command: add primaries, transfer and video_colorspace to overlay-add by kasper93 · Pull Request #18395 · mpv-player/mpv

kasper93 · 2026-08-20T18:31:53Z

No description provided.

The union member is only valid for SUBBITMAP_LIBASS. The resulting data is only read for PL_OVERLAY_MONOCHROME, so there was no risk of using garbage data, but we can make it explicit.

No functional changes.

The flag was lost when replacing the result with the packed image.

Bitmap subtitles muxed in media file are generally the same colorspace as video. Generic overlays may not be.

kasper93 · 2026-08-20T18:32:33Z

/cc @na-na-hi @iwalton3 @posilash

iwalton3 · 2026-08-20T22:40:01Z

I can confirm this fixes the SDR usecase again.

(Compare to broken version.)

It also appears to work with a patched thumbfast too to emit actual HDR thumbnails on an HDR display, although I need to fix some local issues to actually test mpv with real HDR support not through a screengrab proxy.

Edit: I got my HDR display and Nvidia drivers working, HDR thumbnails are working end-to-end!

kasper93 · 2026-08-20T22:59:11Z

@posilash: You removed the comment, do you want image_subs_hdr_peak to affect overlays too, same as subtitles? I think it generally makes sense (current pr), the image_subs_hdr_peak option itself is bit silly anyway.

posilash · 2026-08-20T23:01:34Z

@kasper93 I was running more tests, wanted concrete numbers to back my suggestion.

posilash · 2026-08-20T23:07:04Z

