Troubleshooting AV1 HDR10+ Metadata Recognition Issues In Jellyfin

by ADMIN 67 views

Hey guys! Have you ever run into a situation where your AV1 HDR10+ videos aren't playing with the HDR10+ metadata in Jellyfin? It's a pretty frustrating issue, especially when you've got the gear to enjoy that sweet, sweet dynamic metadata. This guide dives deep into the AV1 HDR10+ recognition bug in Jellyfin, how to reproduce it, what the expected behavior should be, and how to troubleshoot. Let's get started and figure out how to get those videos looking their absolute best!

Understanding the Issue: AV1 HDR10+ Not Fully Recognized

So, what's the deal? The main problem is that Jellyfin isn't fully recognizing videos encoded with the AV1 codec and HDR10+ metadata. Instead of playing or transcoding these videos with the HDR10+ dynamic metadata, Jellyfin often defaults to standard HDR10. This means you're missing out on the enhanced contrast and color that HDR10+ offers, which adjusts dynamically scene by scene or even frame by frame. It’s like having a super-powered TV but not being able to unleash its full potential. When you play an AV1 HDR10+ video on a compatible device, you expect it to leverage the HDR10+ capabilities. However, because Jellyfin might only recognize it as standard HDR10, you're not getting the optimal viewing experience. This can be particularly noticeable in scenes with a wide range of brightness levels, where the dynamic metadata of HDR10+ would typically shine, providing more detail in both the shadows and highlights. Imagine watching a scene with a bright sky and dark foreground – HDR10+ would ensure both elements are displayed with optimal clarity and detail, whereas standard HDR10 might leave some areas looking either washed out or too dark. The crux of the issue lies in how Jellyfin interprets the video's metadata during playback or transcoding. If the HDR10+ metadata isn't correctly identified, the video stream is processed as regular HDR10, limiting the dynamic range and color accuracy. This problem extends beyond direct playback; it also affects transcoding. When Jellyfin transcodes an AV1 HDR10+ video, ideally, it should preserve the HDR10+ metadata if the output format supports it (like H.265). However, if the metadata isn't recognized initially, the transcoded video will also lack the HDR10+ enhancements, further diminishing the viewing experience. To address this, we need to ensure Jellyfin properly recognizes and handles AV1 HDR10+ metadata, allowing for both direct playback and transcoding with the full dynamic range intact. This involves a combination of correct identification, proper handling during transcoding, and ensuring the playback device can utilize the HDR10+ stream. By tackling these aspects, we can unlock the true potential of AV1 HDR10+ videos within Jellyfin, providing a visually stunning experience for users with compatible hardware.

How to Reproduce the Bug: Step-by-Step Guide

Want to see this issue in action? Here’s how you can reproduce the bug step-by-step:

  1. Get Your Hands on an AV1 HDR10+ Video: The first thing you'll need is a video file encoded in AV1 with HDR10+ metadata. These files are becoming more common as AV1 gains traction, but you might need to do some digging to find one.
  2. Set Up Your Jellyfin Server: Make sure you have Jellyfin installed and running. This issue has been reported in versions 10.10.0 and later, so if you're on an older version, it might be time to update.
  3. Add the Video to Your Library: Place the AV1 HDR10+ video in a directory that your Jellyfin library scans. Once the library scan is complete, the video should appear in your Jellyfin library.
  4. Prepare Your Playback Device: You'll need a TV or device that supports HDR10+ playback. Even if the device doesn't natively support AV1, that's okay – Jellyfin will attempt to transcode the video. The key is that it can handle HDR10+ if the metadata is passed through correctly.
  5. Play the Video: Fire up the Jellyfin client on your playback device and start playing the AV1 HDR10+ video.
  6. Observe the Output: This is where you'll see the bug in action. If Jellyfin isn't correctly recognizing the HDR10+ metadata, your TV will likely display the video in standard HDR10. You might be able to tell this from your TV's picture settings or information display, which often shows the HDR format being used.
  7. Verify Transcoding (If Applicable): If your device doesn't support AV1, Jellyfin will transcode the video. Even in this case, the HDR10+ metadata should ideally be preserved if transcoding to a format like H.265. Check the output to see if HDR10+ is maintained or if it's downgraded to standard HDR. By following these steps, you can easily reproduce the issue and confirm whether you're experiencing the AV1 HDR10+ recognition problem in your Jellyfin setup. This hands-on approach helps in understanding the scope of the bug and provides a solid basis for further troubleshooting and resolution efforts.

