On Now/Next overlay YAML fails to render (format_datetime arity + null font_family) — #74 hotfix #570

Closed
opened 2026-07-22 23:06:10 +02:00 by timothy · 1 comment
Owner

The seeded on-now-next.yml from #74 fails to render at transcode time — the overlay silently never appears. Found via live visual E2E on ersatztv-test (real channel + content). Two bugs in the seeded YAML:

  1. format_datetime wrong arity. The NEXT line calls format_datetime (convert_timezone Epg[1].Start) "h:mm tt" (2 args). TemplateFunctions.FormatDateTime takes 3 args (DateTimeOffset, timeZoneId, format) and does the tz conversion itself. Wrong arity → Scriban render throws (Failed to render graphics element YAML definition as scriban template) → element ignored.
  2. Missing font_family. Styles omit font_family; CustomFontMapper.TypefaceFromStyle does _customFonts.TryGetValue(style.FontFamily, ...) with a null key → crash before the graceful default-font fallback (TextElement.InitializeAsync line 82).

Fix (verified live): drop the NEXT start-time (avoids hardcoding a timezone in a shipped default) and add font_family: "Noto Sans" to each style. With both fixes the overlay renders correctly (NOW/NEXT EPG titles, per-line styling, halo, bottom-left) — confirmed by frame capture on ersatztv-test.

Related latent bug (separate follow-up): CustomFontMapper.TypefaceFromStyle should treat a null font_family as "use default" instead of crashing.

Root cause: the seeded YAML was authored from field grammar without the format_datetime signature or the font-mapper null-behavior, and static validation can't exercise the render path. Only a live transcode surfaces it.

Done-when

  • Root cause identified — format_datetime wrong arity + null font_family
  • Fix verified LIVE on ersatztv-test via frame capture (overlay renders NOW/NEXT correctly)
  • Seeder guard test added (deserialize + assert base_style resolves + every style sets a font) and green
  • Independent review — skipped per rubric (no-logic YAML-const + test change; verification is the live render, stronger than static review)
  • CI green on the PR
The seeded `on-now-next.yml` from #74 fails to render at transcode time — the overlay silently never appears. Found via live visual E2E on ersatztv-test (real channel + content). Two bugs in the seeded YAML: 1. **`format_datetime` wrong arity.** The NEXT line calls `format_datetime (convert_timezone Epg[1].Start) "h:mm tt"` (2 args). `TemplateFunctions.FormatDateTime` takes **3** args `(DateTimeOffset, timeZoneId, format)` and does the tz conversion itself. Wrong arity → Scriban render throws (`Failed to render graphics element YAML definition as scriban template`) → element ignored. 2. **Missing `font_family`.** Styles omit `font_family`; `CustomFontMapper.TypefaceFromStyle` does `_customFonts.TryGetValue(style.FontFamily, ...)` with a null key → crash **before** the graceful default-font fallback (`TextElement.InitializeAsync` line 82). **Fix (verified live):** drop the NEXT start-time (avoids hardcoding a timezone in a shipped default) and add `font_family: "Noto Sans"` to each style. With both fixes the overlay renders correctly (NOW/NEXT EPG titles, per-line styling, halo, bottom-left) — confirmed by frame capture on ersatztv-test. Related latent bug (separate follow-up): `CustomFontMapper.TypefaceFromStyle` should treat a null `font_family` as "use default" instead of crashing. Root cause: the seeded YAML was authored from field grammar without the `format_datetime` signature or the font-mapper null-behavior, and static validation can't exercise the render path. Only a live transcode surfaces it. ## Done-when - [x] Root cause identified — `format_datetime` wrong arity + null `font_family` - [x] Fix verified LIVE on ersatztv-test via frame capture (overlay renders NOW/NEXT correctly) - [x] Seeder guard test added (deserialize + assert base_style resolves + every style sets a font) and green - [x] Independent review — skipped per rubric (no-logic YAML-const + test change; verification is the live render, stronger than static review) - [x] CI green on the PR
timothy added the priority: high label 2026-07-22 23:06:10 +02:00
Author
Owner

Closing record

Outcome: Fixed via PR #571 (merged). The #74 On Now/Next overlay now renders at transcode time.
Root cause: The seeded on-now-next.yml had two render-time bugs invisible to static validation and code review: (1) format_datetime called with 2 args when it needs 3 (DateTimeOffset, timeZoneId, format) — Scriban render threw; (2) styles set no font_family, and CustomFontMapper.TypefaceFromStyle crashes on a null family key before its default-font fallback. The seed YAML was authored from field grammar without the helper's real signature or the font-mapper's null behavior; only a live transcode surfaces it.
Decisions/conventions changed: none.
Reusable knowledge: Text graphics elements MUST set font_family on every style (null crashes the mapper). format_datetime does its own tz conversion and needs 3 args — don't wrap it in convert_timezone. Seeded/authored template content needs a LIVE render check on real content + EPG; static/unit validation cannot exercise the Scriban+font+SkiaSharp path. The graphics element loads per playout-item, so a fresh transcode session is required to pick up a YAML edit (kill ffmpeg / new session).
Verification: Live on ersatztv-test — captured frames of channel 901 showing the overlay rendering (NOW/NEXT EPG titles, per-line styling, halo, bottom-left); confirmed both opacity_percent and opacity_expression render paths. GraphicsElementSeederTests 4/4 incl. a new guard test (deserialize + assert base_style resolves + every style sets a font). CI green.
Deferred: CustomFontMapper.TypefaceFromStyle should treat a null font_family as "use default" instead of crashing — latent robustness bug, separate follow-up worth filing.
Docs updated: none required (content fix; the overlay behavior docs from #74 remain accurate).

## Closing record **Outcome:** Fixed via PR #571 (merged). The #74 On Now/Next overlay now renders at transcode time. **Root cause:** The seeded `on-now-next.yml` had two render-time bugs invisible to static validation and code review: (1) `format_datetime` called with 2 args when it needs 3 (`DateTimeOffset, timeZoneId, format`) — Scriban render threw; (2) styles set no `font_family`, and `CustomFontMapper.TypefaceFromStyle` crashes on a null family key before its default-font fallback. The seed YAML was authored from field grammar without the helper's real signature or the font-mapper's null behavior; only a live transcode surfaces it. **Decisions/conventions changed:** none. **Reusable knowledge:** Text graphics elements MUST set `font_family` on every style (null crashes the mapper). `format_datetime` does its own tz conversion and needs 3 args — don't wrap it in `convert_timezone`. Seeded/authored template content needs a LIVE render check on real content + EPG; static/unit validation cannot exercise the Scriban+font+SkiaSharp path. The graphics element loads per playout-item, so a fresh transcode session is required to pick up a YAML edit (kill ffmpeg / new session). **Verification:** Live on ersatztv-test — captured frames of channel 901 showing the overlay rendering (NOW/NEXT EPG titles, per-line styling, halo, bottom-left); confirmed both `opacity_percent` and `opacity_expression` render paths. `GraphicsElementSeederTests` 4/4 incl. a new guard test (deserialize + assert base_style resolves + every style sets a font). CI green. **Deferred:** `CustomFontMapper.TypefaceFromStyle` should treat a null `font_family` as "use default" instead of crashing — latent robustness bug, separate follow-up worth filing. **Docs updated:** none required (content fix; the overlay behavior docs from #74 remain accurate).
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#570