Skip to content

keryx reel plan

Description

A read-only pre-flight for a reel: what it will time out to, and what's still missing. reel plan reports a workspace's real VO-driven timing and flags pre-build gaps — generating and rendering nothing. It answers the two questions you have before a build: how long will this reel be (so I can size the music bed)? and is anything going to silently downgrade or break? (spec 0024).

It uses the same timing computation as reel build (ReelTimingForBoard), so the total it prints is the total the build assembles — and the music-bed length it reports is exactly what music gen --takes would request. Each promoted vo/NN.mp3 clip is bound to its own card by line number; on a mixed board (some cards VO'd, some not) the VO-less cards fall back to their storyboard dur. With no promoted VO at all it degrades to the storyboard dur (silent-render) timing and says so, rather than erroring.

Usage

keryx reel plan --workspace <slug> [flags]

Behaviour

  • Read-only. No generation, no render — just probes the promoted VO for timing.
  • Per-card timing. For each card: its 1-based index, on-screen dur, start offset, vo_delay, and the duration source — vo (a promoted vo/NN.mp3 clip) or storyboard (the dur fallback when that card has no VO).
  • Totals. The VO-driven reel total and the implied music bed length (the VO-driven total, or a 35s default when no VO sizes it) — so the bed can be sized confidently without summing ffprobe durations by hand.
  • Pre-build gaps. Flags what would silently downgrade or break a build:
  • missing_vo — a card with no promoted VO (→ silent fallback for that card),
  • unpromoted_takes — VO takes were generated but none selected (run voice pick),
  • missing_media — an overlay card with a scene but no selected illustration,
  • missing_cover — no cover.png,
  • no_music — no music bed.
  • Reproducibility signal. Reports how many selected assets are locked (approved) vs merely selected; when every selected asset is locked, the reel is "reproducible from committed inputs" (see reel lock).
  • Machine-readable. --output json emits the timing, gaps, and selected/locked counts for the studio / CI.
  • Backend-neutral probe. VO is timed through the backend selected by providers.render — a default-ffmpeg setup needs the binary; an afmpeg setup probes in-memory (zero-config). Mirrors how reel build resolves its renderer.

Flags

Flag Effect
-w, --workspace <slug> the reel workspace (required)
--output json emit the timing + gaps as JSON (global flag)

Run keryx reel plan --help for the authoritative, always-current flag set.

Example

# Where does this reel time out, and what's still missing?
keryx reel plan --workspace my-post

reel plan: my-post  [VO-driven]

card  dur    start  vo_delay  source
1     3.200  0.000  0.500     vo
2     4.100  2.800  3.300     vo
3     2.700  6.500  7.000     vo

total: 9.600s   music bed: 9.600s (9600ms)
assets: 4 selected, 2 locked

2 pre-build gap(s):
  - [missing_media] card 2: overlay card has no selected illustration
  - [no_music] no music bed

# Size the music bed from the plan, then generate it.
keryx reel plan -w my-post --output json | jq .data.bed_length_ms
keryx music gen -w my-post --takes 3        # bed defaults to the same VO-driven total

See also