Current Bug Behavior: AV1 HDR10+ Recognized as AV1 HDR10

The current bug behavior is quite straightforward, but its impact on video quality is significant. When an AV1 video file includes HDR10+ metadata, Jellyfin isn't fully recognizing this enhanced dynamic range information. Instead, it's treating these videos as standard HDR10. This misidentification has a direct effect on the viewing experience, particularly on devices capable of displaying HDR10+. What's happening under the hood? Jellyfin's media analysis process seems to be the bottleneck. When a video is added to the library, Jellyfin analyzes its metadata to determine the video and audio codecs, resolution, and HDR format, among other things. In the case of AV1 HDR10+ videos, the system correctly identifies the AV1 codec and the presence of HDR, but it's failing to properly register the HDR10+ dynamic metadata. This leads to the video being flagged as HDR10 rather than HDR10+. This misrecognition trickles down into playback and transcoding decisions. During playback, if Jellyfin thinks the video is only HDR10, it won't engage the HDR10+ capabilities of your display. Your TV might still display the video in HDR, but you won't get the frame-by-frame or scene-by-scene dynamic metadata adjustments that HDR10+ offers. This means you're missing out on improved contrast, color accuracy, and overall visual depth. The issue also extends to transcoding scenarios. If your playback device doesn't support AV1, Jellyfin will transcode the video to a compatible format, such as H.264 or H.265. Ideally, if transcoding to a format that supports HDR10+ (like H.265), the HDR10+ metadata should be preserved. However, because Jellyfin doesn't initially recognize the HDR10+ metadata, it's not carried through the transcoding process. The transcoded video ends up being standard HDR, further compounding the loss in visual quality. The implications of this bug are considerable for users who have invested in HDR10+-capable displays and have a library of AV1 HDR10+ content. They're not getting the full benefit of their hardware and media, which can be a frustrating experience. Addressing this issue is crucial for Jellyfin to provide accurate playback and transcoding of AV1 HDR10+ videos, ensuring users can enjoy their content in the best possible quality. The fix likely involves improving Jellyfin's metadata analysis to correctly identify and handle HDR10+ metadata within AV1 streams, as well as ensuring this metadata is preserved during transcoding processes.

Expected Correct Behavior: Full HDR10+ Playback and Transcoding

So, what should happen when you play an AV1 HDR10+ video in Jellyfin? Ideally, the expected behavior is quite clear: a seamless experience that fully leverages the capabilities of HDR10+. Let's break down the correct behavior in detail:

  1. Accurate Metadata Recognition: The first and most crucial step is for Jellyfin to correctly identify the video as AV1 HDR10+. This means the server needs to accurately read the video's metadata and recognize the presence of both the AV1 codec and the HDR10+ dynamic metadata. This recognition is the foundation for everything else that follows. Without it, the rest of the playback chain will be operating on incorrect assumptions, leading to a degraded viewing experience. Proper metadata recognition involves more than just identifying the presence of HDR; it requires distinguishing between different HDR formats, such as HDR10, HDR10+, Dolby Vision, and HLG. HDR10+, in particular, requires specific handling due to its dynamic metadata, which adjusts brightness and contrast on a scene-by-scene or even frame-by-frame basis. Jellyfin needs to parse this metadata correctly to ensure it's used during playback and transcoding.
  2. Direct Playback with HDR10+: If your playback device supports both the AV1 codec and HDR10+, Jellyfin should directly play the video without transcoding. This is the most efficient way to deliver the highest quality, as it avoids any potential loss of quality that can occur during transcoding. When a direct play scenario is possible, Jellyfin should pass the AV1 HDR10+ video stream directly to the playback device, allowing the device to handle the decoding and HDR processing. This ensures that the HDR10+ metadata is fully utilized, providing the intended dynamic range and color enhancements. The playback device then uses this metadata to adjust the display settings in real-time, optimizing the picture for each scene.
  3. Transcoding with HDR10+ Preservation: If your playback device doesn't support AV1 or HDR10+, Jellyfin will need to transcode the video to a compatible format. The key here is that if transcoding to a format that supports HDR10+ (such as H.265), Jellyfin should preserve the HDR10+ metadata. This ensures that the benefits of HDR10+ are retained even after transcoding. Preserving HDR10+ metadata during transcoding is a complex process that requires careful handling of the video stream. Jellyfin needs to decode the AV1 video, process the HDR10+ metadata, and then re-encode the video into the target format while ensuring the metadata is correctly incorporated into the new stream. This might involve using specific transcoding libraries and settings that are designed to handle dynamic HDR metadata.
  4. Fallback to HDR10 When Necessary: In cases where the playback device only supports standard HDR10, Jellyfin should fall back gracefully to HDR10 playback. While this won't provide the full benefits of HDR10+, it's still better than displaying the video in standard dynamic range (SDR). The fallback mechanism should ensure that the core HDR information is retained, even if the dynamic metadata is not used. This might involve stripping the HDR10+ metadata while preserving the overall HDR characteristics of the video, such as the color gamut and transfer function. By implementing these behaviors, Jellyfin can ensure that users get the best possible viewing experience for their AV1 HDR10+ content, regardless of their playback device's capabilities. This requires a combination of accurate metadata recognition, intelligent playback decisions, and robust transcoding capabilities.

