Files
ersatztv/docs/graphics-elements.md
T
timothy bef3f54798 fix(732): close the review findings on the background box and the default attach
Two independent cold reviews (Codex GPT-5.6 and a worktree-isolated Opus agent) converged on the
same three serious problems; both returned BLOCKED.

Boot safety. The already-seeded branch of SeedOnNowNext used to touch the filesystem not at all,
so a template the app cannot read - one edited as root via `docker exec` while the app runs under
PUID/PGID, or a read-only /config - was harmless. Reading and rewriting it there put unguarded IO
ahead of DatabaseIsReady() in a BackgroundService whose default behavior is StopHost, i.e. a
restart loop triggered by a file permission an operator can set by hand. The upgrade is now
best-effort (broad catch, cancellation still propagates) and CreateDirectory moved back below the
already-seeded check.

Stranding. The backfill wrote its marker even when the built-in GraphicsElement row was merely
undiscovered - the row is normally created by RefreshGraphicsElements, which runs long after
startup. An install upgrading from before #74 seeds the template and backfills on the same boot,
so every pre-existing channel would have been left unattached forever, with no second chance. The
seeder now creates the row itself, so the marker is only ever written against a resolved element.
The test that asserted the old behavior is replaced by one that pins the upgrade case.

Overclaimed records. The never-re-attach guarantee holds from the marker onwards, not across the
upgrade boundary: an operator who cleared the overlay before this landed left no state that
survives, and the one-time backfill re-adds it. That is inherent to "on by default" rather than a
defect, but the record asserted otherwise. Also recorded: the upgrade is a one-way door, because
the loader rejects unknown YAML keys, so a rollback drops the overlay on every channel at once.

Smaller, all with tests: the wrap budget now subtracts the same integer inset the bitmap grows by
(a fractional padding overflowed width_percent by a pixel); an inset that cannot fit is clamped
instead of squeezing the text to 1px and letting the box grow unbounded; FitTextBlock carries halo
and line height across, which only became reachable once a box's insets could push an element into
the Scale path; the built-in lookup filters on Kind so a same-named element in another template
folder cannot win; CreateChannelHandler adds to the collection rather than assigning over it.

width_percent is documented as a budget rather than a guarantee - wrapping cannot break below one
glyph, so it overflows with or without a box. The doc also no longer claims an unparseable colour
is never substituted (true for the box, false for text_color) or that an unset background_color
means no box (a border alone draws one).

The mutation claim is now reproducible: all 19 clause mutations are listed in
docs/graphics-elements.md with the test each one reddens. Two candidate mutations produced NO test
summary because they failed to compile under warnings-as-error, which reads exactly like a pass in
a scrolled log - that is called out there too.

The new pixel tests are the first in the repo to rasterise text, so the CI image's font dependency
is now declared in docs/testing.md rather than incidental (351 fonts present in the pinned image,
measured; they arrive via playwright install --with-deps).

Decisions-Edit: yes
Refs: #732
2026-08-26 20:37:06 +02:00

