使用指南

4K 渲染

无需重写即可将任何合成渲染为 4K（3840×2160）—— CLI 通过 Chrome 的 device scale factor 对 1080p 合成进行超采样。

Hyperframes 通过两种方式渲染到 4K（3840×2160）。两种方式都能生成真正的 4K MP4；选择适合你项目的方式。

以 4K 创作 以 4K 分辨率创建项目，使合成原生以 4K 布局。适合需要清晰的 4K 原生排版和素材时使用。 bash npx hyperframes init my-video --resolution 4k
渲染时超采样 保留现有的 1080p 合成。在渲染时传入 --resolution 4k，Chrome 会以 2× DPR 渲染，使截图达到 4K 分辨率。 bash npx hyperframes render --resolution 4k --output 4k.mp4

快速开始

以 4K 渲染现有项目

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

合成的 data-width / data-height 保持不变。Chrome 的 deviceScaleFactor 设为 2，因此每帧的截图为 3840×2160。ffmpeg 自动从截图流中检测尺寸并以 4K 编码。

或以 4K 创建新项目

npx hyperframes init my-video --resolution 4k

每个脚手架 HTML 文件会被就地修改：data-width="3840"、data-height="2160"、data-resolution="landscape-4k"、#stage CSS 尺寸以及 <meta viewport> 标签。

验证输出为 4K

ffprobe -v error -select_streams v:0 -show_entries stream=width,height my-video-4k.mp4

预期输出：

width=3840
height=2160

分辨率预设

--resolution 在 init 和 render 命令中接受以下值：

预设	尺寸	别名
`landscape`	1920×1080	`1080p`、`hd`
`portrait`	1080×1920	`1080p-portrait`
`landscape-4k`	3840×2160	`4k`、`uhd`
`portrait-4k`	2160×3840	`4k-portrait`

示例：

npx hyperframes render --resolution 4k         # 横屏 4K
npx hyperframes render --resolution portrait-4k # 竖屏 4K（TikTok / Reels 最高质量）
npx hyperframes render --resolution 1080p       # 显式 1080p（对 1080p 合成无效果）

`--resolution` 的工作原理（超采样）

合成保持其创作时的尺寸。Hyperframes 根据输出与合成尺寸的比率计算 deviceScaleFactor，并将其传递给 Chrome：

合成	`--resolution`	`deviceScaleFactor`	输出
1920×1080	`4k`	2	3840×2160
1080×1920	`portrait-4k`	2	2160×3840
3840×2160	`4k`	1（无操作）	3840×2160

Chrome 然后以更高的 DPR 渲染页面——实质上将每个 CSS 像素渲染为 2×2 设备像素——因此截图具有所请求的分辨率。

💡 Tip
这种方法刻意保持简单——无需编辑合成，无需二次创作。权衡是：4K 渲染每帧大约需要 4 倍的时间，因为需要捕获和编码 4 倍的像素。

什么会缩放，什么不会

超采样以更高的 DPR 重新渲染页面。这对浏览器从矢量或高分辨率源光栅化的任何内容都有真正帮助，但对已锁定到固定像素网格的内容则无效果。了解哪些会缩放、哪些不会，有助于在 4K 渲染前设定正确的预期：

素材类型	`--resolution 4k` 下的行为
文本（HTML、SVG `<text>`、Web 字体）	✅ 以 4K 重新光栅化。字形是矢量的，浏览器在新的 DPR 下对其进行塑形/光栅化。任何缩放级别都清晰。
SVG / 矢量图形	✅ 以 4K 重新光栅化。与文本相同——路径是矢量的。
CSS 形状、渐变、边框、阴影	✅ 以 4K 重新光栅化。浏览器生成的光栅。
固有尺寸 ≥ 4K 的图像	✅ 完全受益。 3840×2160 的源素材提供所有细节。
小于 4K 的图像（如 1920×1080 的 PNG）	⚠️ 无新增细节。浏览器放大源位图；输出不会比在 1080p 渲染后外部放大更清晰——但也不会更差。
`<video>` 元素	❌ 锁定到源分辨率。 1080p 的 MP4 仍然是 1080p；超采样仅帮助周围的 DOM。如果需要全程 4K，请以目标分辨率编码源视频。
`<canvas>`（2D 和 WebGL）	❌ 锁定到 canvas 固有尺寸。 `<canvas width="1920" height="1080">` 无论 DPR 如何都是 1080p 位图。要以 4K 渲染 canvas 内容，请将 `canvas.width` / `canvas.height` 乘以目标 DPR，并缩放绘图上下文（`ctx.scale(2, 2)` 用于相同逻辑布局的 2× canvas）。
引擎注入的预渲染视频帧	❌ 锁定到提取分辨率。当 producer 通过 ffmpeg 预提取 `<video>` 帧时，它们以源视频的尺寸解码。

经验法则：如果素材是矢量的或由浏览器生成的，超采样有帮助。如果它是具有固定像素尺寸的位图（视频、canvas、低分辨率 PNG），则没有帮助——请以目标分辨率创作。

约束条件

--resolution 在捕获帧之前执行三项检查。如果任何一项失败，渲染会在执行前退出。

宽高比必须匹配

# 正确——都是横屏
hyperframes render --resolution 4k         # 合成是 1920×1080

# 错误——合成是横屏，目标是竖屏
hyperframes render --resolution portrait-4k  # 合成是 1920×1080
# → outputResolution portrait-4k (2160×3840) 与合成的宽高比 (1920×1080) 不匹配。
#   请选择方向匹配的预设。

每帧捕获：慢 3–4 倍（Chrome 绘制 4 倍的像素，截图传输量增大 4 倍）
编码：慢 2–3 倍（取决于编码器；H.264 随分辨率亚线性扩展）
内存：有上限——引擎的帧 data-URI 缓存有字节预算（默认每个 worker 1500 MB，可通过 PRODUCER_FRAME_DATA_URI_CACHE_BYTES_MB 配置）
输出文件大小：在默认 CRF 下，预期为 1080p 渲染文件大小的 3–5 倍。传入 --video-bitrate 25M（或更高）可获得可预测的文件大小。

对于 30 秒合成的 4K 渲染，在现代笔记本电脑上预计需要几分钟的挂钟时间。在渲染机器上添加 --workers 4（或更多）以实现并行捕获。

Studio 支持

Studio 的渲染面板在格式和质量选择器旁边包含一个分辨率下拉菜单。选择 4K（或竖屏 4K ↕）并点击导出——运行与 CLI 标志相同的超采样路径，无需编辑合成。

下拉菜单默认为 Auto（以合成的创作尺寸渲染）。可用预设：

Auto — 合成的原生尺寸
1080p ↔ / 1080p ↕ — 1920×1080 / 1080×1920
4K ↔ / 4K ↕ — 3840×2160 / 2160×3840

分辨率按每次渲染应用，而非按项目——你的合成文件不会改变。相同的约束条件适用；当 producer 拒绝某个组合时，失败信息会显示在 Studio 渲染队列中。

你也可以通过 CLI 控制分辨率：

新项目：hyperframes init my-video --resolution 4k
现有项目：hyperframes render --resolution 4k --output 4k.mp4

另请参阅

render CLI 参考 — 每个渲染标志，包括 --video-bitrate 和 --crf
init CLI 参考 — 创建时的 --resolution 标志
HDR 渲染 — 颜色管线指南；HDR + 4K 尚不支持组合使用

HDR 渲染

当源包含 HDR 视频或图片时，将合成渲染为 HDR10 MP4（BT.2020 PQ 或 HLG，10-bit H.265）。

性能

如何保持预览播放流畅，以及如何诊断高开销的合成。