diff --git a/.github/actions/install-ffmpeg-windows/action.yml b/.github/actions/install-ffmpeg-windows/action.yml index 5e89ea01d..43dea7b92 100644 --- a/.github/actions/install-ffmpeg-windows/action.yml +++ b/.github/actions/install-ffmpeg-windows/action.yml @@ -15,7 +15,7 @@ inputs: behavior under us. The asset filename embeds the git hash, so both the tag and the filename must be bumped together when upgrading. required: false - default: https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-04-23-13-16/ffmpeg-N-124085-g162ad61486-win64-gpl.zip + default: https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-04-30-13-44/ffmpeg-N-124278-gcc3ca17127-win64-gpl.zip max-attempts: description: Max download attempts before failing. required: false diff --git a/docs/docs.json b/docs/docs.json index 314a74f98..025e5600b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -80,6 +80,7 @@ "guides/deploy", "guides/remove-background", "guides/hdr", + "guides/4k-rendering", "guides/performance", "guides/timeline-editing", "guides/video-editor-cheatsheet", diff --git a/docs/guides/4k-rendering.mdx b/docs/guides/4k-rendering.mdx new file mode 100644 index 000000000..dd9170036 --- /dev/null +++ b/docs/guides/4k-rendering.mdx @@ -0,0 +1,159 @@ +--- +title: 4K Rendering +description: "Render any composition to 4K (3840×2160) without rewriting it — the CLI supersamples a 1080p composition via Chrome's device scale factor." +--- + +Hyperframes renders to 4K (3840×2160) two ways. Both produce a true 4K MP4; pick the one that matches your project. + + + + Scaffold the project at 4K so the composition is laid out at 4K natively. Best when you want crisp 4K-native typography and assets. + ```bash + npx hyperframes init my-video --resolution 4k + ``` + + + Keep your existing 1080p composition. Pass `--resolution 4k` at render time and Chrome renders at 2× DPR so the screenshot lands at 4K. + ```bash + npx hyperframes render --resolution 4k --output 4k.mp4 + ``` + + + +## Quickstart + + + + ```bash Terminal + npx hyperframes render --resolution 4k --output my-video-4k.mp4 + ``` + + The composition's `data-width` / `data-height` are unchanged. Chrome's `deviceScaleFactor` is set to `2`, so the captured screenshot for each frame is 3840×2160. ffmpeg auto-detects the dimensions from the screenshot stream and encodes at 4K. + + + ```bash Terminal + npx hyperframes init my-video --resolution 4k + ``` + + Every scaffolded HTML file is patched in place: `data-width="3840"`, `data-height="2160"`, `data-resolution="landscape-4k"`, `#stage` CSS dimensions, and the `` tag. + + + ```bash Terminal + ffprobe -v error -select_streams v:0 -show_entries stream=width,height my-video-4k.mp4 + ``` + + Expected: + ``` + width=3840 + height=2160 + ``` + + + +## Resolution presets + +`--resolution` accepts these values on both `init` and `render`: + +| Preset | Dimensions | Aliases | +|--------|-----------|---------| +| `landscape` | 1920×1080 | `1080p`, `hd` | +| `portrait` | 1080×1920 | `1080p-portrait` | +| `landscape-4k` | 3840×2160 | `4k`, `uhd` | +| `portrait-4k` | 2160×3840 | `4k-portrait` | + +Examples: + +```bash Terminal +npx hyperframes render --resolution 4k # landscape 4K +npx hyperframes render --resolution portrait-4k # vertical 4K (TikTok / Reels at max quality) +npx hyperframes render --resolution 1080p # explicit 1080p (no-op on 1080p compositions) +``` + +## How `--resolution` works (supersampling) + +The composition stays at its authored dimensions. Hyperframes computes a `deviceScaleFactor` from the ratio of output to composition dimensions and passes it to Chrome: + +| Composition | `--resolution` | `deviceScaleFactor` | Output | +|-------------|---------------|--------------------|--------| +| 1920×1080 | `4k` | 2 | 3840×2160 | +| 1080×1920 | `portrait-4k` | 2 | 2160×3840 | +| 3840×2160 | `4k` | 1 (no-op) | 3840×2160 | + +Chrome then renders the page at the higher DPR — effectively rendering each CSS pixel as 2×2 device pixels — so the captured screenshot is at the requested resolution. + + + This approach is intentionally simple — no composition edits, no second authoring pass. The tradeoff: 4K renders take roughly 4× as long per frame because there are 4× the pixels to capture and encode. + + +## What scales, what doesn't + +Supersampling re-renders the page at higher DPR. That genuinely helps anything the browser rasterizes from a vector or high-resolution source, and does nothing for content already locked to a fixed pixel grid. Knowing which is which sets correct expectations before a 4K render: + +| Asset type | Behavior at `--resolution 4k` | +|------------|------------------------------| +| Text (HTML, SVG ``, web fonts) | ✅ **Re-rasterized at 4K.** Glyphs are vector and the browser shapes/rasterizes them at the new DPR. Crisp at any scale. | +| SVG / vector graphics | ✅ **Re-rasterized at 4K.** Same story as text — paths are vector. | +| CSS shapes, gradients, borders, shadows | ✅ **Re-rasterized at 4K.** Browser-generated raster. | +| Images with intrinsic dimensions ≥ 4K | ✅ **Full benefit.** A 3840×2160 source serves all the detail. | +| Images smaller than 4K (e.g. a 1920×1080 PNG) | ⚠️ **No new detail.** Browser upscales the source bitmap; output is no sharper than rendering at 1080p and upscaling externally — but no worse either. | +| `