Editor

Editor playbook

Read this when: "compose the video", "do the render", "render", "preview", "fix captions", "audio mix", "final cut", "tighten transitions".

Composer + renderer. I take scenario.json + asset-manifest.json, assemble an HTML composition with GSAP, and render an MP4 via HyperFrames. I do not generate media — that's the art director. I stitch, time, transition, caption, mix, sanity-check.

STOP rule. Render only via ralphy render. FFmpeg only via ralphy audio / ralphy video. No direct bunx hyperframes render outside debugging, no ad-hoc ffmpeg shells — every recipe is a verb that auto-logs. AGENTS invariant #2.

Engine

HyperFrames is the only render engine. Every project must ship .ralphy/workspaces/<ws>/projects/<id>/index.html. See hyperframes for composition rules, GSAP timelines, registry blocks, captions, transitions, audio mixing.

CLI cookbook

Render only via ralphy render. FFmpeg only via ralphy audio / ralphy video. Never call bunx hyperframes render directly outside debugging, and never shell out to ad-hoc ffmpeg — every recipe below is a verb that auto-logs.

# Final render
ralphy render <project-id> [--loudnorm]
ralphy render <project-id> --fps 60 --quality high

# Captions
ralphy generate captions --project <id> --audio <vo.mp3>     # → captions.json (Caption[])
# HyperFrames also ships a built-in word-level transcriber:
bunx hyperframes transcribe --in <vo.wav> -o captions.json

# Audio recipes — wrap cli/lib/ffmpeg-recipes.ts
ralphy audio loudnorm  --in <vo.mp3>  --out <vo-norm.mp3>           # -16 LUFS for TikTok / Reels
ralphy audio sidechain --voice <vo>   --music <m> --out <mix.mp3>   # duck music under VO
ralphy audio concat    --files a.mp3,b.mp3,c.mp3 --out concat.mp3   # lossless concat

# Video recipes
ralphy video extract-segment --in <src.mp4> --start 1.2 --end 4.5 --out <seg.mp4>
ralphy video burn-subs       --in <src.mp4> --srt <subs.srt> --out <final.mp4>   # last step
ralphy video tonemap-hdr     --in <hdr.mp4> --out <sdr.mp4>                       # HDR → Rec.709
ralphy video concat          --files a.mp4,b.mp4 --out concat.mp4

# HyperFrames iteration loop (foreground only — no auto-Studio)
bunx hyperframes preview .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes lint    .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes inspect .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes add <block-slug> .ralphy/workspaces/<ws>/projects/<id>

# Inspect inputs / outputs
ralphy project show <id> --assets        # asset-manifest before composing
ralphy project show <id> --status        # what's done / missing
ralphy project log <id> --type generations --limit 50    # ffmpeg + render entries

For HyperFrames API specifics (composition rules, GSAP timelines, captions, transitions, registry blocks) read hyperframes — that's the reference manual, not this playbook.

Extending a stylized clip (i2v last-frame anchor + full 15s blocks)

When the user asks to "extend" / lengthen an existing stylized clip (toon, painterly, Spider-Verse / Arcane register), don't generate a fresh disconnected clip — anchor a new i2v clip from the last frame of the existing one so the join is seamless:

1. Extract the final frame: ralphy video extract-segment (or an ffmpeg -sseof tail-frame grab via a ralphy video recipe) of the last ~0.15s → one PNG.
2. Feed that PNG as the --first-frame of a new ralphy generate video i2v call on bytedance/seedance-2.0. The new clip starts on the real last frame, so the cut is invisible. (Stylized/painterly anchors don't trip seedance's photoreal-human privacy filter — that filter only fires on photoreal human faces, see feedback_seedance_rejects_realistic_people.)
3. Default the extension to a full 15s block, not 5s. Short extensions feel rushed and lose dynamics; a 15s block has room for a real beat (e.g. solo → camera orbit revealing the crowd → finale) and the stylized register comes through stronger on action-heavy long blocks than on static wides. Emphasize a moving camera (orbit / crane) for dynamics. Keep the SUBJECT / STYLE / AUDIO-POLICY prompt blocks verbatim across blocks.
4. ralphy video concat the blocks, regenerate a music bed sized to the FULL new length with the climax aligned to the finale, then ralphy audio sidechain (duck music under VO) and copy to render/final.mp4.

Does NOT apply to: photoreal-human clips (seedance rejects the anchor — extend via kwaivgi/kling-v3.0-pro instead); slow static / dialogue-driven beats where a 5s extension is the right length; cases where the new beat is a hard scene change rather than a continuation (then it's a new scene, not an extend, and the last-frame anchor is unnecessary).

Sub-docs (read on demand)

Sub-tasks

What I read on start

1. Run ralphy editor preflight <id> first. Single canonical check for durations, fps, codec, audio tracks, music-gap vs total clip length, and scenario-to-disk completeness. Exits 1 on red — fix before composing. Replaces every project's ad-hoc ffprobe loop. (#034)
2. Then ralphy editor trim-analyze <id>. Batch gemini-3.1-pro-preview vision pass over artifacts/videos/ for dead-time / hot-moments / suggested trim_in_s / trim_out_s per clip. Aggregates to artifacts/analysis/summary.json (idempotent via mtime — re-runs only re-analyze changed clips). Use --dry-run to preview the plan + cache state. Canonical solver for kling/seedance ~1s overshoot (#042). (#034)
3. AGENTS.md — invariants (no auto-Studio, no scripts, ralphy render).
4. hyperframes playbook — reference manual for HyperFrames composition / captions / transitions / GSAP / registry.
5. art-director/pre-render-checklist.md — HARD snapshot-review gate the art-director must clear before handing off. If you arrived here without snapshots on disk, bounce back to art-director.
6. .ralphy/workspaces/<ws>/projects/<id>/scenario.json — structure and timings.
7. .ralphy/workspaces/<ws>/projects/<id>/asset-manifest.json — asset paths.

• .ralphy/workspaces/<ws>/projects/<id>/index.html — the composition.
• .ralphy/workspaces/<ws>/projects/<id>/design.md — brand source-of-truth (HyperFrames skill gate).
• docs/green-zone.md for text positioning.