chore: import upstream snapshot with attribution

2026-07-13 12:58:35 +08:00
commit 85453da49f
4031 changed files with 710987 additions and 0 deletions
@@ -0,0 +1,167 @@
+---
+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.
+
+<CardGroup cols={2}>
+  <Card title="Author at 4K" icon="ruler">
+    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
+    ```
+  </Card>
+  <Card title="Supersample at render" icon="up-right-and-down-left-from-center">
+    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
+    ```
+  </Card>
+</CardGroup>
+
+## Quickstart
+
+<Steps>
+  <Step title="Render an existing project at 4K">
+    ```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.
+  </Step>
+  <Step title="Or scaffold a new project 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 `<meta viewport>` tag.
+  </Step>
+  <Step title="Verify the output is 4K">
+    ```bash Terminal
+    ffprobe -v error -select_streams v:0 -show_entries stream=width,height my-video-4k.mp4
+    ```
+
+    Expected:
+    ```
+    width=3840
+    height=2160
+    ```
+  </Step>
+</Steps>
+
+## Resolution presets
+
+`--resolution` accepts these values on both `init` and `render`:
+
+| Preset | Dimensions | Aliases |
+|--------|-----------|---------|
+| `landscape` | 1920×1080 | `1080p`, `hd` |
+| `portrait` | 1080×1920 | `1080p-portrait` |
+| `square` | 1080×1080 | `1080p-square`, `square-1080p` |
+| `landscape-4k` | 3840×2160 | `4k`, `uhd` |
+| `portrait-4k` | 2160×3840 | `4k-portrait` |
+| `square-4k` | 2160×2160 | `4k-square` |
+
+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.
+
+<Tip>
+  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.
+</Tip>
+
+## 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 `<text>`, 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. |
+| `<video>` elements | ❌ **Locked to source resolution.** A 1080p MP4 stays 1080p; the supersample only helps the surrounding DOM. Encode source video at the target resolution if you need 4K throughout. |
+| `<canvas>` (2D and WebGL) | ❌ **Locked to canvas's intrinsic dimensions.** `<canvas width="1920" height="1080">` is a 1080p bitmap regardless of DPR. To render canvas content at 4K, multiply `canvas.width` / `canvas.height` by your target DPR and scale the drawing context (`ctx.scale(2, 2)` for a 2× canvas with the same logical layout). |
+| Pre-rendered video frames injected by the engine | ❌ **Locked to extraction resolution.** When the producer pre-extracts `<video>` frames via ffmpeg, they're decoded at the source video's dimensions. |
+
+**Rule of thumb**: if the asset is *vector or generated by the browser*, supersampling helps. If it's a *bitmap with fixed pixel dimensions* (video, canvas, low-res PNG), it doesn't — author it at the target resolution instead.
+
+## Constraints
+
+`--resolution` enforces three guards before any frames are captured. If any fail, the render exits before doing work.
+
+### Aspect ratio must match
+
+```bash
+# OK — both landscape
+hyperframes render --resolution 4k         # composition is 1920×1080
+
+# Error — composition is landscape, target is portrait
+hyperframes render --resolution portrait-4k  # composition is 1920×1080
+# → outputResolution portrait-4k (2160×3840) does not match the aspect ratio
+#   of the composition (1920×1080). Pick a preset whose orientation matches.
+```
+
+### The scale must be an integer
+
+The width ratio (output ÷ composition) must be a positive integer. 1080p → 4K is exactly `2×`. 720p → 4K would be `3×` and works. Non-integer scales like 900p → 4K (`2.4×`) introduce aliasing on subpixel-positioned text — Hyperframes refuses rather than producing a blurry render.
+
+### Downsampling is not supported
+
+`--resolution` only supersamples. A 4K composition cannot be downsampled to 1080p with this flag — render at the composition's native resolution and downscale separately with ffmpeg if needed.
+
+### Not yet supported with `--hdr`
+
+The HDR layered compositor processes pixel buffers at composition dimensions; supersample + HDR would need parallel scaling for those buffers. The combination is rejected with a clear error message. Render in two passes if you need both: HDR at composition resolution, then upscale separately.
+
+## Performance
+
+A 1080p → 4K supersample is roughly 4× more pixels to capture, encode, and write. Expect:
+
+- **Per-frame capture**: 3–4× slower (Chrome paints 4× the pixels and the screenshot transfer is 4× larger)
+- **Encoding**: 2–3× slower (depends on codec; H.264 scales sublinearly with resolution)
+- **Memory**: bounded — the engine's frame data-URI cache is byte-budgeted (default 1500 MB per worker, configurable via `PRODUCER_FRAME_DATA_URI_CACHE_BYTES_MB`)
+- **Output file size**: at the default CRF, expect 3–5× the file size of the 1080p render. Pass `--video-bitrate 25M` (or higher) for predictable file sizes.
+
+For a 4K render of a 30-second composition, plan on a few minutes of wall time on a modern laptop. Add `--workers 4` (or more) on a render box for parallel capture.
+
+## Studio support
+
+The Renders panel in Studio includes a resolution dropdown next to the format and quality selectors. Pick `4K` (or `4K ↕` for portrait) and hit **Export** — the same supersampling path runs as the CLI flag, no composition edits required.
+
+The dropdown defaults to `Auto` (render at the composition's authored size). Available presets:
+
+- **Auto** — composition's native dimensions
+- **1080p ↔** / **1080p ↕** — 1920×1080 / 1080×1920
+- **4K ↔** / **4K ↕** — 3840×2160 / 2160×3840
+
+The resolution applies per render, not per project — your composition files are unchanged. The same [constraints](#constraints) apply; when the producer rejects a combination, the failure surfaces in the Studio render queue.
+
+You can also drive resolution from the CLI:
+
+- **New project**: `hyperframes init my-video --resolution 4k`
+- **Existing project**: `hyperframes render --resolution 4k --output 4k.mp4`
+
+## See also
+
+- [`render` CLI reference](/packages/cli#render) — every render flag including `--video-bitrate` and `--crf`
+- [`init` CLI reference](/packages/cli#init) — the `--resolution` flag at scaffold time
+- [HDR Rendering](/guides/hdr) — color pipeline guide; HDR + 4K is not yet a supported combination