The table in docs/graphics-elements.md asserted 19 clause-level results carried over from notes. Two were false: one named a test that had since been renamed, and one claimed a red for a clause whose mutation reddened nothing. Every row is now generated from a fresh run against this tree, and the "Reddens" column is the measured failure set rather than a prediction. Re-measuring found two tests passing for the wrong reason. The atomicity test could not see what it claimed. Testably raises its interception BEFORE truncating, so a plain in-place WriteAllTextAsync leaves the original intact too and "the file survived" is true either way - on a real filesystem it would not be. The test now captures which PATH the write targets and requires it to be the temp file, which is what actually distinguishes the two, and reverting the atomic write reddens it. The non-finite width_percent test set no background fields, so the budget was never converted to an int and the guard it was named for could be deleted with the test still green. It now carries a box. The float.IsFinite guard on the width budget is recorded as NOT covered by any mutation: .NET saturates float-to-int conversion, so removing it changes no observable behaviour. It stays as explicit intent, said out loud rather than implied by omission. Also recorded: warnings-as-error turn the obvious mutation shapes (if (true) return, self-assignment, a constant-folded condition) into build failures that emit no test summary and read like a pass, and detecting that needs `: error `, not `error CS`. Decisions-Edit: yes Refs: #732
168 lines
12 KiB
Markdown
168 lines
12 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)
|
||
|
||
Every clause below was mutated in turn against this tree and the suite re-run; the "Reddens" column is
|
||
the **measured** failure set, not a prediction. The working tree was confirmed clean after each run.
|
||
Reproduce one by making the edit and running
|
||
`dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj --filter FullyQualifiedName~<the fixture>`.
|
||
|
||
Two traps this table is built to avoid:
|
||
|
||
- **A mutation that fails to COMPILE is not a result.** Warnings-as-error here turn the obvious
|
||
mutation shapes into build failures — `CS0162` for `if (true) { return; }`, `CS1717` for
|
||
self-assignment, Sonar `S3981` for a constant-folded condition — and a build failure produces no
|
||
test summary at all, which reads exactly like a pass in a scrolled log. Require a summary line, and
|
||
detect build failure with `: error `, not `error CS`.
|
||
- **Re-measure the red set; never carry it over.** Test renames and added cases both change which
|
||
tests a clause reddens, so a row written from anything but a fresh run is a claim about a tree that
|
||
no longer exists.
|
||
|
||
**Not covered by any mutation:** the `float.IsFinite` guard on the `width_percent` budget. .NET
|
||
saturates float→int conversion, so removing the guard changes no observable behaviour and no test
|
||
reddens. It is kept as explicit intent, not as a tested clause — said here rather than implied by
|
||
omission.
|
||
|
||
| # | Clause mutated | Reddens (measured) |
|
||
|---|---|---|
|
||
| 1 | DrawBackgroundBox returns immediately | `An_Oversized_Border_Is_Clamped_And_Does_Not_Flood_The_Element`<br>`Background_Color_Fills_The_Box`<br>`Background_Opacity_Percent_Scales_The_Alpha`<br>`Background_Padding_Actually_Insets_The_Text`<br>`Border_Color_Draws_A_Border_Distinct_From_The_Fill`<br>`Border_Color_Without_An_Explicit_Width_Draws_A_Hairline`<br>`Corner_Radius_Rounds_The_Corner_Away` |
|
||
| 2 | inset not subtracted from the wrap budget | `Fractional_Padding_Still_Respects_Width_Percent`<br>`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 | `A_Failed_Write_Leaves_The_Original_Template_Intact`<br>`An_Unreadable_Template_Does_Not_Fail_Startup`<br>`The_Upgraded_Template_Still_Deserializes_With_A_Resolvable_Base_Style`<br>`Upgrades_An_Untouched_Previous_Default`<br>`Upgrades_An_Untouched_Previous_Default_With_Windows_Line_Endings` |
|
||
| 6 | fingerprint check ignored (upgrade unconditionally) | `Leaves_An_Operator_Modified_File_Alone` |
|
||
| 7 | line-ending normalisation dropped from Normalize | `Upgrades_An_Untouched_Previous_Default_With_Windows_Line_Endings` |
|
||
| 8 | HLS-Direct exclusion removed from the backfill | `Skips_Hls_Direct_Channels_Where_The_Overlay_Cannot_Render` |
|
||
| 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_With_A_Different_Filename` |
|
||
| 11 | graphics.on_now_next_default_attached guard never fires | `Does_Not_Re_Attach_After_An_Operator_Clears_It` |
|
||
| 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_Because_Nothing_Can_Render_There` |
|
||
| 14 | upgrade no longer catches filesystem exceptions | `A_Failed_Write_Leaves_The_Original_Template_Intact`<br>`A_Read_Failure_On_The_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_To_The_Largest_That_Fits` |
|
||
| 18 | Kind == Text filter dropped from the lookup | `Ignores_A_Same_Named_Element_Of_A_Different_Kind` |
|
||
| 19 | Sanitize passes values through unchecked | `Non_Finite_And_Absurd_Box_Values_Do_Not_Corrupt_The_Geometry` |
|
||
| 20 | the BOX itself is no longer clamped (only insetPixels) | `An_Oversized_Border_Is_Clamped_And_Does_Not_Flood_The_Element` |
|
||
| 21 | duplicate guard removed from EnsureBuiltInElementRow | `Repeated_Seeding_Does_Not_Accumulate_Element_Rows` |
|
||
| 22 | EnsureBuiltInElementRow removed from the ALREADY-SEEDED branch | `An_Already_Seeded_Install_Missing_Its_Element_Row_Gets_One` |
|
||
| 23 | non-atomic in-place write restored | `A_Failed_Write_Leaves_The_Original_Template_Intact` |
|
||
| 24 | marker written even with nothing resolved | `Stays_Armed_When_There_Is_No_Built_In_Element_To_Attach` |
|