mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
James Russo
f7d2260f9d
* feat(engine): stamp rendered files with hidden renderer provenance * fix(engine,producer): re-assert provenance at every container writer Review found that a no-audio MOV render still shipped untagged. The concat step is the last container write on that path (mux is skipped without audio, and applyFaststart only copies mov/webm), and the concat demuxer does not carry the chunks' container metadata through. The same hole applies to no-audio WebM, and to the in-process chunked encode in chunkEncoder, not just the distributed assemble path. mp4 was masked throughout because applyFaststart re-runs ffmpeg for that format and re-tagged the output. Tags the four remaining writers: the chunked-encode concat, and assemble's single-chunk remux, concat and cfr re-encode. Also corrects the trust claim. These are unsigned, freely writable keys, so a present tag means the file claims to be HyperFrames output, not that HyperFrames wrote it. Documented as an unauthenticated diagnostic hint rather than an authenticity or attribution boundary. Tests assert on the assembled file through the real assemble() path for both mov and webm; both fail without the concat fix. * test(engine): pin provenance through the in-process chunked concat Review noted the distributed writers are mutation-pinned but the encodeFramesChunkedConcat fix had no real-file regression of its own. Encodes 70 frames at a 30-frame chunk size so the concat step actually runs, then asserts the tags on the resulting no-audio mov. Fails without the concat fix, passes with it.
206 lines
7.0 KiB
Plaintext
206 lines
7.0 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 |
|
||
|
||
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
|
||
```
|
||
|
||
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.
|
||
|
||
## 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 `standard` quality is the right choice for most finished work.
|
||
|
||
```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.
|
||
|
||
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)
|