Part 1 - background box. TextGraphicsElement gains element-level background_color, background_opacity_percent, background_padding, background_corner_radius, border_color and border_width; TextElement draws a rounded rect behind the text block and insets the text into it. Element level rather than per-style because the engine lays the whole element out as one RichTextKit TextBlock and rasterises it into one bitmap, so one box per element is the only shape the renderer can express. width_percent keeps bounding the visible element, so the insets are subtracted from the text's wrap/scale budget. The seeded on-now-next.yml adopts it. The halo drops from 2px to 1px rather than to zero, and the box carries a low-alpha white border: rendered against real frames, a 65% black fill is legible on bright and midtone content but vanishes entirely into dark content, which is why the issue asked for an *outlined* box. The halo still matters because the fill is translucent. Because #74's seeder writes the template only when absent, an already-seeded install would never have seen any of this. GraphicsElementSeeder now keeps every default it has shipped as a verbatim fingerprint and rewrites the file only when it still matches one (line-endings normalised), so an untouched install upgrades and an operator-edited one is left alone. The V1 fingerprint was checked byte-for-byte against the live install before being trusted - a fingerprint that matches nothing in the field is a permanent silent no-op. Part 2 - on by default. New channels get the built-in element from CreateChannelHandler (CreateChannel carries no graphics field and the SPA's channel editor is update-only, so the server is the only place a create-time default can live). Pre-existing channels get a one-time AttachOnNowNextByDefault backfill. The marker is written on the first run even when nothing was attached: the tempting alternative - stay armed until the element row exists - would fire on a later boot and re-attach the overlay to a channel the operator had cleared in between. HLS Direct is excluded at both sites, where the overlay cannot render at all. Resolves the issue's open question: [vge] in a filter graph does not imply a graphics element is bound. Watermarks fall back onto the graphics engine whenever they cannot use ffmpeg's native overlay shortcut, so a watermark alone produces that stage. Tests assert rendered pixels, because every failure mode here is a silent no-op that a model-level test cannot see. 13 clause mutations were executed against them; each reddened only its own clause. Decisions-Edit: yes Refs: #732
101 lines
6.0 KiB
Markdown
101 lines
6.0 KiB
Markdown
# 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). An unparseable colour is skipped, never substituted.
|
||
- **`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. Bounds the **whole element**, box included. |
|
||
| `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 box at all**. |
|
||
| `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` still bounds the visible box rather than the text inside it.
|
||
- 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.
|