Fixing Crushed Blacks: HDR On Wayland With GNOME/Kodi

Hey there, tech enthusiasts and media lovers! Ever fired up some gorgeous HDR content on your Linux rig, running Wayland with GNOME, only to be met with scenes that look a little... too dark? Like the shadows are just swallowing all the detail? If you've been battling crushed blacks when trying to enjoy your high dynamic range media, especially within applications like Kodi, you're definitely not alone. It's a frustrating experience, right? We invest in these amazing HDR displays, hoping for vibrant colors and incredible contrast, but sometimes the software side of things just doesn't play nice. This isn't just a minor annoyance; it fundamentally degrades the viewing experience, making dark scenes unwatchable and robbing HDR of its true potential. We're talking about losing subtle details in shadows, where everything just merges into a murky, indistinct blob instead of providing depth and realism. This issue often surfaces in specific environments, and our focus today is on the intriguing interplay between Kodi, Wayland, and GNOME, and how they handle HDR content. We'll dive deep into why this might be happening, what it looks like, and what the community is doing to try and figure it out. Understanding the technical underpinnings, from display calibration to Wayland protocols, is key here, and we're going to break it down so it's easy to grasp. So, buckle up, because we're about to demystify the dark corners of HDR playback on Linux!

Understanding the Crushed Blacks Problem in HDR on Wayland/GNOME

So, what exactly are crushed blacks, and why are they such a headache, especially with HDR content on Wayland/GNOME? Basically, when blacks are crushed, it means that the darkest parts of an image — those subtle shades of gray and deep black — are all being displayed as a uniform, undifferentiated pure black. Instead of seeing distinct levels of darkness, with details still visible in shadows, everything just merges into one big, dark blob. For HDR, which thrives on a vast range between the brightest whites and the darkest blacks, this is a major problem. It completely undermines the whole point of HDR, which is to reveal more detail and create a more immersive, lifelike image. You're losing information, guys, and that's just no fun when you've got a fantastic display designed to show you every single nuance. When your display isn't correctly interpreting the black levels of an HDR signal, it essentially clips all information below a certain threshold, turning varying shades of dark gray into absolute black. This isn't just about aesthetics; it's about accuracy. Content creators meticulously grade their films and shows to ensure details are preserved in every part of the image, and crushed blacks destroy that artistic intent. Think of a night scene in a movie: you should still be able to distinguish tree branches against a moonlit sky, or the texture of a character's dark clothing. With crushed blacks, all of that just disappears into a flat void. The frustration really kicks in when you realize your setup should be capable of displaying these details, making you wonder where the bottleneck is. This issue points to a deeper conflict or misconfiguration within the rendering pipeline, from the media player (like Kodi) to the display server (Wayland) and its compositor (GNOME's Mutter). The goal of HDR is to expand the dynamic range, providing a more faithful reproduction of real-world light and shadow. When blacks are crushed, that expansion is effectively curtailed at the lower end, leading to a much flatter, less engaging picture. It's like having a top-of-the-line sports car but being stuck in first gear; you're not getting the full performance. So, when we see this happening with HDR content, it's a strong indicator that something is amiss in how the system is handling the extended brightness and color information that HDR provides. Pinpointing the exact source of this issue is critical for achieving that pristine, uncompromised HDR experience we all crave on our Linux machines. Without proper black level reproduction, the contrast, depth, and overall realism of HDR content are severely compromised, turning what should be a breathtaking visual into a disappointing washout of dark tones. It's a common stumbling block in the relatively nascent world of HDR on desktop Linux, and one that many users and developers are actively working to overcome. We're all in this together, striving for that perfect picture!

Diving Deep into HDR Calibration: What Went Wrong?