Jellyfin Server Version and Environment Details

To provide a clear understanding of the issue, here are the details of the Jellyfin server version and the environment where the bug was observed:

  • Jellyfin Server Version: 10.10.0+ (specifically tested on 10.10.7)
  • Operating System: Unraid
  • Linux Kernel: 6.12.24
  • Virtualization: No
  • Clients: All (The issue is observed across various clients)
  • Browsers: Firefox/Chrome
  • FFmpeg Version: The version that comes bundled with Jellyfin
  • Playback Method: Jellyfin's built-in player
  • Hardware Acceleration: Not in use (no hardware acceleration)
  • GPU Model: Not applicable (no GPU used for transcoding)
  • Plugins:
    • Apple Music
    • Anisearch
    • Anilist
    • Anidb
    • Audiodb
    • Bookshelf
    • Chapter Segments Provider
    • Intro Skipper
    • Local Intro
    • Lrclib
    • Musik Brainz
    • Omdb
    • Open Subtitles
    • Playback Report
    • Report
    • Session Cleaner
    • Skin Manager
    • Studio Images
    • Subtitle Extractors
    • Them songs
    • Webbhock
    • A custom test plugin (currently deactivated)
  • Reverse Proxy: Not in use
  • Base URL: Not configured
  • Networking: Standard network configuration
  • Jellyfin Data Storage: Default Jellyfin data storage location
  • Media Storage: Standard media storage setup
  • External Integrations: None beyond the listed plugins

This comprehensive list gives a detailed snapshot of the environment where the AV1 HDR10+ metadata recognition issue was encountered. The server is running on Unraid, a popular NAS operating system, with a relatively recent Linux kernel. The absence of virtualization and hardware acceleration indicates a straightforward software-based transcoding setup. The extensive list of plugins suggests a feature-rich Jellyfin installation, but none of these plugins are likely to directly interfere with core video processing or metadata handling. The fact that the issue is observed across all clients and browsers points to a server-side problem rather than a client-specific bug. The use of Jellyfin's built-in player further narrows down the potential causes. Given that the FFmpeg version is the one bundled with Jellyfin, it's essential to ensure that this version has proper HDR10+ support for AV1. The lack of a reverse proxy and a custom base URL simplifies the network configuration, eliminating potential networking-related issues. Overall, this detailed environment description provides valuable context for troubleshooting the AV1 HDR10+ metadata recognition issue in Jellyfin. It highlights the key components and configurations that might be relevant to the bug, allowing developers and users to focus their investigation on the most likely areas of concern.

Logs and Additional Information

Jellyfin Logs

