Files
ersatztv/docs/graphics-elements.md
T
timothy 8eab7baf58 docs(732): record that the per-style halo fix leaves the seeded template byte-identical
The halo fix changes a renderer that has already shipped, so the question is what it does to the one
template we ship. Measured rather than reasoned: the seeded on-now-next.yml renders to the same
bitmap with and without the fix (md5 0663AF1E13C558F4DB99F887318E275D, 1920x1080), because all three
of its styles declare the same halo - which is also why the bug was invisible. A third-party template
that varies halo per style will change, which is the point.

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

14 KiB
Raw Blame History

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.
  • The inset is also capped at min(frameWidth, frameHeight) / 2, with a logged warning, whether or not width_percent is set. Each field is bounded on its own, but padding and border add up, so without this a two-field mistake could allocate a bitmap far larger than the frame it is drawn onto.
  • 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. Every one of these overrides the base_style's value when the style declares it — the halo fields did not until #732, so before that a non-base style silently rendered the base style's halo. The seeded on-now-next.yml is unaffected because all three of its styles declare the same halo: its rendered bitmap is byte-identical either way (md5 0663AF1E13C558F4DB99F887318E275D, 1920x1080, measured 2026-08-26). A third-party template that varies halo per style will change, correctly. 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 — CS0162 for if (true) { return; }, CS1717 for self-assignment, Sonar S3981 for 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 , 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 describes a tree that no longer exists.

Not covered by any mutation — one clause, enumerated rather than asserted: 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.

Treat this paragraph as a claim that decays: it is only true for the clauses present when the table was last measured. Adding a guard without adding its row silently makes it false, which is how the frame cap went three commits with no proof it could go red.

# Clause mutated Reddens (measured)
1 DrawBackgroundBox returns immediately An_Oversized_Border_Is_Clamped_And_Does_Not_Flood_The_Element
Background_Color_Fills_The_Box
Background_Opacity_Percent_Scales_The_Alpha
Background_Padding_Actually_Insets_The_Text
Border_Color_Draws_A_Border_Distinct_From_The_Fill
Border_Color_Without_An_Explicit_Width_Draws_A_Hairline
Corner_Radius_Rounds_The_Corner_Away
2 inset not subtracted from the wrap budget Fractional_Padding_Still_Respects_Width_Percent
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_Replace_After_A_Complete_Temp_Write_Leaves_The_Original_Intact
A_Failed_Write_Leaves_The_Original_Template_Intact
An_Unwritable_Template_Does_Not_Fail_Startup
The_Upgraded_Template_Still_Deserializes_With_A_Resolvable_Base_Style
Upgrades_An_Untouched_Previous_Default
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
While_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_Intact
A_Failed_Write_Leaves_The_Original_Template_Intact
A_Read_Failure_On_The_Template_Does_Not_Fail_Startup
An_Unwritable_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
Repeated_Seeding_Does_Not_Accumulate_Element_Rows
23 non-atomic in-place write restored A_Failed_Replace_After_A_Complete_Temp_Write_Leaves_The_Original_Intact
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
While_Armed_A_Restored_Element_Is_Attached_To_Every_Eligible_Channel
25 the atomic replace becomes a non-atomic copy A_Failed_Replace_After_A_Complete_Temp_Write_Leaves_The_Original_Intact
26 the frame cap on the inset is disarmed Non_Finite_And_Absurd_Box_Values_Do_Not_Corrupt_The_Geometry
The_Inset_Is_Capped_Against_The_Frame_Even_With_No_Width_Percent
27 per-style halo overrides dropped from the style merge A_Non_Base_Style_Uses_Its_Own_Halo_Not_The_Base_Styles