Watermark MiddleCenter renders bottom-right — missing switch arm in OverlayWatermarkFilter #503

Closed
opened 2026-07-20 20:16:16 +02:00 by timothy · 4 comments
Owner

Symptom

A watermark configured with WatermarkLocation.MiddleCenter renders in the bottom-right corner, not centered.

Root cause

ErsatzTV.FFmpeg/Filter/OverlayWatermarkFilter.cs:39-49 maps WatermarkLocation to an ffmpeg overlay position with a switch that has no arm for MiddleCenter:

WatermarkLocation.LeftMiddle => $"x={horizontalMargin}:y=(H-h)/2",
_ => $"x=W-w-{horizontalMargin}:y=H-h-{verticalMargin}"   // BottomRight — and MiddleCenter lands here

BottomRight is itself served by that _ => default, so the missing arm is invisible: both values produce identical output and nothing looks obviously broken. MiddleCenter is a real member of the enum (ErsatzTV.FFmpeg/State/WatermarkState.cs).

Why it hasn't bitten

WatermarksScreen.tsx:34 deliberately does not offer MiddleCenter in its location picker (there is an explicit comment saying so, inherited from the Blazor editor), so the value is not reachable through the current UI. It is reachable through the REST API, a hand-edited database, or an imported/legacy row.

Suggested fix

Add the explicit arm — x=(W-w)/2:y=(H-h)/2 — and make the _ => default either explicitly BottomRight or a thrown/logged unsupported case, so the next added enum value fails loudly instead of silently rendering bottom-right. Check the accelerated overlay paths (Cuda/OverlayWatermarkCudaFilter.cs, Qsv/OverlayWatermarkQsvFilter.cs) for the same gap.

Provenance

Found during independent review of the #67 <BugPreview> component, which renders MiddleCenter as genuinely centered — i.e. the SPA preview and the FFmpeg output disagree for this value. #67 keeps the semantically-correct centered preview and does not encode this defect; see the comment in web/src/components/bugPreview.tsx.

Done-when

  • MiddleCenter renders centered in the software overlay path
  • Accelerated (CUDA / QSV) overlay paths checked for the same missing arm
  • Default arm no longer silently absorbs unmapped enum values
  • Adversarial review passed
## Symptom A watermark configured with `WatermarkLocation.MiddleCenter` renders in the **bottom-right corner**, not centered. ## Root cause `ErsatzTV.FFmpeg/Filter/OverlayWatermarkFilter.cs:39-49` maps `WatermarkLocation` to an ffmpeg overlay position with a `switch` that has **no arm for `MiddleCenter`**: ```csharp WatermarkLocation.LeftMiddle => $"x={horizontalMargin}:y=(H-h)/2", _ => $"x=W-w-{horizontalMargin}:y=H-h-{verticalMargin}" // BottomRight — and MiddleCenter lands here ``` `BottomRight` is itself served by that `_ =>` default, so the missing arm is invisible: both values produce identical output and nothing looks obviously broken. `MiddleCenter` is a real member of the enum (`ErsatzTV.FFmpeg/State/WatermarkState.cs`). ## Why it hasn't bitten `WatermarksScreen.tsx:34` deliberately does not offer `MiddleCenter` in its location picker (there is an explicit comment saying so, inherited from the Blazor editor), so the value is not reachable through the current UI. It *is* reachable through the REST API, a hand-edited database, or an imported/legacy row. ## Suggested fix Add the explicit arm — `x=(W-w)/2:y=(H-h)/2` — and make the `_ =>` default either explicitly `BottomRight` or a thrown/logged unsupported case, so the next added enum value fails loudly instead of silently rendering bottom-right. Check the accelerated overlay paths (`Cuda/OverlayWatermarkCudaFilter.cs`, `Qsv/OverlayWatermarkQsvFilter.cs`) for the same gap. ## Provenance Found during independent review of the #67 `<BugPreview>` component, which renders `MiddleCenter` as genuinely centered — i.e. the SPA preview and the FFmpeg output disagree for this value. #67 keeps the semantically-correct centered preview and does not encode this defect; see the comment in `web/src/components/bugPreview.tsx`. ## Done-when - [x] `MiddleCenter` renders centered in the software overlay path - [x] Accelerated (CUDA / QSV) overlay paths checked for the same missing arm - [x] Default arm no longer silently absorbs unmapped enum values - [x] Adversarial review passed
timothy added the bugpriority: low labels 2026-07-20 20:16:16 +02:00
Author
Owner