148 lines
9.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Graphics elements — schema reference
Graphics elements are YAML-authored overlays composited onto a channel's **transcoded** frames by the
SkiaSharp graphics engine (`ErsatzTV.Infrastructure/Streaming/Graphics/`). They appear in the FFmpeg
filter graph as the `[vge]` stage.
`[vge]` is **not** proof that a graphics element is bound. Watermarks are a separate, older system that
falls back onto the graphics engine whenever it cannot use ffmpeg's native `overlay` shortcut — an
`Intermittent`/`OpacityExpression` mode, more than one active watermark, or an external-URL image all
route a *watermark* through `[vge]` with zero graphics-element rows. The native shortcut is only taken
for a single `Permanent` local-file watermark
(`ErsatzTV.Core/FFmpeg/FFmpegLibraryProcessService.cs`, `CanUseFFmpegNativeWatermark`).
`StreamingMode.HttpLiveStreamingDirect` renders nothing: ErsatzTV is not transcoding, so there is no
frame pipeline to draw into and `GraphicsElementSelector` returns empty.
## Discovery and attachment
- Files live under `FileSystemLayout.GraphicsElements*TemplatesFolder` (`text/`, `image/`, `motion/`,
`subtitle/`, `script/`). `RefreshGraphicsElementsHandler` scans them and maintains one
`GraphicsElement` row per file, removing rows whose file vanished.
- Five join tables attach an element: `ChannelGraphicsElement`, `PlayoutItemGraphicsElement`,
`ProgramScheduleItemGraphicsElement`, `BlockItemGraphicsElement`, `DecoGraphicsElement`.
Resolution order and the deco `Merge`/`Override`/`Disable`/`Inherit` semantics are in
`graphics.channel-level-attachment`; the channel level is the **base layer**.
## Parsing rules that bite
- Deserialization is YamlDotNet **without** `IgnoreUnmatchedProperties`, so **an unknown key throws**
and the whole element is silently disabled for that content with only a logged warning
(`GraphicsElementLoader.FromYaml<T>`). A typo is not a partial render — it is no render.
- There is no schema validation (`GraphicsElementLoader` carries an explicit `TODO: validate schema`).
- Colour strings are parsed with SkiaSharp's `SKColor.TryParse` (`#RRGGBB`, `#AARRGGBB`, named
colours). Failure handling differs by field: an unparseable **background/border** colour is warned
about and that part of the box is skipped, but an unparseable `text_color` silently falls back to
**white** and an unparseable `halo_color` silently leaves the halo unset.
- **`font_family` is required on every style.** A null one makes `CustomFontMapper` throw on a null
dictionary key, which the renderer swallows into "disable for this content" (#570).
- `{{ … }}` template expressions are rendered by Scriban before the YAML is parsed.
## Text element fields
Element level (`TextGraphicsElement`):
| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | Display name; **never** used for identity. |
| `text` | string | Scriban-templated. `[styleName]…[/styleName]` selects a style for a span. |
| `base_style` | string | Must name an entry in `styles`, or initialization throws. |
| `styles` | list | See below. |
| `epg_entries` | int | How many EPG entries to expose as `Epg[…]`. |
| `location` | enum | `TopLeft`, `BottomLeft`, … |
| `horizontal_margin_percent` / `vertical_margin_percent` | double | Percent of frame width/height. |
| `width_percent` | double | Percent of frame width. A wrapping/scaling **budget** for the whole element, box included — not a hard clamp; see the geometry notes. |
| `text_fit` | `None` \| `Wrap` \| `Scale` | Only meaningful with `width_percent`. |
| `text_align` | `Left` \| `Center` \| `Right` | |
| `z_index` | int | |
| `opacity_percent` | int | Ignored when `opacity_expression` is set. |
| `opacity_expression` | string | NCalc expression, e.g. `LinearFadeDuration(content_seconds, 4, 1, 6)`. |
| `include_fonts_from` | string | Directory of `.ttf`/`.otf` to load. |
Background box (#732) — element level, because the engine lays the whole element out as one text block
and rasterises it into one bitmap, so there is exactly one box per element:
| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `background_color` | string | unset | Unset means no **fill**. A `border_color` alone still draws an outlined box; with neither, there is no box and no insets. |
| `background_opacity_percent` | int | 100 | Clamped to 0–100; multiplies the colour's own alpha, so `#AARRGGBB` and this field compose. |
| `background_padding` | double px | 0 | Space between the text and the box edge, on all four sides. |
| `background_corner_radius` | double px | 0 | Clamped to half the shorter side. |
| `border_color` | string | unset | |
| `border_width` | double px | 1 when `border_color` is set | A border colour with no width draws a hairline rather than nothing. |
Geometry notes:
- Padding and border grow the element's bitmap and are subtracted from the text's wrap/scale budget, so
`width_percent` applies to the visible box rather than to the text inside it. The inset is rounded up
to a whole pixel once and the same integer is used on both sides, so the box cannot exceed the budget
by a rounding remainder.
- **`width_percent` is a budget, not a guarantee.** Wrapping cannot break below a single glyph, so a
narrow `width_percent` overflows with or without a box — that is pre-existing behaviour, not
something the box introduced. `text_fit: Scale` shrinks the font instead, down to a 5px floor.
- If the inset does not fit inside the budget at all, the **inset is clamped** (with a logged warning)
rather than the text being squeezed to nothing, so an oversized `background_padding` stops growing
its box at the budget instead of producing one several times the requested width.
- With no box fields set the wrap/scale budget is passed through untouched, so existing overlays keep
their exact pre-#732 geometry.
- The box is drawn behind the text and fades with the element, so `opacity_expression` dims box and
text together.
- Sizes are in **pixels at frame scale**, matching `font_size`. They do not scale with resolution.
Per-style (`StyleDefinition`): `name`, `font_family` (required), `font_size`, `font_weight`,
`font_italic`, `text_color`, `letter_spacing`, `line_height`, `halo_color`, `halo_width`, `halo_blur`.
Halo is drawn by RichTextKit as part of the text, not by the box code — a wide halo **on top of** a
background box over-darkens the glyphs, which is why the seeded template cuts it to 1px.
## The built-in On Now / Next element
`GraphicsElementSeeder` writes `on-now-next.yml` once per database (`graphics.on_now_next_seeded`) and
never overwrites an operator's file. Two rules govern it after that:
- Updating the shipped default → `graphics.seeded-template-upgrade-by-fingerprint`.
- It is attached to channels by default → `graphics.on-now-next-on-by-default`.
Identity is the **filename** (`GraphicsElementDefaults.OnNowNextFileName`), never the editable `Name`;
`GraphicsElementResponseModel.BuiltIn` is derived from it server-side so the SPA never name-matches.
## Tests
`ErsatzTV.Tests/Infrastructure/Graphics/TextElementBackgroundBoxTests.cs` renders real bitmaps and
asserts pixels — the box's failure mode is a silent no-op, which a model-level test cannot see.
Geometry assertions are relative to a no-box baseline so they do not depend on the host's typeface,
and `Baseline_Renders_A_Non_Empty_Bitmap` turns a fontless host into a loud red instead of a suite
that passes vacuously on a 0x0 bitmap (see `docs/testing.md` → font dependency).
Attachment behaviour is covered by `GraphicsElementDefaultAttachTests`,
`GraphicsElementSeederUpgradeTests` and `CreateChannelDefaultGraphicsElementTests`.
### Mutation record (#732)
Each clause below was mutated in turn and the suite re-run; each reddened only the listed test(s) and
nothing else, and the tree was restored and confirmed green afterwards. Re-run one by making the edit
and running the named filter. A mutation that fails to COMPILE is not a result — two of these
(`if (true) { return; }`, an unused local) tripped `CS0162`/warning-as-error and produced no test
summary at all, which reads exactly like a pass in a scrolled log.
| # | Clause mutated | Expected red |
|---|---|---|
| 1 | `DrawBackgroundBox` returns immediately | 6 box tests |
| 2 | inset not subtracted from the wrap budget | `Width_Percent_Bounds_The_Whole_Box_Including_Padding` |
| 3 | text painted at `(0,0)` instead of the inset | `Background_Padding_Actually_Insets_The_Text` |
| 4 | `ApplyOpacityPercent` returns the colour unchanged | `Background_Opacity_Percent_Scales_The_Alpha` |
| 5 | `UpgradeUnmodifiedTemplate` call removed | 3 upgrade tests |
| 6 | fingerprint check ignored (upgrade unconditionally) | `Leaves_An_Operator_Modified_File_Alone` |
| 7 | line-ending normalisation dropped from `Normalize` | `..._With_Windows_Line_Endings` |
| 8 | HLS-Direct exclusion removed from the backfill | `Skips_Hls_Direct_Channels_...` |
| 9 | already-attached filter removed | `Does_Not_Duplicate_An_Existing_Attachment` |
| 10 | filename check removed from the built-in lookup | `Ignores_A_Non_Built_In_Element_...` |
| 11 | `graphics.on_now_next_default_attached` guard never fires | `Does_Not_Re_Attach_...`, `Backfills_On_The_Same_Boot_...` |
| 12 | create-time `AttachDefaultGraphicsElements` call removed | `Attaches_The_Built_In_Element_To_A_New_Channel` |
| 13 | HLS-Direct skip removed from the create path | `Leaves_An_Hls_Direct_Channel_Alone_...` |
| 14 | upgrade no longer catches filesystem exceptions | `An_Unreadable_Template_Does_Not_Fail_Startup` |
| 15 | `FitTextBlock` drops `HaloColor` again | `The_Scale_Path_Preserves_The_Halo` |
| 16 | unrounded inset subtracted from the budget | `Fractional_Padding_Still_Respects_Width_Percent` |
| 17 | inset clamp removed | `An_Oversized_Padding_Is_Clamped_...` |
| 18 | `EnsureBuiltInElementRow` removed | `Backfills_On_The_Same_Boot_That_First_Seeds_The_Template` |
| 19 | `Kind == Text` filter dropped from the lookup | `Ignores_A_Same_Named_Element_Of_A_Different_Kind` |