fix(fallbacks): T4 — fail loud on missing configured render asset (font dir, background) (#807)

## Summary
Theme 4 of the silent-fallback audit
(`docs/archive/2026-06-09-fallback-audit-plan.md`, in #805). A
*configured* branded render asset that is missing must not silently
substitute a different font/background on a paid deliverable. Mirrors
the existing background-image check in
`output/video.VideoGenerator.__init__` (which already raises).

## Changes
- **`output/video._build_ass_filter`** (4.1): when the theme's karaoke
`font_path` is set but the file is missing, the final MP4 used to
silently drop `:fontsdir` → libass resolves a system fallback font for
the whole song. Now raises `FileNotFoundError`. *(Unset `font_path` is
still fine — no fontsdir, no raise.)*
- **`video_generator._create_background`** (4.3): a set-but-missing
title/end-screen `background_image` used to silently fall back to a flat
color. Now raises `FileNotFoundError`. *(No background configured is
still fine — flat color.)*

## Scope (per your decision)
Only these two clean "configured-but-missing → raise" cases are changed.
The font **substitution** items (4.2 title/end font, 4.4 CDG→arial, 4.8
measurement font) and duet/colour items (4.5–4.7) are **left as-is** —
font substitution overlaps with legitimate CJK font fallback
(`test_video_generator_cjk_font.py`) and warrants per-item treatment.

## Testing
- [x] New `tests/unit/test_fallback_render_assets.py` (raise +
legitimate-unset cases)
- [x] 105 render/video tests pass

## Review
- [x] CodeRabbit CLI review completed locally (0 findings)

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 4.8 authored and GitHub committed 2026-08-22 18:50:16 -04:00
1 parent 6c374842f9
commit 51d9233cb8
4 files changed
+91 -5

No files matched your search

+11 -1
View File
@@ -414,7 +414,17 @@ class VideoGenerator:
karaoke_styles = self.styles.get("karaoke", {})
font_path = karaoke_styles.get("font_path")
if font_path and os.path.isfile(font_path):
if font_path:
if not os.path.isfile(font_path):
# The theme specifies a branded karaoke font but the file is
# missing. Refuse to silently render the whole song with a libass
# system-fallback font on a paid deliverable — mirrors the
# background-image check in __init__. (Fallback audit, Theme 4.)
raise FileNotFoundError(
f"Karaoke font not found: {font_path}. The theme specifies a "
"branded font but the file is missing — refusing to silently "
"render with a system fallback font."
)
font_dir = os.path.dirname(font_path)
escaped_font_dir = self._escape_ffmpeg_filter_path(font_dir)
ass_filter += f":fontsdir={escaped_font_dir}"
+14 -3
View File
@@ -367,9 +367,20 @@ class VideoGenerator:
def _create_background(self, format, resolution):
"""Create or load the background image."""
if format["background_image"] and os.path.exists(format["background_image"]):
self.logger.info(f"Using background image file: {format['background_image']}")
background = Image.open(format["background_image"])
background_image = format["background_image"]
if background_image:
if not os.path.exists(background_image):
# A themed background was specified but the file is missing.
# Refuse to silently fall back to a flat color on a paid title/end
# card — mirrors the karaoke video path, which raises on a missing
# background image. (Fallback audit, Theme 4.)
raise FileNotFoundError(
f"Background image not found: {background_image}. The theme "
"specifies a background image but the file is missing — refusing "
"to silently render a flat color instead."
)
self.logger.info(f"Using background image file: {background_image}")
background = Image.open(background_image)
else:
self.logger.info(f"Using background color: {format['background_color']}")
background = Image.new("RGB", resolution, color=self.hex_to_rgb(format["background_color"]))
+1 -1
View File
@@ -1,6 +1,6 @@
[tool.poetry]
name = "karaoke-gen"
version = "0.196.6"
version = "0.196.7"
description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens."
authors = ["Andrew Beveridge <andrew@beveridge.uk>"]
license = "MIT"
+65
View File
@@ -0,0 +1,65 @@
"""
Fallback audit (Theme 4): a *configured* branded render asset that is missing
must fail loudly rather than silently substituting a different font/background on
a paid deliverable. Mirrors the existing background-image check in
lyrics_transcriber/output/video.VideoGenerator.__init__ (which already raises).
Scope: only the cleanest "configured-but-missing → raise" cases were changed
(4.1 final-MP4 karaoke font dir, 4.3 themed title/end background). Font
*substitution* paths (title/end font, CDG arial, measurement font) were left as
graceful fallbacks because they overlap with legitimate CJK font handling.
"""
import pytest
from unittest.mock import MagicMock
from karaoke_gen.lyrics_transcriber.output.video import VideoGenerator as AssVideoGenerator
from karaoke_gen.video_generator import VideoGenerator as ScreenVideoGenerator
# ---- 4.1: final-MP4 karaoke font dir ----
def _make_ass_generator(styles):
"""Build just enough of the ASS VideoGenerator to exercise _build_ass_filter."""
gen = AssVideoGenerator.__new__(AssVideoGenerator)
gen.styles = styles
gen.logger = MagicMock()
return gen
def test_build_ass_filter_raises_when_configured_font_missing():
"""A theme font that's set but missing must raise, not silently drop fontsdir."""
gen = _make_ass_generator({"karaoke": {"font_path": "/nonexistent/Branded.ttf"}})
with pytest.raises(FileNotFoundError, match="Karaoke font not found"):
gen._build_ass_filter("/tmp/lyrics.ass")
def test_build_ass_filter_ok_when_no_font_configured():
"""No font configured is legitimate — no fontsdir, no raise."""
gen = _make_ass_generator({"karaoke": {}})
result = gen._build_ass_filter("/tmp/lyrics.ass")
assert "fontsdir" not in result
assert result.startswith("ass=")
# ---- 4.3: themed title/end background image ----
def _make_screen_generator():
gen = ScreenVideoGenerator.__new__(ScreenVideoGenerator)
gen.logger = MagicMock()
return gen
def test_create_background_raises_when_configured_image_missing():
"""A background image that's set but missing must raise, not silently use a flat color."""
gen = _make_screen_generator()
fmt = {"background_image": "/nonexistent/bg.png", "background_color": "black"}
with pytest.raises(FileNotFoundError, match="Background image not found"):
gen._create_background(fmt, (100, 100))
def test_create_background_uses_color_when_no_image_configured():
"""No background image configured is legitimate — flat color, no raise."""
gen = _make_screen_generator()
fmt = {"background_image": None, "background_color": "#000000"}
bg = gen._create_background(fmt, (10, 10))
assert bg.size == (10, 10)