🔗 Session bundle — watermark rendering: #503, #510

Watermark rendering correctness in the FFmpeg/graphics path: #503 (MiddleCenter renders bottom-right — missing switch arm in OverlayWatermarkFilter) and #510 (WatermarkSelector deco path has a different missing-logo policy than the three precedence levels). Same WatermarkSelector/overlay surface.

When you claim any member, check this cluster for co-workable siblings and sweep the disjoint set in one session (per docs/handoffs/chicorytv-issue-queue.md → bundles).

🔗 **Session bundle — watermark rendering:** #503, #510 Watermark rendering correctness in the FFmpeg/graphics path: #503 (MiddleCenter renders bottom-right — missing switch arm in OverlayWatermarkFilter) and #510 (WatermarkSelector deco path has a different missing-logo policy than the three precedence levels). Same WatermarkSelector/overlay surface. When you claim any member, check this cluster for co-workable siblings and sweep the disjoint set in one session (per docs/handoffs/chicorytv-issue-queue.md → bundles).
timothy added the in-progress label 2026-07-25 14:05:17 +02:00
Author
Owner

Claiming — swept into this session alongside #484/#491 as a small, fully disjoint slice (ErsatzTV.FFmpeg/Filter/*, no overlap with the scanner work).

Claiming — swept into this session alongside #484/#491 as a small, fully disjoint slice (`ErsatzTV.FFmpeg/Filter/*`, no overlap with the scanner work).
Author
Owner

