4K Rendering

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.

Author at 4K

Scaffold the project at 4K so the composition is laid out at 4K natively. Best when you want crisp 4K-native typography and assets.

npx hyperframes init my-video --resolution 4k

Supersample at render

Keep your existing 1080p composition. Pass --resolution 4k at render time and Chrome renders at 2× DPR so the screenshot lands at 4K.

npx hyperframes render --resolution 4k --output 4k.mp4

Quickstart

1. Render an existing project at 4K

   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.

2. Or scaffold a new project at 4K

   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.

3. Verify the output is 4K

   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:

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 <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

# 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 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 — every render flag including --video-bitrate and --crf
• init CLI reference — the --resolution flag at scaffold time
• HDR Rendering — color pipeline guide; HDR + 4K is not yet a supported combination