# 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`). 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.