Automatic per-source HDR/SDR tone-mapping with an HDMI matrix, Home Assistant and Kodi

[berezovskyi-oleksandr]

I wanted HDR tone mapping to be fully deterministic and content-aware: a known, correct state for every source and every title, switched automatically rather than left to runtime detection. Getting there took two small tools I wrote and open-sourced, so I'm sharing both the approach and the code in case it helps anyone running multiple HDR sources.

I have two sources feeding the TV through an EZCOO 4x2 HDMI matrix (mirrored into the grabber): an Ugoos X4 / CoreELEC box and a gaming PC. Tone mapping is driven by two layers

• Coarse layer - Home Assistant, keyed to the matrix input. Switching the matrix to the gaming PC (always HDR) forces tone mapping on; switching to the CoreELEC box forces it off, because the Kodi UI itself is SDR. To make the matrix controllable from HA at all, I wrote ezcoo-usb-control - a small service that bridges the EZCOO's USB-serial control protocol to Home Assistant over MQTT, so HA can both switch inputs and read the active one.
• Fine layer - a Kodi service add-on, only on the CoreELEC box. I wrote
  service.video.hdrnotify: on playback start it reads VideoPlayer.HdrType and calls HyperHDR's videomodehdr JSON-RPC directly, so an HDR/Dolby Vision title flips tone mapping on and an SDR one keeps it off, then resets to SDR when playback stops.

The two never fight: when a movie starts on the box the matrix input didn't change, so the HA automation has no trigger and never runs - it only set the SDR baseline earlier, for the Kodi menu. The add-on owns the per-title decision from there. End result: SDR menus stay SDR, HDR/DV content lights up correctly, and every transition is driven by an explicit event rather than guessed at.

The two tools, both open-source and probably reusable on their own:

• ezcoo-usb-control (EZCOO HDMI matrix -> Home Assistant over MQTT):
  https://gitea.berezovskyi.dev/oleksandr/ezcoo-usb-control
• service.video.hdrnotify (Kodi -> HyperHDR HDR-type bridge):
  https://gitea.berezovskyi.dev/oleksandr/service.video.hdrnotify

The rest of the rig, written up in full at the links below:

• P010 on x86. No pre-patched image like the Pi, so I built awawa-dev's P010_for_V4L2 as a DKMS module. Grabber is a Ugreen 25173.
• Matrix, not splitter, kept at 4K. I need input switching, and the matrix passes 4K untouched so the grabber does the 1080p P010 itself, rather than letting the 8-bit matrix scaler into the capture path.
• 3.3 V to 5 V level shifting with a 74AHCT125 between an RP2040 (HyperSerialPico) and the SK6812 strip.
• Host migration. The original Raspberry Pi 4 died; everything now runs on a fanless Dell Wyse 3040 (x86) and survived the swap intact.

Write-ups:

• The rig (wiring, HyperHDR config, the HA automations and the Kodi add-on):
  https://blog.berezovskyi.dev/notes/hyperhdr-ambient-lighting/
• Rebuilding the host on the Wyse 3040:
  https://blog.berezovskyi.dev/notes/hyperhdr-host-wyse3040-dietpi/

Thanks to @awawa-dev and everyone on HyperHDR - great project.

[anthonylavado]

I just wanted to thank you for creating the USB control utility. I had been doing calls over SSH with a script to execute this, and now there's something much better to use!