The table asserted its "Reddens" column was measured, and it was - through `--filter FullyQualifiedName~<fixture>`, which structurally cannot observe a red in another fixture. A measurement with a blind spot presented as a measurement is worse than none, and it was the table's own documented reproduce command that carried the blind spot. Re-measured by running the whole ErsatzTV.Tests project per mutation. Eight of the twenty-four rows redden more than one fixture and were previously under-reported - including the row a cold review caught by hand, which reddens `An_Already_Seeded_Install_Missing_Its_Element_Row_Gets_One` AND `Repeated_Seeding_Does_Not_Accumulate_Element_Rows`, not one of them. The reproduce instruction now says to run the project unfiltered, and the reason is stated so the next person does not reintroduce the filter for speed. The mutation harness also grew a guard: it restores with `git checkout --`, so an uncommitted change to a file it mutates was silently reverted. It now refuses to run when a mutated file is dirty. Decisions-Edit: yes Refs: #732
13 KiB
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/).RefreshGraphicsElementsHandlerscans them and maintains oneGraphicsElementrow per file, removing rows whose file vanished. - Five join tables attach an element:
ChannelGraphicsElement,PlayoutItemGraphicsElement,ProgramScheduleItemGraphicsElement,BlockItemGraphicsElement,DecoGraphicsElement. Resolution order and the decoMerge/Override/Disable/Inheritsemantics are ingraphics.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 (
GraphicsElementLoadercarries an explicitTODO: 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 unparseabletext_colorsilently falls back to white and an unparseablehalo_colorsilently leaves the halo unset. font_familyis required on every style. A null one makesCustomFontMapperthrow 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_percentapplies 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_percentis a budget, not a guarantee. Wrapping cannot break below a single glyph, so a narrowwidth_percentoverflows with or without a box — that is pre-existing behaviour, not something the box introduced.text_fit: Scaleshrinks 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_paddingstops 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_expressiondims 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 whole ErsatzTV.Tests project
re-run; the "Reddens" column is the measured failure set. The working tree was confirmed clean after
each run. Reproduce one by making the edit and running
dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj — not a --filtered run.
Three traps this table is built to avoid:
- Measure against the whole project, never a per-fixture filter. A filtered run structurally cannot observe a red in another fixture, so it under-reports the failure set while looking precise. Eight of the rows below redden more than one fixture.
- A mutation that fails to COMPILE is not a result. Warnings-as-error turn the obvious mutation
shapes into build failures —
CS0162forif (true) { return; },CS1717for self-assignment, SonarS3981for a constant-folded condition — and a build failure emits 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, noterror 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 describes 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 it 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_ElementBackground_Color_Fills_The_BoxBackground_Opacity_Percent_Scales_The_AlphaBackground_Padding_Actually_Insets_The_TextBorder_Color_Draws_A_Border_Distinct_From_The_FillBorder_Color_Without_An_Explicit_Width_Draws_A_HairlineCorner_Radius_Rounds_The_Corner_Away |
| 2 | inset not subtracted from the wrap budget | Fractional_Padding_Still_Respects_Width_PercentWidth_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_Replace_After_A_Complete_Temp_Write_Leaves_The_Original_IntactA_Failed_Write_Leaves_The_Original_Template_IntactAn_Unreadable_Template_Does_Not_Fail_StartupThe_Upgraded_Template_Still_Deserializes_With_A_Resolvable_Base_StyleUpgrades_An_Untouched_Previous_DefaultUpgrades_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_AttachmentWhile_Armed_A_Restored_Element_Is_Attached_To_Every_Eligible_Channel |
| 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_Replace_After_A_Complete_Temp_Write_Leaves_The_Original_IntactA_Failed_Write_Leaves_The_Original_Template_IntactA_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_OneRepeated_Seeding_Does_Not_Accumulate_Element_Rows |
| 23 | non-atomic in-place write restored | A_Failed_Replace_After_A_Complete_Temp_Write_Leaves_The_Original_IntactA_Failed_Write_Leaves_The_Original_Template_Intact |
| 24 | marker written even with nothing resolved | Stays_Armed_When_There_Is_No_Built_In_Element_To_AttachWhile_Armed_A_Restored_Element_Is_Attached_To_Every_Eligible_Channel |