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