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
14 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. - The inset is also capped at
min(frameWidth, frameHeight) / 2, with a logged warning, whether or notwidth_percentis 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_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.
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 —
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 — 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_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_Unwritable_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_StartupAn_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_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 |
| 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_GeometryThe_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 |