> ## Documentation Index
> Fetch the complete documentation index at: https://ralphy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ralphy render

> 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

## Summary

```bash theme={"dark"}
ralphy render [options] <project>
```

**Common flags**

| Flag                 | Description                                                                                                                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--composition <id>` | Composition id (default: index.html)                                                                                                                                                                                         |
| `--output <path>`    | Output mp4 path (default: \<project>/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 theme={"dark"}
ralphy render spring-001
```

<Expandable title="Full reference">
  **Flags**

  | Flag                    | Description                                                                                                                                                                                                                  |
  | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `--composition <id>`    | Composition id (default: index.html)                                                                                                                                                                                         |
  | `--output <path>`       | Output mp4 path (default: \<project>/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 \<project>/artifacts/music/\*.mp3 onto the final mp4. Writes render/final.\<music-basename>.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.                     |
  | `--force-overwrite`     | Disable append-only auto-archiving — overwrite render/final.mp4 and render/final-social.mp4 in place instead of archiving the prior copies to final.v{N}.mp4 / final-social.v{N}.mp4 (#118) (default: false)                 |
  | `--no-fix-letterbox`    | Skip the post-render letterbox auto-crop. HyperFrames bakes a solid black bar under \<video> compositions; the heal runs by default and is a no-op when the frame is already clean.                                          |
  | `--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 theme={"dark"}
  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>