mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
JamesandClaude Opus 4.6
915fe2f47a
Major improvements across all 18 pages: - Use Mintlify components: <Steps> for tutorials, <Tabs> for alternatives, <CodeGroup> for multi-platform commands, <Tree> for directory structures, <AccordionGroup> for FAQ/scannable content, <Mermaid> for diagrams - Add filename annotations to all code blocks (e.g., ```html index.html) - Add numbered comments inside multi-step code examples - Show expected terminal output after CLI commands - Add "When to use" / "When NOT to use" sections to all package pages - Add "Next Steps" CardGroup to every page (no dead-end pages) - Cross-link between pages at point of curiosity (not just "see also" dumps) - Expand thin pages (engine, studio) with architecture details and examples - Add decision guides (rendering modes, template selection) - Use <Warning> and <Note> sparingly (max 2-3 per page) Also adds DOCS_GUIDELINES.md at repo root with writing standards. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
149 lines
4.5 KiB
Plaintext
149 lines
4.5 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 20.x
|
|
✓ FFmpeg found (7.x)
|
|
✓ Docker available
|
|
✓ Disk space OK
|
|
```
|
|
</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 -o 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 -o 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 -o 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 |
|
|
|------|--------|---------|-------------|
|
|
| `-f, --fps` | 24, 30, 60 | 30 | Frames per second |
|
|
| `-q, --quality` | draft, standard, high | standard | Encoding quality preset |
|
|
| `-w, --workers` | 1-8 | auto | Parallel render workers |
|
|
| `--gpu` | — | off | GPU encoding (NVENC, VideoToolbox, VAAPI) |
|
|
| `-o, --output` | path | — | Output file path |
|
|
| `--docker` | — | off | Use Docker for [deterministic rendering](/concepts/determinism) |
|
|
|
|
## 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>
|