Files
ersatztv/docs/graphics-elements.md
T
timothy bef3f54798 fix(732): close the review findings on the background box and the default attach
Two independent cold reviews (Codex GPT-5.6 and a worktree-isolated Opus agent) converged on the
same three serious problems; both returned BLOCKED.

Boot safety. The already-seeded branch of SeedOnNowNext used to touch the filesystem not at all,
so a template the app cannot read - one edited as root via `docker exec` while the app runs under
PUID/PGID, or a read-only /config - was harmless. Reading and rewriting it there put unguarded IO
ahead of DatabaseIsReady() in a BackgroundService whose default behavior is StopHost, i.e. a
restart loop triggered by a file permission an operator can set by hand. The upgrade is now
best-effort (broad catch, cancellation still propagates) and CreateDirectory moved back below the
already-seeded check.

Stranding. The backfill wrote its marker even when the built-in GraphicsElement row was merely
undiscovered - the row is normally created by RefreshGraphicsElements, which runs long after
startup. An install upgrading from before #74 seeds the template and backfills on the same boot,
so every pre-existing channel would have been left unattached forever, with no second chance. The
seeder now creates the row itself, so the marker is only ever written against a resolved element.
The test that asserted the old behavior is replaced by one that pins the upgrade case.

Overclaimed records. The never-re-attach guarantee holds from the marker onwards, not across the
upgrade boundary: an operator who cleared the overlay before this landed left no state that
survives, and the one-time backfill re-adds it. That is inherent to "on by default" rather than a
defect, but the record asserted otherwise. Also recorded: the upgrade is a one-way door, because
the loader rejects unknown YAML keys, so a rollback drops the overlay on every channel at once.

Smaller, all with tests: the wrap budget now subtracts the same integer inset the bitmap grows by
(a fractional padding overflowed width_percent by a pixel); an inset that cannot fit is clamped
instead of squeezing the text to 1px and letting the box grow unbounded; FitTextBlock carries halo
and line height across, which only became reachable once a box's insets could push an element into
the Scale path; the built-in lookup filters on Kind so a same-named element in another template
folder cannot win; CreateChannelHandler adds to the collection rather than assigning over it.

width_percent is documented as a budget rather than a guarantee - wrapping cannot break below one
glyph, so it overflows with or without a box. The doc also no longer claims an unparseable colour
is never substituted (true for the box, false for text_color) or that an unset background_color
means no box (a border alone draws one).

The mutation claim is now reproducible: all 19 clause mutations are listed in
docs/graphics-elements.md with the test each one reddens. Two candidate mutations produced NO test
summary because they failed to compile under warnings-as-error, which reads exactly like a pass in
a scrolled log - that is called out there too.

The new pixel tests are the first in the repo to rasterise text, so the CI image's font dependency
is now declared in docs/testing.md rather than incidental (351 fonts present in the pinned image,
measured; they arrive via playwright install --with-deps).

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

9.9 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.
  • 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)

Each clause below was mutated in turn and the suite re-run; each reddened only the listed test(s) and nothing else, and the tree was restored and confirmed green afterwards. Re-run one by making the edit and running the named filter. A mutation that fails to COMPILE is not a result — two of these (if (true) { return; }, an unused local) tripped CS0162/warning-as-error and produced no test summary at all, which reads exactly like a pass in a scrolled log.

# Clause mutated Expected red
1 DrawBackgroundBox returns immediately 6 box tests
2 inset not subtracted from the wrap budget 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 3 upgrade tests
6 fingerprint check ignored (upgrade unconditionally) Leaves_An_Operator_Modified_File_Alone
7 line-ending normalisation dropped from Normalize ..._With_Windows_Line_Endings
8 HLS-Direct exclusion removed from the backfill Skips_Hls_Direct_Channels_...
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_...
11 graphics.on_now_next_default_attached guard never fires Does_Not_Re_Attach_..., Backfills_On_The_Same_Boot_...
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_...
14 upgrade no longer catches filesystem exceptions An_Unreadable_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_...
18 EnsureBuiltInElementRow removed Backfills_On_The_Same_Boot_That_First_Seeds_The_Template
19 Kind == Text filter dropped from the lookup Ignores_A_Same_Named_Element_Of_A_Different_Kind