Skip to content

keryx reel

Manage and build reels. A reel workspace is the resumable unit of the authoring loop — see the Workspace concept.

Workspace lifecycle

keryx reel new <slug> [--theme <kw>] [--bundle <dir>] [--from-post <md>] [--force]
keryx reel list
keryx reel rename <old> <new>
keryx reel duplicate <src> <dst>      # copies authoring inputs, resets posting status
keryx reel rm <slug> --yes
keryx reel link <slug> <dir>          # associate a content directory (page bundle)
keryx reel prune <slug>               # drop candidate takes + cache (keep selected)
  • new scaffolds <root>/<slug>/ with workspace.yaml, an empty schema-valid storyboard.json, vo/ + cards/ dirs, and a .gitignore for takes/cache (refuses to clobber without --force — R-WS-4/5). --from-post marks the board unreviewed; keryx storyboard draft (LLM) seeds it later.
  • list enumerates the project's reels with status + theme + bundle (R-WS-16).
  • duplicate copies authoring inputs but not social.json — a copy hasn't been posted (R-WS-17); rename/rm are guarded (R-WS-18; rm requires --yes).
  • link records an associated content directory in workspace.yaml (R-WS-19).

The reel root defaults to reels/ (configurable via workspace.root).

keryx reel build

keryx reel build

Assemble a 9:16 reel from a storyboard — render each card, crossfade with ffmpeg, optionally mix a VO-driven audio track. A port of the blog gen-reel.py (spec §3.1).

keryx reel build --storyboard board.json [--cover cover.png] [--theme <kw>] [--silent] [--out reel.mp4]
keryx reel build --workspace <dir>       # uses <dir>/storyboard.json, vo/, music.mp3, cover.png
Flag Meaning
--storyboard storyboard.json path (standalone mode)
--workspace a reel workspace dir (storyboard.json, vo/*.mp3, music.mp3, cover.png)
--cover cover image for bookend cards
--theme reel theme (palette + card fonts/treatment); else the configured reel default
--silent render with no audio, using the storyboard dur timing — the fast pacing proof
--out output MP4 path (default reel.mp4)

How it builds

  1. Parse + validate the storyboard (exit 2 on schema errors — see Storyboard).
  2. Render each card to a PNG (block or overlay) in the theme's palette + fonts.
  3. Timing. --silent/no vo/ → storyboard dur; a workspace vo/ → VO-driven (card = VO + lead + tail; cards crossfade).
  4. Assemble with ffmpeg: an xfade chain, plus (when audio is present) the music bed ducked under the VO, mixed and limited.

Output is 1080×1920, 30fps, H.264 (+ AAC when there's audio).

keryx reel build --storyboard board.json --cover cover.png --silent --out draft.mp4
keryx reel build --workspace content/post/my-slug/reel --theme editorial

Notes

  • Rendering is provider-selected via providers.render (default local ffmpeg) — see Providers. Needs ffmpeg/ffprobe + the theme's card fonts (DejaVu by default).
  • Generated video panels are deferred to Phase 5; overlay cards use stills (generated or uploaded).