mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-02 19:57:13 +00:00
Jerrai
7a34d6fbe4
* docs: align render, fps and transcribe docs with the CLI - docs/guides/rendering.mdx: default render quality is `looks` (CRF 16), not `standard`. - docs/packages/cli.mdx, render --help (render.ts): default --output is the timestamped `renders/<project>_<YYYY-MM-DD>_<HH-MM-SS>.<ext>`. - skills/hyperframes-cli/references/preview-render.md: local --fps accepts 1-240 or a rational and defaults to the root data-fps, else 30; only lambda and cloudrun are limited to 24, 30, 60. - skills/hyperframes-cli/references/lint-validate-inspect.md: snapshot --range is documented as START,END like every other reference. - skills/media-use/references/audio.md, skills/media-use/audio/references/ transcribe.md, skills/hyperframes/references/captions.md: name the entry point for each transcription default (transcribe.mjs prefers Parakeet; `hyperframes transcribe` uses Parakeet when installed, else the small.en whisper model). - transcribe --model help text and docs/packages/cli.mdx: list `small` and `medium`, which the CLI already accepts. - skills-manifest.json: regenerated hashes for the three skills touched. — Jerrai * docs: lambda and cloud run also accept 25 fps Distributed renders accept 24, 25, 30 and 60 fps (DISTRIBUTED_FPS in packages/core/src/distributedFps.ts). - skills/hyperframes-cli/references/preview-render.md: the --fps note lists 24, 25, 30, 60 for lambda and cloudrun. - skills/hyperframes-cli/references/lambda.md, cloudrun.md: --fps lists include 25. - packages/cli/src/docs/rendering.md (`hyperframes docs rendering`): --fps said 24, 30 or 60 and --quality defaulted to standard; local render takes 1-240 or a rational, default root data-fps else 30, and the default quality is looks. - skills-manifest.json: regenerated hyperframes-cli hash. — Jerrai * chore(skills): regenerate skills manifest after formatting The format hook rewrote skill markdown after the manifest hook had hashed it, leaving the hyperframes-cli hash stale. — Jerrai
247 lines
8.9 KiB
Plaintext
247 lines
8.9 KiB
Plaintext
---
|
||
title: "Render from the command line"
|
||
description: "Check a project and render MP4, MOV, WebM, GIF, or PNG output."
|
||
---
|
||
|
||
import { DocsVideo } from "/snippets/docs-video.jsx";
|
||
|
||
Studio is the simplest place to export a project. Use the command line when an agent, script, CI job, or advanced delivery workflow needs to control the render.
|
||
|
||
<DocsVideo
|
||
title="One command turns the project into an MP4"
|
||
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/render-loop-demo-v2.mp4"
|
||
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/render-loop-demo-v2.jpg"
|
||
/>
|
||
|
||
The whole loop: the project, the render command, progress, and the finished file
|
||
playing. The flags shown are the ones people actually reach for — format,
|
||
resolution, frame rate, quality.
|
||
|
||
## Render a normal video
|
||
|
||
From the project folder:
|
||
|
||
```bash
|
||
npx hyperframes render --output final.mp4
|
||
```
|
||
|
||
If you omit `--output`, HyperFrames writes the result under `renders/`.
|
||
|
||
The normal workflow is:
|
||
|
||
```bash
|
||
npx hyperframes lint
|
||
npx hyperframes check
|
||
npx hyperframes render --output final.mp4
|
||
```
|
||
|
||
`lint` checks the project structure. `check` opens the project in a browser and looks for runtime, layout, motion, media, and contrast problems.
|
||
|
||
## Choose a format
|
||
|
||
| Format | Use it for |
|
||
| ------------ | ---------------------------------------------------------- |
|
||
| MP4 | Normal sharing, publishing, and delivery |
|
||
| MOV | ProRes workflows and transparent editing intermediates |
|
||
| WebM | Web delivery and transparent overlays |
|
||
| GIF | Short previews in issues, pull requests, and documentation |
|
||
| PNG sequence | Frame-by-frame handoff to compositing software |
|
||
| HLS | VOD streaming from a playlist directory |
|
||
|
||
Examples:
|
||
|
||
```bash
|
||
# Transparent web overlay
|
||
npx hyperframes render --format webm --output overlay.webm
|
||
|
||
# ProRes editing file
|
||
npx hyperframes render --format mov --output master.mov
|
||
|
||
# Short looping preview
|
||
npx hyperframes render --format gif --fps 15 --output preview.gif
|
||
|
||
# RGBA frames in a directory
|
||
npx hyperframes render --format png-sequence --output frames
|
||
|
||
# HLS VOD stream in a directory
|
||
npx hyperframes render --format hls --output stream
|
||
```
|
||
|
||
GIF has no audio and limited transparency. Prefer MP4 or WebM for normal playback.
|
||
|
||
### Transparent video
|
||
|
||
Use WebM for a transparent web overlay or MOV for a ProRes 4444 editing
|
||
intermediate. Leave the composition background unpainted wherever the output
|
||
must remain transparent; an opaque `html`, `body`, or full-frame background
|
||
will be encoded as visible pixels.
|
||
|
||
```bash
|
||
npx hyperframes render --format webm --output overlay.webm
|
||
npx hyperframes render --format mov --output overlay.mov
|
||
```
|
||
|
||
MP4 is the normal opaque delivery format. After rendering transparency, inspect
|
||
the file over a contrasting background rather than trusting a player that
|
||
always shows black behind alpha.
|
||
|
||
For VP9 WebM, `ffprobe` reporting `pix_fmt=yuv420p` does not by itself mean
|
||
transparency was lost. FFmpeg's default VP9 decoder can also produce an opaque
|
||
image from a file that contains alpha. To inspect a frame, explicitly select
|
||
the alpha-aware decoder **before** the input:
|
||
|
||
```bash
|
||
ffmpeg -c:v libvpx-vp9 -i overlay.webm -frames:v 1 -pix_fmt rgba overlay-frame.png
|
||
```
|
||
|
||
View the PNG over a checkerboard or contrasting background. If it is still
|
||
opaque, compare it with the composition's PNG-sequence output to check whether
|
||
transparency was already missing before video encoding.
|
||
|
||
### HLS streaming output
|
||
|
||
`--format hls` writes an HLS VOD stream into the output **directory**:
|
||
`master.m3u8`, `video.m3u8` and `video_NNNNN.ts`, plus `audio.m3u8` and
|
||
`audio_NNNNN.ts` when the composition has audio. The video and audio encodes
|
||
are identical to MP4; only the delivery container differs, and packaging is a
|
||
stream copy rather than a second encode.
|
||
|
||
```bash
|
||
npx hyperframes render --format hls --output stream
|
||
npx hyperframes render --format hls --hls-segment-seconds 6 --output stream
|
||
```
|
||
|
||
Segments are exactly `--hls-segment-seconds` long (default 4) except the last,
|
||
and every segment starts on a keyframe. HLS output is SDR only, so `--hdr` is
|
||
rejected, and `--gpu` is rejected because GPU encoders ignore the forced-keyframe
|
||
lock that fixed-length segments depend on. Cloud rendering (`lambda`,
|
||
`cloudrun`) does not offer HLS yet.
|
||
|
||
## Input video codecs
|
||
|
||
Studio, preview, `check`, and published projects normally create cached browser
|
||
proxies for local video that Chrome cannot decode reliably, including common
|
||
HEVC and ProRes inputs. The original file stays in the project and remains the
|
||
render source.
|
||
|
||
If a clip is black only in preview, keep automatic proxying enabled, confirm the
|
||
source is local, and run `npx hyperframes check`. Disable proxying only when the
|
||
browser already supports the source or you are diagnosing the proxy itself.
|
||
|
||
## Choose quality and frame rate
|
||
|
||
The default `looks` quality (CRF 16) is the right choice for most finished work.
|
||
MOV is an alpha-preserving editing intermediate and always uses the fixed
|
||
ProRes 4444 profile. `--crf` and `--video-bitrate` do not map to that profile
|
||
and are rejected for MOV; choose MP4 or WebM when you need those controls.
|
||
|
||
```bash
|
||
# Faster review version
|
||
npx hyperframes render --quality draft --output review.mp4
|
||
|
||
# Larger final master
|
||
npx hyperframes render --quality high --output master.mp4
|
||
|
||
# Explicit frame rate
|
||
npx hyperframes render --fps 60 --output final-60fps.mp4
|
||
```
|
||
|
||
Use a higher frame rate only when the source or destination needs it. It creates more frames, so rendering takes longer.
|
||
|
||
The CLI uses the composition’s `data-fps` when present and otherwise defaults to 30 fps.
|
||
|
||
## Local or Docker
|
||
|
||
Local rendering is the normal choice:
|
||
|
||
```bash
|
||
npx hyperframes render --output final.mp4
|
||
```
|
||
|
||
It starts quickly and can use the computer’s browser GPU.
|
||
On WSL2, Chrome may not reach the GPU; see
|
||
[the render is slow under WSL2](/guides/troubleshooting#the-render-is-slow-under-wsl2).
|
||
|
||
Use Docker when a controlled Chrome, FFmpeg, and font environment matters:
|
||
|
||
```bash
|
||
npx hyperframes render --docker --output final.mp4
|
||
```
|
||
|
||
Docker adds startup and infrastructure overhead. It is useful for CI and repeatable production environments, not a requirement for every final render.
|
||
|
||
## Render another composition
|
||
|
||
The root `index.html` is rendered by default. To target another standalone composition:
|
||
|
||
```bash
|
||
npx hyperframes render \
|
||
--composition compositions/intro.html \
|
||
--output intro.mp4
|
||
```
|
||
|
||
Nested compositions that use `<template>` wrappers should be rendered through the root composition that includes them.
|
||
|
||
## Batch and cloud work
|
||
|
||
For several variable-driven versions, use batch rendering. For remote infrastructure, use HyperFrames cloud, AWS Lambda, or Google Cloud Run.
|
||
|
||
Those workflows involve output naming, credentials, concurrency, and infrastructure choices. Start in the [CLI guide](/developers/cli) and use the complete [CLI reference](/packages/cli) when you need every flag.
|
||
|
||
## Render provenance
|
||
|
||
Rendered video carries two container metadata tags that say which tool wrote the file:
|
||
|
||
```bash
|
||
ffprobe -v error -show_entries format_tags -of json out.mp4
|
||
```
|
||
|
||
```json
|
||
{ "hyperframes_renderer": "hyperframes", "hyperframes_version": "0.7.107" }
|
||
```
|
||
|
||
That is the whole of it. The tags name the renderer and its version, and nothing else: no file
|
||
paths, usernames, machine names, project names, or anything about the composition. They are
|
||
container metadata, not a visible watermark, so no pixel of your video changes. Matroska
|
||
uppercases tag names on read, so a `.webm` reports `HYPERFRAMES_RENDERER`.
|
||
|
||
Strip them whenever you like:
|
||
|
||
```bash
|
||
ffmpeg -i out.mp4 -map_metadata -1 -c copy clean.mp4
|
||
```
|
||
|
||
<Note>
|
||
These tags are an unauthenticated diagnostic hint, not proof of origin. They are ordinary unsigned
|
||
container keys, so anything can write the same two values with a single `ffmpeg -metadata`
|
||
command: a tag that is present means the file *claims* to be HyperFrames output, not that
|
||
HyperFrames wrote it. A tag that is absent means just as little, because re-encoding, remuxing, or
|
||
any tool that drops unknown keys strips it, and files rendered by older versions never carried it.
|
||
Treat it as a "what probably produced this file?" hint for support and debugging, never as an
|
||
authenticity, attribution, or licensing check. Verifiable provenance needs signed claims such as
|
||
C2PA.
|
||
</Note>
|
||
|
||
## If rendering fails
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npx hyperframes doctor
|
||
npx hyperframes lint
|
||
npx hyperframes check
|
||
```
|
||
|
||
Keep the first exact error rather than only the final “render failed” message. See [Troubleshooting](/guides/troubleshooting) for the next checks.
|
||
|
||
<Tip>
|
||
Always watch the exported file itself. Preview proves that the project can play; the output file
|
||
proves that the delivery is correct.
|
||
</Tip>
|
||
|
||
## Related topics
|
||
|
||
- [Compare local, hosted, and self-managed rendering](/deploy/overview)
|
||
- [Render and export from Studio](/studio/export)
|
||
- [Diagnose a failed render](/guides/troubleshooting)
|