Implementation done locally (branch fix/503-watermark-middlecenter, not yet pushed — batching with #484/#491).

Findings while implementing

OverlayWatermarkCudaFilter and OverlayWatermarkQsvFilter both derive from OverlayWatermarkFilter and override only Filter/NextState, never Position — so the single base-class switch covers all three overlay paths and there was nothing extra to patch in the accelerated files. Verified by grepping the whole ErsatzTV.FFmpeg project for WatermarkLocation switches: exactly one.

Worth recording for future enum-exhaustiveness audits: there is a second WatermarkLocation switch outside this project, ErsatzTV.Infrastructure/Streaming/Graphics/GraphicsElement.cs (CalculatePosition, the SkiaSharp graphics-engine renderer from #67). It already has a correct MiddleCenter arm, so it was never affected — but note it applies the margin as an offset even when centered, unlike the ffmpeg path's pure center. That is a deliberate difference between the two renderers, not a bug.

Default arm — log, don't throw. Every sibling filter in ErsatzTV.FFmpeg/Filter/ falls back to a safe default (string.Empty, "hwupload", None) rather than throwing, and this runs on the playback hot path where an exception would kill a stream. So the default now logs a warning and falls back to bottom-right. Note the original was already a switch expression with a catch-all _ =>, so the compiler's unhandled-enum diagnostic was never active here — this commit doesn't regress that, but it also can't rely on it, which is why box 3 is closed by a test instead.

Independent review: cold review-only pass, verdict MERGEABLE. A different model family was preferred per process.independent-review-rubric but the Codex CLI is not installed in this environment, so the rubric's stated fallback (a fresh agent with no implementation role) was used — recording the exemption rather than leaving it silent. It confirmed all 9 position expressions against ffmpeg overlay semantics, confirmed the inheritance claim, and surfaced two gaps, both now fixed in a follow-up commit:

  1. ExpectedPositions was a hardcoded 9-element table, so a future 10th enum member would have passed every test and silently rendered bottom-right — reintroducing this very bug. Now asserted against Enum.GetValues<WatermarkLocation>(). Negative control proven: removing MiddleCenter from the table makes the guard fail with the intended diagnostic.
  2. SourceContentMargins() was exercised by no test at all. Now covered with a pillarboxed 1440x1080-in-1920x1080 case.

ErsatzTV.FFmpeg.Tests: 64 passed, 0 failed (was 34 pre-change). BOM check clean, dotnet format whitespace --folder clean.

Done-when

  • MiddleCenter renders centered in the software overlay path
  • Accelerated (CUDA / QSV) overlay paths checked for the same missing arm — they inherit Position, so no separate gap
  • Default arm no longer silently absorbs unmapped enum values — logs a warning, and an exhaustiveness test fails the moment the enum grows
  • Adversarial review passed
Implementation done locally (branch `fix/503-watermark-middlecenter`, not yet pushed — batching with #484/#491). **Findings while implementing** `OverlayWatermarkCudaFilter` and `OverlayWatermarkQsvFilter` both derive from `OverlayWatermarkFilter` and override only `Filter`/`NextState`, never `Position` — so the single base-class switch covers all three overlay paths and there was nothing extra to patch in the accelerated files. Verified by grepping the whole `ErsatzTV.FFmpeg` project for `WatermarkLocation` switches: exactly one. Worth recording for future enum-exhaustiveness audits: there is a **second** `WatermarkLocation` switch outside this project, `ErsatzTV.Infrastructure/Streaming/Graphics/GraphicsElement.cs` (`CalculatePosition`, the SkiaSharp graphics-engine renderer from #67). It already has a correct `MiddleCenter` arm, so it was never affected — but note it applies the margin as an offset even when centered, unlike the ffmpeg path's pure center. That is a deliberate difference between the two renderers, not a bug. **Default arm — log, don't throw.** Every sibling filter in `ErsatzTV.FFmpeg/Filter/` falls back to a safe default (`string.Empty`, `"hwupload"`, `None`) rather than throwing, and this runs on the playback hot path where an exception would kill a stream. So the default now logs a warning and falls back to bottom-right. Note the original was already a switch *expression* with a catch-all `_ =>`, so the compiler's unhandled-enum diagnostic was never active here — this commit doesn't regress that, but it also can't rely on it, which is why box 3 is closed by a test instead. **Independent review:** cold review-only pass, verdict MERGEABLE. A different model family was preferred per `process.independent-review-rubric` but the Codex CLI is not installed in this environment, so the rubric's stated fallback (a fresh agent with no implementation role) was used — recording the exemption rather than leaving it silent. It confirmed all 9 position expressions against ffmpeg `overlay` semantics, confirmed the inheritance claim, and surfaced two gaps, both now fixed in a follow-up commit: 1. `ExpectedPositions` was a hardcoded 9-element table, so a future 10th enum member would have passed every test and silently rendered bottom-right — reintroducing this very bug. Now asserted against `Enum.GetValues<WatermarkLocation>()`. **Negative control proven**: removing `MiddleCenter` from the table makes the guard fail with the intended diagnostic. 2. `SourceContentMargins()` was exercised by no test at all. Now covered with a pillarboxed 1440x1080-in-1920x1080 case. `ErsatzTV.FFmpeg.Tests`: **64 passed, 0 failed** (was 34 pre-change). BOM check clean, `dotnet format whitespace --folder` clean. ## Done-when - [x] `MiddleCenter` renders centered in the software overlay path - [x] Accelerated (CUDA / QSV) overlay paths checked for the same missing arm — they inherit `Position`, so no separate gap - [x] Default arm no longer silently absorbs unmapped enum values — logs a warning, and an exhaustiveness test fails the moment the enum grows - [x] Adversarial review passed
Author
Owner

Closing record

Outcome: Shipped in PR #611 (merged). WatermarkLocation.MiddleCenter now maps to x=(W-w)/2:y=(H-h)/2 across the software, CUDA and QSV overlay paths; BottomRight promoted to an explicit arm; the default arm logs a warning instead of silently absorbing unmapped values.

Root cause: The switch had no arm for MiddleCenter, so it fell through a _ => default — and that same default served BottomRight. Two enum values producing byte-identical output is what made the gap invisible: nothing looked broken, and no test could distinguish "handled" from "fell through". The deeper cause is that the mapping's completeness was never asserted anywhere; the original was a switch expression with a catch-all, so the compiler's unhandled-enum diagnostic was never active either.

Decisions/conventions changed: none.

Reusable knowledge: Three things worth carrying forward.

  1. OverlayWatermarkCudaFilter and OverlayWatermarkQsvFilter inherit Position from OverlayWatermarkFilter and override only Filter/NextState — one base switch covers all three overlay paths, so a position fix does not need touching the accelerated files.
  2. There is a second WatermarkLocation switch outside ErsatzTV.FFmpeg: ErsatzTV.Infrastructure/Streaming/Graphics/GraphicsElement.cs (CalculatePosition, the SkiaSharp renderer from #67). It was already correct, but note it applies the margin as an offset even when centered, unlike the ffmpeg path's pure center — a deliberate difference between the two renderers, not a bug. Any future enum-exhaustiveness audit must cover both.
  3. Every sibling filter in ErsatzTV.FFmpeg/Filter/ falls back to a safe default rather than throwing on an unrecognized enum — these run on the playback hot path, where an exception kills a stream. Follow that pattern, and close the "silent absorption" hole with a test rather than an exception.

Verification: ErsatzTV.FFmpeg.Tests 64 passed / 0 failed (34 before). Exact-string assertions for all 9 locations across all three overlay filters, plus an exhaustiveness guard asserting the expected-position table covers Enum.GetValues<WatermarkLocation>() — negative control proven: removing MiddleCenter from the table fails it with the intended diagnostic. Also closed a pre-existing gap where SourceContentMargins() was exercised by no test at all. Full CI green. No live-E2E: pure ffmpeg-argument-construction leaf, no API write path, no server state, no UI.

Deferred: none.

Docs updated: none required — no route, endpoint, SPA screen, or convention changed. The fix is internal to filter-argument construction.

## Closing record **Outcome:** Shipped in PR #611 (merged). `WatermarkLocation.MiddleCenter` now maps to `x=(W-w)/2:y=(H-h)/2` across the software, CUDA and QSV overlay paths; `BottomRight` promoted to an explicit arm; the `default` arm logs a warning instead of silently absorbing unmapped values. **Root cause:** The `switch` had no arm for `MiddleCenter`, so it fell through a `_ =>` default — and that same default served `BottomRight`. Two enum values producing byte-identical output is what made the gap invisible: nothing looked broken, and no test could distinguish "handled" from "fell through". The deeper cause is that the mapping's completeness was never asserted anywhere; the original was a switch *expression* with a catch-all, so the compiler's unhandled-enum diagnostic was never active either. **Decisions/conventions changed:** none. **Reusable knowledge:** Three things worth carrying forward. 1. `OverlayWatermarkCudaFilter` and `OverlayWatermarkQsvFilter` **inherit** `Position` from `OverlayWatermarkFilter` and override only `Filter`/`NextState` — one base switch covers all three overlay paths, so a position fix does not need touching the accelerated files. 2. There is a **second** `WatermarkLocation` switch outside `ErsatzTV.FFmpeg`: `ErsatzTV.Infrastructure/Streaming/Graphics/GraphicsElement.cs` (`CalculatePosition`, the SkiaSharp renderer from #67). It was already correct, but note it applies the margin as an offset even when centered, unlike the ffmpeg path's pure center — a deliberate difference between the two renderers, not a bug. Any future enum-exhaustiveness audit must cover both. 3. Every sibling filter in `ErsatzTV.FFmpeg/Filter/` falls back to a safe default rather than throwing on an unrecognized enum — these run on the playback hot path, where an exception kills a stream. Follow that pattern, and close the "silent absorption" hole with a test rather than an exception. **Verification:** `ErsatzTV.FFmpeg.Tests` 64 passed / 0 failed (34 before). Exact-string assertions for all 9 locations across all three overlay filters, plus an exhaustiveness guard asserting the expected-position table covers `Enum.GetValues<WatermarkLocation>()` — **negative control proven**: removing `MiddleCenter` from the table fails it with the intended diagnostic. Also closed a pre-existing gap where `SourceContentMargins()` was exercised by no test at all. Full CI green. No live-E2E: pure ffmpeg-argument-construction leaf, no API write path, no server state, no UI. **Deferred:** none. **Docs updated:** none required — no route, endpoint, SPA screen, or convention changed. The fix is internal to filter-argument construction.
timothy removed the in-progress label 2026-07-25 17:09:31 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#503