Image Overlays

Add a logo, watermark, or other local PNG on top of the video without modifying the source media.

Overlays are session content. The player starts with none. Only this process's overlay_set commands add them. Restarting the player does not restore them. There is a hard cap of 32 overlay ids: a new id at the cap is refused; existing ids are never evicted to make room.

This is an HTTP-only extension. It is not part of the stable playback 10 commands or OSC. There is no named exhibition consumer yet.

Workflow

Use overlay_set as a complete replace by id. Send every required field each time. Optional fields use fixed defaults (opacity 1.0, visible true, z_order 0). The player does not patch omitted fields from the previous object.

For visual setup, use the debug panel Overlay tab, then copy the flat overlay_set envelope.

path is a local image file only. Relative paths resolve under control.media_root. Remote URLs are rejected. After a new overlay_set, that id leaves the old texture immediately (pending/loading/error frames are not drawn, and a failed load does not restore the previous image). Encoded files larger than 16 MiB, images wider/taller than 4096 px, or decoded images over 16M pixels (including a global 16M-pixel budget across all overlays) enter Error without drawing. Unknown fields are rejected.

z_order orders overlays among themselves. Ties use id lexicographic ascending (smaller id is drawn first).

Need on-screen text? Pre-render a PNG (or other local image) and place it with overlay_set. The public text OSD commands (text_*) were removed.

Commands

Use overlay_set, overlay_remove, and overlay_clear through POST /api/extensions/command. Read the current inventory with HTTP-only GET /api/extensions/overlays. That query returns a snapshot and is not a command; the old overlay_list command is gone.

{ "cmd": "overlay_set", "params": { "id": "logo", "path": "logo.png", "rect": {"x": 0.85, "y": 0.05, "w": 0.1, "h": 0.1}, "opacity": 1.0, "visible": true, "z_order": 10 } }
{ "cmd": "overlay_remove", "params": { "id": "logo" } }
{ "cmd": "overlay_clear" }

For the exact schema, use the Command Reference.

Previous / Next

• Previous: Calibration Patterns
• Next: Projection Mask