Skip to content

keryx — reel theme comparison (feature spec)

Status: DRAFT (proposed; not started) Owner: Matt Cockayne Last updated: 2026-06-17

0. How to read this

This is a feature spec for rendering one reel under several themes and comparing them side by side — the reel-level analogue of the per-card contact-sheet text-leak screen (keryx cards sheet, 0001 §3.1 / 0002 §2). Where it overlaps the core specs (0001-keryx.md, 0002-interface-contracts.md), 0001/0002 win; this elaborates. Requirement IDs use R-CMP-n.

1. Purpose & value

As more reels were produced, the workflow grew an explicit off-brand theming experiment: take a finished storyboard and re-skin it under alternative aesthetics to find ones worth keeping. From the blog session (verbatim):

"alternative off brand theming for some of our reels … come up with two or three alternative themes and regenerate a reel and compare them side by side"

Themes tried — neon (synthwave/outrun), Hokusai, tattoo, marker, brutalist, papercut — were judged by eye from a montage built ad-hoc with montage.py. Verdicts were decisive ("neon looks stunning", "tattoo is a keeper", "Hokusai … everything is a wave … copyright strike", "brutalist very harsh"). This is a taste-gate over whole reels, and it is currently manual. keryx should make it first-class: one command renders the same storyboard under N reel themes and produces a single comparison artefact.

This is purely additive — it composes the existing theme catalog (0001 §6), the reel renderer, and the take/contact-sheet model. It changes no existing behaviour.

2. Scope

In scope: - Render a workspace's storyboard under several reel themes in one invocation. - Produce a comparison montage for human review (a grid of representative frames per theme, and/or the rendered reels collected for side-by-side play). - Keep the comparison cheap: reuse the VO/music takes already selected; only the visual layer (cards + assembly) varies by theme. A --silent comparison (no VO/music) is the cheapest format proof, mirroring reel build --silent.

Out of scope (here): - Authoring new themes — that is keryx theme add/edit (0001 §6). - Cross-brand comparison (different palettes/voices) beyond what a theme already encodes. - Animated/video panels (see 0003-video-panels.md).

3. Proposed surface

# render the workspace storyboard under each theme and build a montage
keryx reel compare -w <slug> --themes neon,tattoo,editorial [--silent] [-o compare.png]
# default theme set = all reel-type themes in the catalog
keryx reel compare -w <slug>
  • A new reel compare subcommand (sibling of reel build), so it inherits the workspace resolution and renderer seam.
  • --themes is a comma-list of reel-type theme keywords; omitted → every reel theme in the catalog.
  • --silent skips audio for the fast visual-only comparison.
  • -o/--out is the montage path (default under the workspace, e.g. compare/montage.png); the per-theme reels land under compare/<theme>.mp4.

4. Requirements (R-CMP-*)

  • R-CMP-1 (MUST) reel compare renders the same storyboard once per named theme, varying only the theme-driven visual layer (palette, card treatment, illustration style); VO/music selected takes are reused unchanged.
  • R-CMP-2 (MUST) with no --themes, the set is all reel-type themes in the resolved catalog, in catalog order.
  • R-CMP-3 (MUST) the output is a labelled comparison montage — one column (or tile) per theme, each labelled with its keyword — plus the individual per-theme reels kept on disk for side-by-side playback.
  • R-CMP-4 (MUST) --silent produces a no-audio comparison (storyboard dur timing), the cheap format proof; without it, audio is mixed per the normal build.
  • R-CMP-5 (SHOULD) comparison reuses the take/cache model so re-running with one extra theme renders only the new theme.
  • R-CMP-6 (MUST) an unknown theme keyword is a clear error naming the available reel themes (it does not silently skip).
  • R-CMP-7 (SHOULD) the montage frame chosen per theme is representative (e.g. a mid-reel overlay card), not a bookend, so the visual treatment is what is compared.
  • R-CMP-8 (MAY) emit machine-readable output (--output json) listing each theme → reel path for scripted pipelines.

5. Theme-authoring implications (from the experiment)

The experiment surfaced two theme-design constraints worth recording in the theme catalog guidance (0001 §6), independent of this command:

  • R-CMP-9 (SHOULD) theme illustration style prompts carry copyright-safe guidance — the Hokusai theme was rejected over a "copyright strike" worry; named living/▸distinctive-artist styles should be avoided in favour of described aesthetics.
  • R-CMP-10 (SHOULD) some styles leak text worse than others (the experiment saw neon/papercut/brutalist leak); the per-theme style should keep the hardened wordless instruction (0001 §3.1) and a theme MAY be flagged as leak-prone so cards sheet/OCR screening (R-GEN-26) is applied more strictly.

6. Open questions

  1. Montage format — single grid PNG of one frame per theme, an animated contact sheet (a few frames each), or a stitched side-by-side video? Start with the still grid (cheapest, matches cards sheet); revisit video later.
  2. Frame selection — fixed index, the first overlay card, or a per-theme "most representative" heuristic? (R-CMP-7 leans to first overlay card.)
  3. Promotion — after choosing, is there a reel compare --pick <theme> that stamps the workspace's theme, or does the user just reel build --theme?
  4. Cost guard — N themes × cards image-gen can be expensive; should compare default to --silent and reuse existing card takes unless --regen?