---
title: "ralphy render"
description: "Render a project to MP4. Engine: HyperFrames (HTML + GSAP). Writes <project>/render/final.mp4. Adds EBU R128 loudnorm with --loudnorm. Also auto-emits a compres"
---

{/* Auto-generated — edit `cli/commands/<verb>.ts` instead. Regenerate via `bun run docs:cli`. */}

## Summary

```bash
ralphy render [options] <project>
```

**Common flags**

| Flag | Description |
|---|---|
| `--composition <id>` | Composition id (default: index.html) |
| `--output <path>` | Output mp4 path (default: &lt;project&gt;/render/final.mp4) |
| `--from-clip <path>` | Pure-clip deliverable mode: faststart-wrap (and optionally loudnorm) an existing mp4 instead of running the HyperFrames engine. Logs to the project's gen-log so the single-entry-point invariant (AGENTS.md #2) holds. #009 |

**Example**

```bash
ralphy render spring-001
```

<Expandable title="Full reference">

**Flags**

| Flag | Description |
|---|---|
| `--composition <id>` | Composition id (default: index.html) |
| `--output <path>` | Output mp4 path (default: &lt;project&gt;/render/final.mp4) |
| `--from-clip <path>` | Pure-clip deliverable mode: faststart-wrap (and optionally loudnorm) an existing mp4 instead of running the HyperFrames engine. Logs to the project's gen-log so the single-entry-point invariant (AGENTS.md #2) holds. #009 |
| `--loudnorm` | Apply EBU R128 loudnorm (-16 LUFS) post-render via ffmpeg |
| `--fps <fps>` | Frame rate (default 30) |
| `--quality <quality>` | Quality preset: draft\|standard\|high (HyperFrames engine) OR web\|print\|archive (post-render CRF 23\|18\|12) |
| `--grade <preset>` | Color-grade preset post-render: tv-commercial-soft \| tv-commercial-strong \| cinematic-teal-orange \| analog-horror |
| `--format <format>` | Output format: mp4\|webm\|mov\|png-sequence (default mp4) |
| `--resolution <preset>` | Resolution preset: portrait\|landscape\|square\|1080p\|4k\|... |
| `--music-variants` | After the base render, mix one variant per &lt;project&gt;/artifacts/music/*.mp3 onto the final mp4. Writes render/final.&lt;music-basename&gt;.mp4 per bed. #049 (default: false) |
| `--music-volume <n>` | Music gain for --music-variants (default 0.18, background bed under VO) (default: 0.18) |
| `--no-compress` | Skip the auto social-compressed deliverable (render/final-social.mp4) |
| `--social-crf <n>` | x264 CRF for the auto social cut (default 20; raise for smaller files, lower for cleaner grain) (default: 20) |
| `--workers <n>` | Parallel capture workers (number or 'auto'). Lower to 1 for heavy compositions (many embedded videos / large GSAP timelines) that hit 'Runtime.callFunctionOn timed out' under the default auto fan-out. |
| `--dry-run` | Print the resolved render plan; no engine run (default: false) |
| `--summary` | Collapse the dry-run plan to a per-stage rollup (default: false) |
| `-h, --help` | display help for command |

**All examples**

```bash
ralphy render spring-001
ralphy render proj-001 --loudnorm
ralphy render proj-001 --output ./out.mp4
ralphy render proj-001 --fps 60 --quality high
ralphy render arena-rocker-001 --from-clip raw.mp4 --loudnorm
ralphy render proj-001 --no-compress              # master only, skip final-social.mp4
ralphy render proj-001 --social-crf 18            # higher-quality (larger) social cut
```

</Expandable>
