Skip to main content
ralphy render <project> is the one-shot path from a populated workspace to a finished mp4. The editor, audio, video, and voice verbs are the observability and post-processing helpers that bracket it — preflight checks before the render, ffmpeg recipes after. Per AGENTS.md invariant #5, there is no auto-launched Studio; iterations happen via ralphy generate + ralphy render, not Studio scrubbing.

​
ralphy render

Reads scenario.json + asset-manifest.json, drives HyperFrames (Puppeteer rasterizer + FFmpeg muxer) against workspace/projects/<id>/index.html, optionally post-processes with EBU R128 loudnorm. 
ralphy render demo-001
ralphy render demo-001 --loudnorm
ralphy render demo-001 --output ./out.mp4
ralphy render demo-001 --fps 60 --quality high
Output lands at workspace/projects/<id>/render/final.mp4. With --loudnorm, the raw render writes to final.raw.mp4 and the ffmpeg pass produces final.mp4 at -16 LUFS (TikTok/Reels target).
​
--output <path>
string
Custom output path. Default: workspace/projects/<id>/render/final.mp4.
​
--loudnorm
boolean
Post-process with loudnorm=I=-16:TP=-1.5:LRA=11. Adds a few seconds, fixes the “too quiet on mobile” problem.
​
--fps <fps>
number
Frame rate. Default: 30.
​
--quality <quality>
string
Quality preset: draft | standard | high. Default: standard.
​
--dry-run
boolean
Print the resolved render plan; skip the actual render.
Full surface: /reference/cli/render.

​
When it fails

HyperFrames render exits non-zero → the log line goes to generations.jsonl with status: "error" and E_INTERNAL raises with the last 500 bytes of stderr. Loudnorm failure → same, with the ffmpeg tail.

​
ralphy editor

Editor-stage observability — preflight every clip with ffprobe, sum durations, flag missing slots, surface aspect / fps / codec mismatches before the render. 
ralphy editor preflight demo-001
ralphy editor preflight demo-001 --expected-aspect 9:16 --expected-fps 30
ralphy editor trim-analyze demo-001    # per-clip gemini-vision dead-head/tail
preflight exits 1 on red — wire it into CI ahead of ralphy render and you’ll catch wrong-aspect leftovers from a model swap, missing scenes, codec drift. Full surface: /reference/cli/editor.

​
ralphy audio

Audio recipes wrapping cli/lib/ffmpeg-recipes.ts. Three recipes ship in v1: 
# EBU R128 loudnorm
ralphy audio loudnorm --in vo.mp3 --out vo.norm.mp3 --target -16

# Duck music under VO with a sidechain compressor → single mixed file
ralphy audio sidechain \
  --voice vo.norm.mp3 \
  --music bed.mp3 \
  --out scene-04-mix.mp3 \
  --ratio 8 --threshold 0.05

# Lossless concat via the concat demuxer
ralphy audio concat --files a.mp3,b.mp3,c.mp3 --out full.mp3
Each recipe appends a structured log line to generations.jsonl when --project is set. Full surface: /reference/cli/audio.

​
ralphy video

Video recipes — also cli/lib/ffmpeg-recipes.ts. Common subset: 
ralphy video extract-segment --in clip.mp4 --out cut.mp4 --start 2.4 --end 7.1
ralphy video optimize --in big.mp4 --out small.mp4 --crf 23 --tune grain
ralphy video burn-subs --in clip.mp4 --subs caps.srt --out subbed.mp4
ralphy video tonemap-hdr --in hdr.mp4 --out sdr.mp4
ralphy video concat --files a.mp4,b.mp4 --out full.mp4
ralphy video add-music-bed --in clip.mp4 --music bed.mp3 --out scored.mp4
optimize reports the compression ratio in the result. Full surface: /reference/cli/video.

​
ralphy voice

Pre-flight checks against the ElevenLabs voice library. The single most common mid-batch failure is a deleted voice ID; the exists verb catches it before the batch commits. 
ralphy voice exists pNInz6obpgDQGcFmaJgB    # 200 + metadata or hard exit
ralphy voice list                            # the user's library + clones
Full surface: /reference/cli/voice.

​
The render → eval → publish loop

ralphy editor preflight demo-001
ralphy render demo-001 --loudnorm
ralphy eval video workspace/projects/demo-001/render/final.mp4
eval is the quality gate after the render; see Eval and research. When eval flags issues, the agent regenerates the offending slots and re-runs render — iterations are CLI-native.