Files
ersatztv/docs/graphics-elements.md
T
timothy 666d476417 fix(732): give the frame cap a proof, fix a per-style halo bug, and correct two false claims
Round-4 review, both reviewers BLOCKED. The blocker was the same shape this branch keeps producing:
a completeness claim stated in words rather than derived.

The frame cap on the inset, added one round earlier, had NO test and NO mutation row. Disarming the
clause left the whole 2064-test suite green. The nearest candidate could not see it: its bound was
`baseline + 25_000` while the clause prevents growth of 20_000 on a 1080p frame, i.e. the assertion
was looser than the defect. Worse, the mutation record written the following commit asserted that
exactly one clause was uncovered, naming a different one - a false enumeration in the doc that exists
to prevent false enumerations. Now: a test pinning the cap, a tightened bound on the sibling, two
mutation rows, the cap documented in the geometry notes, and the "not covered" paragraph rewritten as
a claim that decays when a guard is added without its row.

`Environment.ProcessId` is 1 in every container. The image's ENTRYPOINT is exec form, so each
container is PID 1 in its own namespace and they all compute the same temp name - the mitigation was
inert in exactly the deployment the record cited for it. Two containers on one config volume could
still truncate each other's temp file and rename a partial one over the live template, which is the
outcome write-then-move exists to prevent. Random name now, record corrected.

Per-style halo was documented as working and silently discarded. The merge loop rebuilt each style
from base and overrode only font and colour, so a non-base style's halo_* inherited the base style's.
The seeded template hid it by declaring identical halos on all three styles. Three lines, symmetric
with the existing overrides, plus a differential test.

Also: an assertion on `_target + ".upgrade.tmp"` was unfalsifiable once the temp name gained a
suffix - a path the code can never create, passing with the cleanup gutted; a test named
An_Unreadable_Template actually simulates an unwritable one, renamed; a comment described the wrong
channel as cleared.

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

13 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. 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_Unreadable_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
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