mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-03 04:07:03 +00:00
Miguel Ángel
b306438e8b
* feat(cli): cloud render uploads heavy media as HeyGen assets Media of 5 MB or more leaves the project zip: it uploads through the direct-upload flow as a HeyGen asset and the zip's HTML and CSS point at the asset URL. Uploads are cached by content hash and re-checked before reuse. Media the asset API refuses or caps is re-encoded at visually lossless quality first. The zip must end under 200 MB or the command stops and names the largest files left. * feat(cli): cloud render offloads GIFs, still images and script-referenced media Animated GIFs in the entry composition go through the renderer's own GIF preparation and upload as the resulting video. Still AVIF, GIF, BMP and TIFF images convert to PNG. Plain string literals in scripts and JSON that name offloaded media point at the asset URL. ffprobe calls end their options with "--", and two comment lines are trimmed for the ratchet. * feat(cli): cloud render uploads only the parts of long media a composition plays A video or audio file that has to be re-encoded is cut to the union of the windows its clips play, with half a second of margin on the source's frame grid, and the staged composition's media starts shift to match. Clips in sub-compositions, looping clips, speed ramps and files a script names keep the full file. * fix(cli): cloud render no longer decodes media files as text when rewriting references * fix(cli): cloud render keeps media chosen at render time and encodes the staged bytes Only media a reference points at is offloaded, so a file picked through --variables or built by a script stays in the zip. Variable-bound clips and clips with a media fragment keep their full length. Entry GIFs resolve the way the renderer rebases a nested entry and are prepared only from 5 MB, and every encode reads the staged bytes its cache key hashes. Query strings and media fragments survive the rewrite, a null cache file reads as empty, and the docs say asset URLs are public and unsigned. * fix(cli): cloud render comments cite only what this repo holds * fix(cli): cloud render handles media over 2 GiB and explains a too-large upload Media of 5 MB or more stays on disk until it is used: it is hashed and uploaded as a stream, and a file edited after staging stops the run instead of caching the wrong upload. Files left in the zip are sized before any is read, so a 4 GB file reports "too large" instead of crashing. The asset API rejects an over-limit upload as invalid_parameter with "File too large"; that now gets the dry-run hint instead of the --help one. * fix(cli): cloud render checks and reads each staged file through one handle Staging, the on-disk staged read and the re-encoded output read each opened the path twice: once to stat, once to read. A file swapped or edited between the two could be read without the size or change check seeing it. Each now opens once, checks the open file's stat before and after the read, and reads from it. * test(cli): a heavy file a script builds from split strings stays in the cloud render zip * fix(cli): cloud render keeps media scripts may reach and never trims clips scripts retime - An offloaded file keeps its zip copy when script code holds both its stem and extension, so a path joined at runtime still loads. - Entry GIFs are prepared from a private copy checked against the staged file, so the GIF cache never stores a later edit. - No cut when any script can write a clip's timing attributes, dataset, currentTime, playbackRate, src or loop.
131 lines
4.3 KiB
Plaintext
131 lines
4.3 KiB
Plaintext
---
|
||
title: Cloud rendering
|
||
description: Render on HeyGen's managed cloud without deploying your own infrastructure.
|
||
---
|
||
|
||
Use managed cloud rendering when you want a finished file without installing Chrome or FFmpeg or maintaining AWS or Google Cloud infrastructure.
|
||
|
||
## Render a project
|
||
|
||
Sign in once, then render the current project:
|
||
|
||
```bash
|
||
hyperframes auth login
|
||
hyperframes cloud render
|
||
```
|
||
|
||
The command packages the project, uploads it, waits for the render, and downloads the finished file to `renders/`.
|
||
|
||
Choose a composition or output path when the defaults are not right:
|
||
|
||
```bash
|
||
hyperframes cloud render . \
|
||
--composition compositions/intro.html \
|
||
--output renders/intro.mp4
|
||
```
|
||
|
||
From an attended SSH or headless terminal, use the device flow. Open the displayed URL in any browser and enter the one-time code:
|
||
|
||
```bash
|
||
hyperframes auth login --device
|
||
```
|
||
|
||
Device login requires a TTY and is refused in CI. For unattended agents and CI, save a long-lived API key instead:
|
||
|
||
```bash
|
||
echo "$HEYGEN_API_KEY" | hyperframes auth login --api-key
|
||
```
|
||
|
||
See [Authentication and API keys](/guides/authentication) for credential precedence and local alternatives.
|
||
|
||
## Choose the output
|
||
|
||
| Option | Values | Default |
|
||
| --- | --- | --- |
|
||
| `--fps` | 1–240 | `30` |
|
||
| `--quality` | `draft`, `standard`, `high` | `standard` |
|
||
| `--format` | `mp4`, `webm`, `mov` | `mp4` |
|
||
| `--resolution` | `1080p`, `4k` | `1080p` |
|
||
| `--aspect-ratio` | `16:9`, `9:16`, `1:1` | detected from a local composition when possible |
|
||
|
||
```bash
|
||
hyperframes cloud render --quality high --fps 60
|
||
hyperframes cloud render --resolution 4k
|
||
```
|
||
|
||
<Warning>
|
||
4K is billed at 1.5× and supports MP4 only. WebM and MOV use the alpha-capable path, which does not support 4K supersampling.
|
||
</Warning>
|
||
|
||
## Check what will upload
|
||
|
||
Media files of 5 MB or more that the project names by path upload as HeyGen assets and are referenced by public, unsigned URL, so large footage and audio do not count against the 200 MB project archive limit. Uploads are cached, so re-rendering uploads only new or changed media. Media is streamed from disk as it uploads, so a large file never has to fit in memory; editing one while the command is preparing it stops the run. Inspect what will upload before starting a render:
|
||
|
||
```bash
|
||
hyperframes cloud render --dry-run
|
||
```
|
||
|
||
Add generated or unnecessary files to `.hyperframesignore` when needed:
|
||
|
||
```gitignore
|
||
/exports/
|
||
/source-masters/
|
||
```
|
||
|
||
Do not exclude media that the composition needs at render time. HyperFrames already omits common development and generated paths, including `.git`, `node_modules`, root-level `renders/`, and root-level `snapshots/`.
|
||
|
||
## Fill template variables
|
||
|
||
Use the variables declared by the composition:
|
||
|
||
```bash
|
||
hyperframes cloud render \
|
||
--variables '{"title":"Q4 recap","theme":"dark"}' \
|
||
--strict-variables
|
||
```
|
||
|
||
For larger payloads, pass a JSON file with `--variables-file`.
|
||
|
||
The first `hyperframes cloud render` that uploads a local project prints an `asset_id`. Reuse it to
|
||
render the same uploaded project with different values:
|
||
|
||
```bash
|
||
hyperframes cloud render \
|
||
--asset-id asst_abc123 \
|
||
--variables '{"title":"Customer update"}'
|
||
```
|
||
|
||
## Run asynchronously
|
||
|
||
Submit without waiting and receive a webhook when the render finishes:
|
||
|
||
```bash
|
||
hyperframes cloud render \
|
||
--callback-url https://example.com/hyperframes-hook \
|
||
--no-wait
|
||
```
|
||
|
||
Then inspect or manage renders by ID:
|
||
|
||
```bash
|
||
hyperframes cloud list
|
||
hyperframes cloud get hfr_abc123
|
||
hyperframes cloud delete hfr_abc123
|
||
```
|
||
|
||
For automated retries, pass a stable `--idempotency-key` so an interrupted request can be replayed safely.
|
||
|
||
## Choose another renderer
|
||
|
||
- Use [`hyperframes render`](/guides/rendering) while authoring or when the machine running the command should do the work.
|
||
- Use [AWS Lambda](/deploy/aws-lambda) or [Google Cloud Run](/deploy/gcp-cloud-run) when you need to own the rendering infrastructure.
|
||
- Use a [deployment template](/guides/deploy) when you need a working hosted starting point rather than the full distributed-rendering stack.
|
||
|
||
See the [CLI reference](/packages/cli#hyperframes-cloud) for every flag and JSON output shape.
|
||
|
||
## Related topics
|
||
|
||
- [Compare every rendering path](/deploy/overview)
|
||
- [Render locally from the CLI](/guides/rendering)
|
||
- [Operate rendering in your own cloud account](/deploy/aws-lambda)
|