mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
JamesandClaude Opus 4.6
db892f4e8f
Comprehensive audit of every documentation page against the actual source code, fixing incorrect APIs, wrong CLI flags, nonexistent templates, and missing public exports. Also documents the new agent-friendly CLI design. Key fixes: - Quickstart: `npx create-hyperframe` → `npx hyperframes init`, Node 20→22 - Templates: replaced nonexistent blank/title-card/video-edit with actual templates (blank, warm-grain, play-mode, swiss-grid, vignelli) - CLI: removed nonexistent short flags (-o/-f/-q/-w), added missing commands (browser, docs, telemetry, skills), documented agent-friendly non-interactive default and --human-friendly flag - Producer: replaced nonexistent `render()` API with actual `createRenderJob()`/`executeRenderJob()`, added server API docs - Engine: replaced nonexistent `createEngine()` with actual session-based API, added HfProtocol, encoding, streaming, parallel rendering docs - Core: fixed wrong type names (Composition/Clip→TimelineElement), wrong function names (parseHyperframeHtml→parseHtml), documented all 4 entry points (main, /lint, /compiler, /runtime) - Studio: added all missing exports (NLELayout, SourceEditor, PropertyPanel, FileTree, StudioApp, hooks, Tailwind preset) - All pages: --output not -o, Node 22+ not 20+ Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
151 lines
4.6 KiB
Plaintext
151 lines
4.6 KiB
Plaintext
---
|
|
title: Rendering
|
|
description: "Render compositions to MP4 locally or in Docker."
|
|
---
|
|
|
|
Render your Hyperframes [compositions](/concepts/compositions) to MP4 with the [CLI](/packages/cli). The rendering pipeline is frame-by-frame and seek-driven — see [Deterministic Rendering](/concepts/determinism) for how this works under the hood.
|
|
|
|
## Getting Started
|
|
|
|
<Steps>
|
|
<Step title="Verify your environment">
|
|
Run the diagnostics command to check for required dependencies:
|
|
|
|
```bash Terminal
|
|
npx hyperframes doctor
|
|
```
|
|
|
|
Expected output:
|
|
|
|
```
|
|
✓ Node.js v22.x
|
|
✓ FFmpeg 7.x
|
|
✓ FFprobe 7.x
|
|
✓ Chrome (bundled)
|
|
✓ Docker available
|
|
```
|
|
</Step>
|
|
<Step title="Preview your composition">
|
|
Before rendering, preview your composition in the browser to verify it looks correct:
|
|
|
|
```bash Terminal
|
|
npx hyperframes dev
|
|
```
|
|
</Step>
|
|
<Step title="Render to MP4">
|
|
Run the render command from your project directory:
|
|
|
|
```bash Terminal
|
|
npx hyperframes render --output output.mp4
|
|
```
|
|
|
|
Expected output:
|
|
|
|
```
|
|
⠋ Rendering composition "root" (30fps, standard quality)
|
|
✓ Captured 240 frames in 8.2s
|
|
✓ Encoded to output.mp4 (8.0s, 1920x1080, 4.2MB)
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Rendering Modes
|
|
|
|
<Tabs>
|
|
<Tab title="Local Mode">
|
|
### Local Mode (default)
|
|
|
|
Uses Puppeteer (bundled Chromium) and your system's FFmpeg. Fast for iteration during development.
|
|
|
|
**Requires:** FFmpeg installed on your system. See [Troubleshooting](/guides/troubleshooting) if FFmpeg is not found.
|
|
|
|
```bash Terminal
|
|
npx hyperframes render --output output.mp4
|
|
```
|
|
|
|
**Pros:**
|
|
- Fast startup, no container overhead
|
|
- Uses your system GPU for hardware-accelerated encoding (with `--gpu`)
|
|
- Best for iterative development
|
|
|
|
**Cons:**
|
|
- Output may vary across platforms due to font and Chrome version differences
|
|
- Not suitable for CI/CD pipelines that require reproducibility
|
|
</Tab>
|
|
<Tab title="Docker Mode">
|
|
### Docker Mode
|
|
|
|
[Deterministic](/concepts/determinism) output with an exact Chrome version and font set. Use this for production renders and CI pipelines.
|
|
|
|
**Requires:** Docker installed and running.
|
|
|
|
```bash Terminal
|
|
npx hyperframes render --docker --output output.mp4
|
|
```
|
|
|
|
**Pros:**
|
|
- Identical output on every platform — same Chrome, same fonts, same FFmpeg
|
|
- The same pipeline used in production
|
|
- Ideal for CI/CD and automated workflows
|
|
|
|
**Cons:**
|
|
- Slower startup due to container initialization
|
|
- No GPU acceleration inside the container
|
|
|
|
<Note>
|
|
Docker mode uses `chrome-headless-shell` with [BeginFrame](/concepts/determinism#how-it-works) control for frame-perfect, deterministic capture.
|
|
</Note>
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## When to Use Each Mode
|
|
|
|
| Scenario | Recommended Mode |
|
|
|----------|-----------------|
|
|
| Local development and iteration | Local |
|
|
| CI/CD pipeline | Docker |
|
|
| Sharing renders with a team | Docker |
|
|
| Quick preview export | Local |
|
|
| AI agent-driven rendering | Docker |
|
|
| Benchmarking performance | Local |
|
|
|
|
## Options
|
|
|
|
| Flag | Values | Default | Description |
|
|
|------|--------|---------|-------------|
|
|
| `--output` | path | `renders/<name>.mp4` | Output file path |
|
|
| `--fps` | 24, 30, 60 | 30 | Frames per second |
|
|
| `--quality` | draft, standard, high | standard | Encoding quality preset |
|
|
| `--workers` | 1-8 | 4 | Parallel render workers |
|
|
| `--gpu` | — | off | GPU encoding (NVENC, VideoToolbox, VAAPI) |
|
|
| `--docker` | — | off | Use Docker for [deterministic rendering](/concepts/determinism) |
|
|
| `--quiet` | — | off | Suppress verbose output |
|
|
|
|
## Tips
|
|
|
|
<Tip>
|
|
Use `draft` quality during development for fast previews. Switch to `standard` or `high` for final output.
|
|
</Tip>
|
|
|
|
- Use `npx hyperframes benchmark` to find optimal settings for your system
|
|
- 4 workers is usually the sweet spot for most compositions
|
|
- Docker mode is slower but guarantees [identical output](/concepts/determinism) across platforms
|
|
- For compositions with many frames, `--gpu` can significantly speed up local encoding
|
|
|
|
## Next Steps
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Deterministic Rendering" icon="lock" href="/concepts/determinism">
|
|
Understand the determinism guarantees
|
|
</Card>
|
|
<Card title="CLI Reference" icon="terminal" href="/packages/cli">
|
|
Full list of CLI commands and flags
|
|
</Card>
|
|
<Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
|
|
Fix common rendering issues
|
|
</Card>
|
|
<Card title="Common Mistakes" icon="triangle-exclamation" href="/guides/common-mistakes">
|
|
Avoid pitfalls that affect render output
|
|
</Card>
|
|
</CardGroup>
|