+        // Muxed image subtitles and overlays tagged with video_colorspace
+        // are in the video's colorspace
+        color = src->params.color;
+        if (pl_color_transfer_is_hdr(color.transfer)) {


Suggested change

if (pl_color_transfer_is_hdr(color.transfer)) {

if (!b->bgra.video_color_space && pl_color_transfer_is_hdr(color.transfer)) {

The docs for video_colorspace say the overlay is interpreted in the video's colorspace "including HDR metadata", but the metadata gets replaced by --image-subs-hdr-peak here. Printing color at the end of bgra_overlay_color(), just before it returns, on a BT.2020/PQ file with video_colorspace=true and default options:

overlay prim=6 trc=12 max_luma=1000.0 min_luma=0.000000 video prim=6 trc=12 max_luma=10000.0 min_luma=0.000001 memcmp over the whole pl_color_space: not equal

With the fix applied:

overlay prim=6 trc=12 max_luma=10000.0 min_luma=0.000001 video prim=6 trc=12 max_luma=10000.0 min_luma=0.000001 memcmp over the whole pl_color_space: equal

Image subtitles keep the clamp, i checked by setting item->video_color_space on an overlay-add bitmap so it takes that path, and it still responds to --image-subs-hdr-peak.

One thing to check: else if (ref_luma) below becomes reachable for these overlays with the change. ref_luma is 0 here unless --hdr-reference-white is set, and i couldn't measure a difference either way, but you'd know whether it matters.

The docs for video_colorspace say the overlay is interpreted in the video's colorspace "including HDR metadata", but the metadata gets replaced by --image-subs-hdr-peak here.

It's stated explicity

video_colorspace (default: no) interprets the overlay in the video's colorspace, including HDR metadata, so it is tone mapped exactly like the video. The overlay is treated like image subtitles (see --image-subs-hdr-peak).

I will think tomorrow what we can do about overlays better.

The overlay is treated like image subtitles (see --image-subs-hdr-peak).

I think those two sentences are contradictory, instead of one qualifying the other. "tone mapped exactly like the video" and "treated like image subtitles" can't both hold, since the image subtitle path is defined by replacing the peak. Either way the docs will need a clearer statement once you've settled what the behaviour should be.

Also, wrt the docs, <primaries> <transfer> <video_colorspace> should be [<primaries>] [<transfer>] [<video_colorspace>] since they're optional arguments.

kasper93 · 2026-08-20T23:07:37Z

I have not added it here, but we might need max luminance parameter for HDR overlays. I think single luminance value would be enough in practice to get us most of the use cases.

posilash · 2026-08-20T23:18:46Z

I have not added it here, but we might need max luminance parameter for HDR overlays. I think single luminance value would be enough in practice to get us most of the use cases.

Yes, this was part of my discussion with @llyyr in #18394

Either way, explicit HDR transfers would need to include the peak metadata (from where?), or else the overlay blowout issue would persist.

posilash · 2026-08-20T23:25:01Z

@posilash: You removed the comment, do you want image_subs_hdr_peak to affect overlays too, same as subtitles? I think it generally makes sense (current pr), the image_subs_hdr_peak option itself is bit silly anyway.

No, I don't think image_subs_hdr_peak should affect video_colorspace overlays. For image subtitles the clamp earns its place, they're authored at graphics white with no relation to the video's peak. video_colorspace is the client saying the bitmap is already in the video's colorspace, with the metadata, so replacing the peak contradicts what it was told.

kasper93 · 2026-08-20T23:30:59Z

For image subtitles the clamp earns its place, they're authored at graphics white with no relation to the video's peak.

That's dubious. And the actual clamp is a workaround for badly mastered homebrew PGS subtitles. Hardware blu-ray players does not tone map subtitles, they are compositioned onto video, and would be tone mapped with video as single image.

posilash · 2026-08-20T23:35:43Z

For image subtitles the clamp earns its place, they're authored at graphics white with no relation to the video's peak.

That's dubious. And the actual clamp is a workaround for badly mastered homebrew PGS subtitles. Hardware blu-ray players does not tone map subtitles, they are compositioned onto video, and would be tone mapped with video as single image.

I didn't know about that to be fair, i had the rationale wrong then. But that makes the case stronger though, if the clamp is a workaround for badly mastered PGS then it's the last thing you'd want applied to a bitmap the client explicitly said is in the video's colorspace.

No rush, i'll leave the suggestion there for whenever you look at it.

Split the parts into runs of consecutive parts that share a colorspace and render each run as a separate overlay referencing the same texture.

Add primaries, transfer, max_luma and video_colorspace arguments. Allows tagging the colorspace of the overlay bitmap instead of assuming sRGB. video_colorspace interprets the bitmap in the video's colorspace, so it is tone mapped exactly like the video. max_luma overrides the luminance peak of the bitmap. Currently only vo_gpu_next honors these parameters. vo_gpu keeps its sRGB assumption regardless of the tag. Fixes mpv-player#10678

kasper93 · 2026-08-21T10:20:38Z

I've added max_luma parameter, the name is consistent with other parts of code. This will overwrite luminance value in HDR metadata. At the same time, this is the only piece exposed. It's arguably the important one. Adding all the rest would be annoying for command itself. Not sure it's really fessible with current design.

posilash · 2026-08-21T10:26:50Z

Looks good to me. You're right it doesn't make sense to add all the other hdr params.

posilash · 2026-08-21T10:48:46Z

All test are good on my end. It's ready to merge in my opinion.

na-na-hi

Behavior looks OK.

na-na-hi · 2026-08-21T11:28:02Z

    on the OSD. ``no-osd`` has no effect on this command.

-``overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride> <dw> <dh>``
+``overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride> [<dw> [<dh> [<primaries> [<transfer> [<max_luma> [<video_colorspace>]]]]]]``


Probably better to make video_colorspace the first parameter to avoid needing to specify other parameters that will be overriden.

kasper93 and others added 5 commits August 20, 2026 20:16

vo_gpu_next: don't read libass.color for non-libass parts

d3ac2c7

The union member is only valid for SUBBITMAP_LIBASS. The resulting data is only read for PL_OVERLAY_MONOCHROME, so there was no risk of using garbage data, but we can make it explicit.

vo_gpu_next: split update_overlays into helper functions

8e03c39

No functional changes.

sub/packer: preserve video_color_space when packing to RGBA

8933e6c

The flag was lost when replacing the result with the packed image.

vo_gpu_next: use video colorspace for overlays only when requested

d9a21f5

Bitmap subtitles muxed in media file are generally the same colorspace as video. Generic overlays may not be.

sub/sd_lavc: zero-initialize sub_bitmap entries

dd4798b

posilash reviewed Aug 20, 2026

View reviewed changes

kasper93 added 2 commits August 21, 2026 12:14

vo_gpu_next: support per-part overlay colorspace

ee9f4d3

Split the parts into runs of consecutive parts that share a colorspace and render each run as a separate overlay referencing the same texture.

kasper93 force-pushed the overlay-add-csp branch from 141b34c to 2bd3678 Compare August 21, 2026 10:18

na-na-hi reviewed Aug 21, 2026

View reviewed changes

	if (pl_color_transfer_is_hdr(color.transfer)) {
	if (!b->bgra.video_color_space && pl_color_transfer_is_hdr(color.transfer)) {

Uh oh!

Conversation

kasper93 commented Aug 20, 2026

Uh oh!

kasper93 commented Aug 20, 2026

Uh oh!

iwalton3 commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kasper93 commented Aug 20, 2026

Uh oh!

posilash commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

posilash Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

posilash Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

kasper93 Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

posilash Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kasper93 commented Aug 20, 2026

Uh oh!

posilash commented Aug 20, 2026

Uh oh!

posilash commented Aug 20, 2026

Uh oh!

kasper93 commented Aug 20, 2026

Uh oh!

posilash commented Aug 20, 2026

Uh oh!

kasper93 commented Aug 21, 2026

Uh oh!

posilash commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

posilash commented Aug 21, 2026

Uh oh!

na-na-hi left a comment

Choose a reason for hiding this comment

Uh oh!

na-na-hi Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

iwalton3 commented Aug 20, 2026 •

edited

Loading

posilash commented Aug 20, 2026 •

edited

Loading

posilash Aug 20, 2026 •

edited

Loading

posilash commented Aug 21, 2026 •

edited

Loading