Watermarking and overlay rendering is the pipeline operation of compositing a graphic — channel logo, broadcast bug, copyright tag, viewer-specific identifier — onto video frames during encoding. It's a straightforward pixel-compositing task at the FFmpeg layer with annoying real-world details: positioning across multiple resolutions, anti-aliasing, transparency handling, time-windowed overlays for editorial workflows, and the separate concern of forensic (invisible) watermarking. This page is the engineering reference.
What watermarking and overlays cover
The umbrella term "watermarking" spans several distinct operations:
Visible overlay (logo, bug, channel ident) — render a graphic onto frames. The most common case in broadcast/streaming pipelines.
Burn-in subtitle — render text onto frames for forced-narrative scenes or always-on caption delivery (covered separately under burn-in vs soft subtitles).
Time code burn-in — render frame timecode onto frames for editorial review or QC workflows.
Forensic (invisible) watermarking — embed an imperceptible signal into video pixels for piracy traceability. Pixel-level mathematical operations rather than overlay compositing. Different operational concern.
Time-windowed overlays — overlay graphic only during specific segments of the video (sponsor logos for the first 30 seconds, etc.).
This page focuses on visible overlay rendering. Forensic watermarking is an adjacent topic with very different implementation and operational characteristics.
Why overlay graphics get rendered into video
Common reasons:
- Channel branding — TV networks render the channel logo as a translucent "bug" in a corner.
- Live broadcast identification — sports overlays (scoreboards, ticker), news lower-thirds.
- Copyright marking — "© Studio 2026" tag on archived content.
- Beta / preview marking — "PREVIEW" overlay on pre-release content.
- Personalized identifiers — per-customer or per-session watermark for content licensing audit trails.
- Sponsorship — paid sponsor logos for specific time windows.
- Regional adaptations — different graphics for different distribution regions.
The implementation pattern is consistent: a transparent PNG (or sequence of PNG frames for animated overlays) is composited onto video frames during encode.
ffmpeg overlay filter basics
The core operation:
ffmpeg -i video.mp4 -i logo.png -filter_complex \
"[0:v][1:v]overlay=10:10" \
-c:a copy output.mp4
This composites logo.png at position (10, 10) — 10 pixels from the top-left corner — onto every frame of video.mp4.
The overlay filter syntax:
overlay=x_position:y_position[:other_options]
Position can be a literal value (10:10) or an expression (W-w-10:H-h-10 to position 10 px from bottom-right, where W,H are main video dimensions and w,h are overlay dimensions).
For most production pipelines, the corner-positioning expression is what you want — it auto-adjusts as the main video resolution changes.
Common positioning patterns
Top-left corner with 10px margin:
overlay=10:10
Top-right corner with 10px margin:
overlay=W-w-10:10
Bottom-right corner with 10px margin:
overlay=W-w-10:H-h-10
Bottom-left corner with 10px margin:
overlay=10:H-h-10
Centered:
overlay=(W-w)/2:(H-h)/2
Bottom-center (lower-third banner positioning):
overlay=(W-w)/2:H-h-50
For pipelines producing multi-resolution ABR ladders, percentage-based positioning is the operational best practice — hardcoded pixel offsets that work at 1080p look wrong at 540p.
Multi-resolution overlay scaling
A common bug: overlay graphic authored at one resolution looks wrong on different ladder rungs.
The problem: a 200×100 px logo positioned with overlay=W-w-10:H-h-10 on a 1080p source occupies a small corner. The same logo on a 540p downscaled stream occupies a much larger fraction of the frame (because the logo wasn't scaled).
The fix: scale the logo to the target resolution as part of the overlay graph:
ffmpeg -i video.mp4 -i logo.png -filter_complex \
"[1:v]scale=iw*0.1:-1[scaled_logo]; \
[0:v][scaled_logo]overlay=W-w-10:H-h-10" \
output.mp4
scale=iw*0.1:-1 scales the logo to 10% of the main video width while preserving aspect ratio. The result: the logo is the same proportional size on every ladder rung.
For pipelines producing multiple variants from one source, this scaling approach keeps the logo size consistent across the ladder — the user sees the same proportional logo at every resolution.
Time-windowed overlays
Overlay only during specific time segments:
ffmpeg -i video.mp4 -i logo.png -filter_complex \
"[0:v][1:v]overlay=W-w-10:H-h-10:enable='between(t,0,30)'" \
output.mp4
enable='between(t,0,30)' shows the overlay only between t=0s and t=30s.
For sponsor overlays (logo shown for the first 30 seconds), this is the standard pattern. For per-segment dynamic overlays (different sponsor in different ad-pod-relevant segments), the workflow gets more complex — typically expressed as multiple between() conditions or as separate encode passes with different overlay configurations per pass.
Animated overlays
For overlays with animation (subtle pulse, animated logo, ticker):
Approach 1: Animated PNG sequence:
ffmpeg -i video.mp4 -framerate 30 -i logo_%04d.png -filter_complex \
"[0:v][1:v]overlay=W-w-10:H-h-10" \
output.mp4
The -framerate 30 -i logo_%04d.png reads a sequence of numbered PNG frames at 30 fps. The overlay filter cycles through them in sync with the main video.
Approach 2: Movie filter with looped video:
ffmpeg -i video.mp4 -filter_complex \
"movie=animated_logo.mov:loop=0[ovl]; \
[0:v][ovl]overlay=W-w-10:H-h-10" \
output.mp4
The movie=...:loop=0 loops the overlay video file indefinitely. Useful for short animated loops over longer main video.
For production pipelines, animated overlays add meaningful encoding complexity and compute cost. Use sparingly.
Transparency handling
Overlay graphics typically use PNG with alpha channel for transparent regions. The overlay filter respects alpha:
- Fully opaque pixels (alpha=255): replace the underlying video pixel.
- Fully transparent pixels (alpha=0): preserve the underlying video pixel.
- Partially transparent pixels (0 < alpha < 255): blend per the alpha ratio.
For "bug" overlays (translucent channel logos), use partial transparency — typical channel bugs are 50-80% opacity to remain readable but not fully obscure underlying content.
For pipelines authoring overlay graphics, the relevant editorial concern is opacity tuning — too opaque obscures content, too transparent isn't readable. Typical channel bugs land around 60-70% opacity.
Color management with overlays
A subtle issue: overlay graphics are typically authored in sRGB color space, but video pipelines often process content in YUV (Rec.709 or Rec.2020). The overlay filter handles RGB → YUV conversion automatically, but the conversion can produce slightly different colors than expected.
For pipelines with strict color management (premium streaming, broadcast contribution), explicit color-space handling is the answer:
ffmpeg -i video.mp4 -i logo.png -filter_complex \
"[1:v]format=rgba,colorspace=bt709:iall=bt601-6-625:fast=1[colorlogo]; \
[0:v][colorlogo]overlay=10:10" \
output.mp4
Explicit color-space conversion via the colorspace filter ensures the logo's colors render correctly in the target color space.
For HDR pipelines (Rec.2020), additional consideration: the overlay logo is typically SDR-authored, so it needs tone-aware compositing into HDR content. Naive compositing of an sRGB logo onto a Rec.2020 frame produces a logo that looks washed out or color-shifted. Premium pipelines author HDR-specific overlay variants.
Performance considerations
CPU overlay rendering is fast — overlay compositing is a small per-pixel operation. For 1080p content, overlay adds <5% to encode wall time on modern CPUs. For 4K content, the cost is proportionally larger but still typically negligible.
GPU overlay (NVENC) is faster but only meaningful in pipelines where the encode is also GPU-accelerated. For CPU encode pipelines, CPU overlay is the simpler choice.
For animated overlays, performance depends on overlay frame source — looped video is cheap; PNG sequence has per-frame decode cost; complex graph filters can be expensive.
Common watermarking bugs
Bug 1: Logo positioned off-screen on different resolutions.
Hardcoded pixel offsets (overlay=10:10) that work at 1080p produce wrong positioning at 540p (logo is positioned correctly but is now much larger relative to frame). Use percentage-based positioning or scale the logo to target resolution.
Bug 2: Logo too dim or too bright.
The overlay PNG was authored on a different display calibration than the target. Verify on actual playback devices.
Bug 3: Transparency artifacts.
Some overlay PNG files have premultiplied alpha incorrectly handled. Anti-aliased edges look jagged. Re-export the PNG with the correct alpha format.
Bug 4: Animated overlay desync.
Overlay animation runs at different framerate than main video. Specify -framerate explicitly when reading PNG sequence.
Bug 5: Color-shifted logo on HDR.
SDR-authored logo composited onto HDR content looks washed out. Author HDR-specific logo variants for HDR streams.
Bug 6: Logo encoding overhead.
Overlay rendering happens at every frame; for sources that change minimally (talking head with static background), the encoder has to spend bits on the overlay region every frame. Modest cost for static logos; meaningful cost for animated overlays in low-motion content.
Bug 7: Time-windowed overlay timing drift.
enable='between(t,0,30)' evaluates against PTS; if PTS drifts (live workflows with discontinuities), the time window may not align with the intended editorial segment. For high-stakes time-windowed overlays, verify timing on output.
Forensic watermarking (different topic)
Forensic watermarking embeds an imperceptible signal into video pixels — used for piracy traceability ("this leaked content traces back to subscriber X").
Implementation differs from overlay rendering:
- Mathematical pixel modification (DCT-domain or spatial-domain watermarking) rather than alpha compositing.
- Designed to survive transcoding, scaling, format conversion — robust against the operations that piracy might apply.
- Per-customer or per-session unique — embeds an identifier that's traceable.
- Detection requires the watermarking key — extracting the watermark from suspect content uses cryptographic operations.
Common forensic watermarking systems: Verimatrix Watermarking, NAGRA NexGuard, MarkAny.
For pipelines requiring forensic watermarking, integration is typically via a vendor-supplied SDK rather than ffmpeg-native filtering. The watermarking is per-customer or per-session, which requires per-output encode (not just one encode shared across customers).
The combination of forensic watermarking + per-customer encoding + premium content protection adds significant pipeline complexity. Most premium streaming services with anti-piracy concerns deploy forensic watermarking; most volume streaming services don't.
Operational considerations
Things that matter for watermarking in production:
- Source authoring — overlay graphics need to be authored at high-enough resolution to scale down cleanly to target resolutions.
- Color authoring — author overlay graphics in the target color space (sRGB for SDR, BT.2020 for HDR).
- Time alignment — for time-windowed overlays, verify timing on actual output.
- Multi-rendition consistency — same overlay should appear consistently across ABR ladder rungs (proportional sizing, consistent opacity).
- Per-content overlay — for editorial overlays specific to certain assets, the workflow needs per-asset overlay configuration.
- Live overlays — for live workflows, overlay graphics are typically static or animated loops; dynamic overlays (real-time scoreboards, etc.) require integration with overlay-data sources outside the standard pipeline.
- Editorial QC — verify overlay output matches editorial intent before publishing; manual QC catches subtle issues.
What MpegFlow does with watermarking and overlays
MpegFlow's DAG runtime expresses overlay rendering as part of the FfmpegExecutor stage's filter parameters. FilterParams::Overlay is a typed first-class parameter on the encode stage with options for the overlay-source URL, position (preset corners or explicit coordinates), scale (target proportion of frame), and time window. The partitioner persists each rendition stage to job_stages with explicit dependency tracking and per-stage retry; sibling cancellation propagates fatal failures across rendition stages.
For multi-resolution ABR ladders, the partitioner emits parallel sibling rendition stages with per-rendition overlay parameters; percentage-based scaling is the typical approach so the overlay maintains consistent visual proportion across the ladder. For per-asset overlay (different graphic per content piece), the workflow YAML accepts per-asset overlay configuration; the encode stage's overlay parameters are populated from workflow inputs.
For time-windowed overlays (sponsor logos shown only in opening segments, time-coded watermarks), the time-window expression is part of the filter parameters; the encode stage applies the overlay only during the specified segments.
Forensic watermarking is not currently a pipeline-native operation in MpegFlow. Customers requiring forensic watermarking (per-subscriber piracy traceability) integrate with vendor SDKs (Verimatrix, NexGuard, MarkAny) outside the MpegFlow pipeline boundary. Pipeline-native forensic watermarking would require per-customer encode paths and vendor-specific SDK integration; that's roadmap, not currently shipped.
For animated overlays, the encode stage can read PNG sequences or looped video files; the typed parameters expose the relevant flags. For HDR-aware overlays (logo authored in HDR-appropriate color space), the encode stage handles the color-space conversion via standard FFmpeg filter chains.
The strict-broker security model handles overlay rendering like any pipeline payload — workers carry no ambient credentials; content access (main video, overlay graphics) flows through short-lived presigned URLs scoped per stage; access is disposed on completion. Overlay graphics aren't typically sensitive in the security sense, but the discipline is consistent across pipeline operations.
For customers building pipelines with branding overlays for the first time, the conversation typically focuses on authoring tooling (where do the overlay graphics come from?), positioning conventions (corners vs custom positions), multi-resolution scaling (proportional sizing across the ladder), and time-windowed editorial requirements (which content needs which overlay during which segment). The pipeline mechanics are well-understood; the editorial workflow integration is where customer-specific work happens.
The general guidance: visible overlay rendering is straightforward FFmpeg-layer work that integrates cleanly into the encode stage. Use percentage-based scaling for multi-resolution consistency; author overlay graphics in the target color space; verify on actual output. Forensic watermarking is a separate operational concern that requires vendor integration outside the standard pipeline. Don't conflate the two — they solve different problems with different implementations.