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
148 lines
9.9 KiB
Markdown
148 lines
9.9 KiB
Markdown
# 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` |
|