Jellyfin logs are essential for diagnosing issues, but knowing which logs to provide can be tricky. To effectively troubleshoot the AV1 HDR10+ metadata recognition issue, you'll want to focus on logs that capture media analysis, playback, and transcoding processes. Here’s a breakdown of what to look for:

  1. Media Analysis Logs: These logs are generated when Jellyfin scans and analyzes your media files. They contain information about how Jellyfin identifies the codecs, metadata, and other properties of your videos. Look for entries related to the specific AV1 HDR10+ video files that are exhibiting the issue. Key phrases to search for include “media info,” “codec information,” “HDR,” and “HDR10+.” If Jellyfin is failing to recognize the HDR10+ metadata, these logs might show that the video is being identified as standard HDR10 or simply HDR without the “+.” You might also see errors or warnings related to metadata parsing or codec detection. To access these logs, navigate to your Jellyfin server's logging directory (usually within the Jellyfin data directory) and look for files with names like jellyfin-metadata.log or similar. The exact filenames can vary depending on your Jellyfin setup.
  2. Playback Logs: Playback logs record the details of video playback sessions, including which video was played, the playback device, transcoding decisions, and any errors encountered during playback. These logs can help you determine whether the HDR10+ metadata is being correctly passed to the playback device. Focus on log entries that correspond to the time when you played the AV1 HDR10+ video. Look for information about the video stream, such as the resolution, frame rate, and HDR format. If Jellyfin is transcoding the video, the logs should indicate the transcoding parameters and whether HDR10+ was preserved during the process. Key phrases to search for include “playback started,” “transcoding,” “HDR,” “HDR10+,” and any error messages. Playback logs are typically found in files named jellyfin-playback.log or similar, located in the Jellyfin logging directory.
  3. Transcoding Logs: If Jellyfin is transcoding the AV1 HDR10+ video, the transcoding logs will provide detailed information about the transcoding process. These logs can help you pinpoint whether the HDR10+ metadata is being lost during transcoding. Look for entries that show the FFmpeg command being used to transcode the video. Examine the command-line parameters to see if they include any options related to HDR or HDR10+ metadata. If the HDR10+ metadata is not being preserved, you might not see any specific HDR10+ related options in the FFmpeg command. Also, check for any errors or warnings during the transcoding process, as these can indicate issues with the transcoding pipeline. Transcoding logs might be in separate files named jellyfin-transcode.log or integrated into the main jellyfin.log file.
  4. General Jellyfin Logs: The main Jellyfin log file (jellyfin.log) can also contain useful information, especially regarding startup, plugin initialization, and overall system behavior. While it might not have as much detail as the specific logs mentioned above, it can provide context and help identify any broader issues that might be affecting Jellyfin's ability to handle HDR10+ videos. When collecting logs, it's helpful to reproduce the issue and then immediately grab the relevant log files. This minimizes the amount of irrelevant information in the logs, making it easier to find the entries related to the AV1 HDR10+ problem. Additionally, be sure to redact any sensitive information, such as API keys or passwords, before sharing the logs. By providing detailed and focused logs, you can significantly aid in diagnosing and resolving the AV1 HDR10+ metadata recognition issue in Jellyfin.

FFmpeg Logs

Unfortunately, no FFmpeg logs were provided in the initial report. FFmpeg logs are crucial when troubleshooting transcoding issues, as they provide a detailed view of the transcoding process. These logs show the exact commands FFmpeg is using, any errors or warnings encountered, and the input and output formats. If Jellyfin is failing to preserve HDR10+ metadata during transcoding, FFmpeg logs can help pinpoint where the issue lies. To gather FFmpeg logs, you typically need to enable verbose logging in Jellyfin's transcoding settings. This will cause Jellyfin to output the full FFmpeg command and its output to the logs. When you reproduce the AV1 HDR10+ issue, make sure to capture the FFmpeg logs for the relevant transcoding session. The logs should show the input video's properties, the transcoding parameters, and the output video's properties. Look for any errors or warnings related to HDR, HDR10+, or metadata handling. If the HDR10+ metadata is not being passed through correctly, you might not see the necessary FFmpeg options in the command line.

Client / Browser Logs

No client or browser logs were provided in the initial report. Client logs can be helpful for diagnosing playback issues, especially if the problem is specific to a particular client or browser. These logs can capture errors, warnings, and other information related to video playback, network communication, and rendering. To gather client logs, you typically need to use the developer tools built into your browser or client application. For example, in Chrome or Firefox, you can open the developer tools by pressing F12 and then navigate to the