Let's get into the nitty-gritty of HDR calibration and figure out exactly what went wrong with our crushed blacks situation. Our fellow user wisely used some crucial calibration videos, specifically the Black Clipping 4k UHD HDR 10 Calibration and White Clipping 4K UHD HDR 10 T.V. Calibration from YouTube. These aren't just random test patterns, folks; they're vital tools for making sure your display is showing HDR content correctly. For the black clipping test, the goal is to see bar 68 barely flashing, while bar 64 should completely blend into the background. This indicates that your display is correctly rendering the darkest possible shades without losing information. Now, here's where the problem becomes crystal clear: with the black-hdr.webm video playing in Kodi, bar 68 was blending into the background, and the flashing only became visible around bars 76/80. This, my friends, is a classic symptom of crushed blacks! Your system is effectively treating lighter shades of black as pure black, eliminating detail that should be there. It's like your display is being too aggressive with its darkness, pushing everything below a certain luminance level into an absolute zero, which is not what HDR is about. This observation is super critical because it tells us precisely where the clipping is occurring in the HDR signal path. The fact that bar 68, which should be barely perceptible, is completely gone, signifies a significant loss of shadow detail. This is often caused by incorrect EOTF (Electro-Optical Transfer Function) mapping, or a misinterpretation of the HDR metadata by the display driver or the compositor. It means that the full range of dark values intended by the HDR standard isn't being utilized, leading to that flat, un-dynamic look in dark scenes. In contrast, the black-sdr.webm video looked correct, with bar 64 blending and bar 68 visibly flashing. This tells us a couple of important things: first, your display itself likely can handle proper black levels, and second, the problem seems to be specifically tied to how HDR content is processed within the Wayland/GNOME/Kodi stack. It's not a generic display issue; it's an HDR-specific one. Furthermore, the white-hdr.webm test looked correct, with all bars flashing, which is great because it means the brightest parts of HDR are generally fine. Similarly, white-sdr.webm showed expected clipping at bars 724-756, which is normal for SDR content as it has a much more limited dynamic range. So, the core issue is firmly rooted in the lower end of the dynamic range for HDR. This consistency across different tests, showing correct behavior for SDR and white HDR, but a failure for black HDR, strongly points towards a specific handling error in the HDR black level processing. The discrepancy highlights that the issue isn't with the display's inherent capabilities, but rather with the software pipeline responsible for translating the HDR signal from the content to the display's output. This could involve anything from the media player's internal color management, to the GPU driver's interpretation of HDR metadata, or even the Wayland compositor's handling of color-management-v1 protocols. Understanding this distinction is key to isolating the problem and, hopefully, finding a solution. It's like diagnosing a car engine: if only one part isn't working right while everything else is, you can narrow down your search significantly. The detailed observations from these calibration videos provide invaluable clues, guiding us towards the specific component or interaction that's misbehaving in the chain. These precise observations form the bedrock of any successful troubleshooting effort, giving us concrete data rather than vague assumptions about the issue at hand. It truly helps to pinpoint the specific area of concern and prevent us from chasing down red herrings!

Exploring Potential Culprits: Kodi, GNOME, Mutter, and Wayland Protocols

Alright, folks, it's time to play detective and explore the potential culprits behind these persistent crushed blacks in HDR content on Wayland/GNOME. The original report hinted that the problem might lie within Kodi, GNOME/Mutter, or even the Wayland protocols themselves. This is where things get super interesting and a bit technical, but bear with me! AFAIK, HDR negotiation on Wayland happens through a relatively new protocol called color-management-v1. This protocol is designed to allow applications to communicate their color space and HDR requirements to the Wayland compositor (in GNOME's case, Mutter), which then ideally passes that information to the display. The very existence of this new protocol suggests that HDR support on Wayland is still evolving and might not be fully mature or perfectly implemented across all components. It's entirely possible that Mutter, GNOME's compositor, doesn't yet implement this protocol correctly, or perhaps Kodi isn't interacting with it in the precise way Mutter expects. This kind of handshake between an application and the display server is crucial for correct HDR output, and any miscommunication can lead to issues like crushed blacks. When Kodi requests a specific HDR color space and luminance range, Mutter needs to interpret that, apply any necessary transformations, and then correctly instruct the GPU and display. If there's a disconnect, the display might revert to an SDR-like processing of an HDR signal, or incorrectly clamp the black levels. The fact that disabling VAAPI (Video Acceleration API) in Kodi made no difference is noteworthy. This suggests the problem isn't necessarily with the hardware video decoding itself, but rather with the rendering or display pipeline after decoding. However, disabling HDR in Kodi did result in black-hdr.webm looking more correct (though still a bit brighter than black-sdr.webm), which is a huge clue! It indicates that when Kodi thinks it's sending an HDR signal, something in the chain is getting messed up, but when it sends an SDR signal (even for HDR content), the black levels become more acceptable. This points strongly to the HDR signaling or processing being the root cause of the issue. Now, let's bring in mpv, another popular media player, for some crucial comparison. The original tests showed that mpv v0.40.0 delivered correct black levels with the GPU drivers when using --vo=gpu or --vo=gpu-next. This is fantastic news because it confirms that the underlying GPU drivers and the display itself are capable of rendering HDR correctly! This immediately shifts our suspicion away from the GPU driver and towards the Wayland compositor or the specific display output method being used. But here's the kicker: mpv was also too dark (just like Kodi) when using --vo=dmabuf-wayland. And get this: even the SDR version with dmabuf-wayland was a bit brighter than Kodi but still clipped at bar 64. This is a critical piece of the puzzle! dmabuf-wayland is an experimental Wayland video output backend that allows direct buffer sharing with the compositor. Its similar problematic behavior to Kodi, and its