企业官网建设流程全解析

@hyperframes/engine 渲染引擎深度解析：用 Puppeteer + FFmpeg 把可寻址 Web 页面渲染成视频

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

@hyperframes/engine是 HyperFrames 技术栈中位于底层的"可寻址（seekable）网页渲染引擎"：它打开你的 HTML 合成页面，逐帧seek到精确时刻截屏，再交给 FFmpeg 编码成视频。它不是录屏器，而是一套确定性的帧调度管线，并且与动画框架无关——只要页面实现了统一的window.__hfseek 协议，GSAP、Lottie、Three.js、CSS 动画都能被渲染。读完本文，你将掌握引擎的架构、九大核心服务、window.__hf页面协议、EngineConfig 配置体系、捕获与编码流程以及何时该直接用引擎而不是上层 Producer/CLI。

引擎是什么，以及它为什么不是录屏

@hyperframes/engine的定位在仓库中写得很直白：Seekable web-page-to-video rendering engine built on Puppeteer and FFmpeg（packages/engine/package.json）。

录屏器依赖墙上时钟，机器负载高时可能丢帧；引擎则要求页面暴露window.__hf，通过duration计算总帧数、在每帧截屏前调用seek(time)，因此帧调度是可复现的，慢机器也不会掉帧。但要注意：精确像素仍可能随 Chrome 版本、字体、编解码器、GPU 行为与宿主环境变化，当需要逐字节级别的视觉可复现性时，需要把依赖钉死——这一话题在仓库文档 确定性渲染 中有更完整的讨论。

从渲染路径看，引擎会启动 headless Chrome 实例，用 Chrome 的HeadlessExperimental.beginFrameCDP 接口逐帧推进画面，截取截图，再交给 FFmpeg 编码为视频。这条链路也解释了为什么引擎要求 Node.js ≥ 22、Chrome/Chromium（Puppeteer 自动下载）以及 FFmpeg 三样运行时依赖。

整体架构：九大核心服务

引擎的实现被拆分为一组职责单一的服务，各自拥有独立的源码文件与测试覆盖，入口统一从 packages/engine/src/index.ts 导出。下表来自 packages/engine/README.md，对应源码位置如下：

这套服务矩阵本身就是"网页渲染成视频"问题的领域建模：先有浏览器（browserManager），再逐个捕获帧（frameCapture + screenshotService），同时为视频/音频原生能力做补偿（videoFrameExtractor / audioMixer），编码（chunkEncoder / streamingEncoder），加速（parallelCoordinator），最后还有一个本地静态服务来喂页面（fileServer）。

页面协议：任何框架，只要实现window.__hf

引擎与页面之间唯一的契约是window.__hf（即HfProtocol接口，定义于 packages/engine/src/types.ts）。引擎不关心页面背后是什么动画框架——GSAP、Framer Motion、CSS 动画、Three.js 都行，只要seek()在给定时间点能产出确定的视觉效果：

export interface HfProtocol { /** 合成片段的时长（秒） */ duration: number; /** seek 到特定时间点，必须产出确定的视觉输出 */ seek(time: number): void; /** 可选：引擎应处理的媒体元素 */ media?: HfMediaElement[]; /** 可选：着色器转场元数据（由 @hyperframes/shader-transitions 填充） */ transitions?: HfTransitionMeta[]; }

types.ts中对全局Window做了声明增强（declare global），把__hf?: HfProtocol挂到window上。由此，引擎读duration计算总帧数、每次捕获前调用seek(time)、利用media处理视频帧注入与音频混音。

media中的每个元素由 HfMediaElement 描述。之所以需要显式声明，是因为BeginFrame 模式下的 headless Chrome 无法播放<video>、也无法产生音频，引擎必须先抽取这些媒体并把画面/声音在合成阶段自动注入与混合。字段包括：

transitions则供包含 shader 转场的合成使用：每个转场记录time、duration、shader、GSAPease、fromScene/toScene，让上层 Producer 能预计算场景区间、按场景捕获 buffer，再做 HDR 感知的合成。

安装与运行环境

npm install @hyperframes/engine

运行时要求：

• Node.js >= 22（见 packages/engine/package.json 的engines字段）；
• Chrome/Chromium，由 Puppeteer 自动下载；
• FFmpeg（含ffprobe）。

代码采用 ESM（"type": "module"），开发态直接以 TS 源文件作为导出入口（main/exports指向./src/index.ts），发布时再编译到dist。包内还按子路径导出./alpha-blit与./shader-transitions两个工具集。FFmpeg 与 ffprobe 的二进制路径可通过环境变量指定（见 ffmpegBinaries.ts 的FFMPEG_PATH_ENV/FFPROBE_PATH_ENV，并有assertConfiguredFfmpegBinariesExist做启动期校验）。

使用流程：从启动浏览器到逐帧捕获

README 给出的四步流程是最小可用骨架：启动浏览器 → 建立捕获会话 → 逐帧捕获 → 清理。不过要注意，当前仓库源码（frameCapture.ts）与更完整的包级文档 docs/packages/engine.mdx 中，createCaptureSession/captureFrame的实际签名已经演进为(serverUrl, outputDir, options)与(session, frameIndex, time)形态——README 中的对象式写法属于概念示意。基于源码的真实调用如下：

import { captureFrame, closeCaptureSession, createCaptureSession, getCompositionDuration, initializeSession, } from "@hyperframes/engine"; const fps = { num: 30, den: 1 }; // fps 是精确有理数：整数帧率 {num:30, den:1} const session = await createCaptureSession( "http://localhost:3000/my-composition.html", // 页面必须实现 window.__hf "./frames", // 输出帧目录（自动创建） { width: 1920, height: 1080, fps, format: "jpeg", }, ); try { await initializeSession(session); // 等页面就绪、预热 BeginFrame const duration = await getCompositionDuration(session); const totalFrames = Math.ceil(duration * 30); for (let frame = 0; frame < totalFrames; frame += 1) { const time = frame / 30; await captureFrame(session, frame, time); // seek + 截屏 + 落盘 } } finally { await closeCaptureSession(session); // teardown 永不抛错 }

几个实现细节值得展开：

• createCaptureSession（frameCapture.ts）内部会解析 headless shell 路径、决策捕获模式、解析 GPU 模式，调用方通常不需要自己acquireBrowser——浏览器生命周期已被会话接管。它还支持传入BeforeCaptureHook与部分EngineConfig。
• captureFrame(session, frameIndex, time)（frameCapture.ts）内部完成 seek + 截屏，并通过writeCapturedFrame按frame_000000.jpg|png的规范命名写入会话输出目录，最后返回CaptureResult（frameIndex、量化后的time、path、captureTimeMs）。
• 当下一阶段需要内存中的 Buffer 而非磁盘文件时，改用captureFrameToBuffer()——这正是 streaming encode 路径把帧直接送进 FFmpeg stdin 的支撑。

捕获模式：BeginFrame、截图与 drawElement

引擎在"把一帧 DOM 状态变成一张位图"这一步有多种路径，会话初始化时会基于平台与配置自动决策，最终模式记录在CapturePerfSummary.captureMode（"drawelement" | "screenshot" | "beginframe"）。核心事实包括：

• BeginFrame 模式依赖HeadlessExperimental.beginFrame这一 CDP 调用，一次调用完成一个 layout-paint-composite 周期并返回截图与hasDamage布尔（screenshotService.ts）。它要求chrome-headless-shell，并需要--enable-begin-frame-control与--deterministic-mode启动参数。源码注释明确：BeginFrame flags 只在 Linux 上生效；macOS 存在 Chromium 结构性限制（crbug.com/40656275），因此相关绕行方案（如 page-side compositing）是 Mac 用户的关键杠杆。
• BeginFrame 不吃 alpha：需要透明 PNG 输出时，应同时设置config.forceScreenshot = true；deviceScaleFactor > 1（超采样）也会回退到截图路径，因为 BeginFrame 的截屏不遵循视口的 DPR 缩放。
• drawElement 快速捕获：在 macOS / Windows + 硬件 GPU 浏览器上可启用（useDrawElement），直接从合成根读取 paint records 做捕获，并带有自校验网——初始化时抓取 ground-truth 样本、运行期对每帧做 PSNR 比对，任何不兼容或损坏的渲染都会自动回退到 screenshot 捕获（相关验证逻辑见 drawElementService.ts 与psnrDb）。
• 无变化帧复用：BeginFrame 上报hasDamage=false时复用上一帧缓存，避免在暂停的合成器上调用会超时的Page.captureScreenshot；截图路径则有静态帧去重（staticFrameDedup，可用HF_STATIC_DEDUP=false关闭）。

screenshotService 中还有一个值得注意的健壮性设计：sendBeginFrame对"Another frame is pending"做指数退避重试（最多 5 次），超限后给出"CPU 被并行渲染打满，请降低并发或使用 --docker 隔离"的明确报错——这说明帧捕获并非总是瞬时成功的，上层必须容忍瞬态错误。

引擎配置体系：EngineConfig 与默认值

引擎把过去散落的PRODUCER_*环境变量收敛为结构化的 EngineConfig 接口，同时保留环境变量作为向后兼容的回退，统一由resolveConfig()解析。核心默认值（config.ts）：

browserGpuMode的三种取值对渲染影响巨大：software（SwiftShader）纯 CPU、总是可用但约慢 5–50 倍；hardware走平台原生 ANGLE 后端（Metal/D3D11/EGL），无可用 GPU 时直接报错；auto会在进程内首次启动时做一次 WebGL 探测（额外成本约 1–2 秒、结果缓存），不可用则回退软件渲染。此外resolveConfig会把低内存检测（getSystemTotalMb/isLowMemorySystem）、Windows 软件 GPU 复合启发式等自动决策落到字段上，供可观测性层区分"自动关闭"与"用户显式关闭"。

错误处理约定：三类错误、三种策略

引擎面向编排方与库调用者，错误语义必须可预期。index.ts 的文档注释给出了全局约定：

1. 编排类服务失败即抛异常：浏览器启动、会话初始化、帧捕获、CDP 操作（frameCapture、browserManager、screenshotService、videoFrameExtractor.extractVideoFramesRange）——调用方应捕获处理；
2. FFmpeg 进程包装器返回结果对象而非 reject：编码、mux、混音、流式编码等返回{ success, error? }（chunkEncoder、audioMixer、streamingEncoder）；
3. 清理与 teardown 永不抛错：releaseBrowser、closeCaptureSession、临时目录清理等通过.catch(() => {})吞掉错误，避免掩盖最初的失败；
4. 可选查找返回T | undefined/null：resolveHeadlessShellPath、getFrameAtTime、detectGpuEncoder等可能合法地"找不到"的函数返回空值而不是抛错。

会话初始化还会产出结构化的CaptureWarning（code 类型如media_readiness_timeout、media_load_failed、audio_processing_failed、sub_timeline_readiness_timeout、live_map_detected），捕获性能摘要CapturePerfSummary则给出 p50 / p95 / p99 的单帧耗时——p50 对预热鲁棒，p95/p99 用于识别"长尾尖峰"，这些都是判断某台机器渲染快慢的关键信号。

媒体管线：BeginFrame 缺陷的补偿机制

由于 headless Chrome 在 BeginFrame 模式下不原生播放<video>、不产生音频，引擎发展出了一整套"外带处理"媒体管线：

• 视频帧抽取与注入：parseVideoElements/extractVideoFramesRange先从源<video>抽帧建立FrameLookupTable（getFrameAtTime按时间取帧），再由 videoFrameInjector.ts 的createVideoFrameInjector在截屏时把对应帧按元素包围盒注入 DOM。抽取结果带内容寻址缓存（默认<tmpdir>/hyperframes-extract-cache-<uid>，键为 path+mtime+size+媒体区间+fps+format，可用HYPERFRAMES_EXTRACT_CACHE_DIR覆盖或设off/none/false/0关闭）。
• 就绪等待的例外：页面默认要等video.readyState >= 1才开拍；对走外带帧注入的视频（含原生 HDR 抽取），通过skipReadinessVideoIds跳过检查，并用videoMetadataHints提前告知 FFmpeg 探测到的原始尺寸，避免height:auto这类依赖媒体固有比例的布局跑偏。
• 音频混音：parseAudioElements(html)在 HTML 中解析音频元素，processCompositionAudio把各轨道按时间轴、音量、淡入淡出曲线混成单一MIXED_AUDIO_FILENAME；audioVolumeEnvelope.ts 提供了包络 walker 与对 WAV 的音量包络应用，另有音频 FX 渲染（audioFxRender.ts 的readWav/writeWav/applyAudioFxChain）。
• HDR：需要 HDR 输出时，hdr配置选hlg或pq，通过 hdrCapture.ts 的专用浏览器参数与 readback（float16ToPqRgb等）拿到宽色域帧，编码时附带DEFAULT_HDR10_MASTERING主控元数据。

编码器：分块 concat、流式管道与 GPU 加速

编码层分成两种互补的路径：

• chunkEncoder（chunkEncoder.ts）：从帧目录按序编码（encodeFramesFromDir），或做分块编码后再 concat（encodeFramesChunkedConcat，chunkSizeFrames控制块大小），最后muxVideoWithAudio合成音视频、applyFaststart把 moov 挪到文件头以便流式播放。detectGpuEncoder探测宿主 GPU 编码器，ENCODER_PRESETS/getEncoderPreset提供预设；VP9 通过vp9CpuUsed（-8..8，默认值见 vp9Options.ts 的DEFAULT_VP9_CPU_USED）调节速度/质量权衡，FFmpeg 参数按精确有理数帧率原样输出。
• streamingEncoder（streamingEncoder.ts）：spawnStreamingEncoder启动 FFmpeg 并持续从writeFrame喂入帧，磁盘上不落中间 PNG，显著降低 IO 与临时空间占用；createFrameReorderBuffer用于需要重排序（如 B 帧）的场景。其流式超时是"帧间静默时长"，不是总渲染时长。

并行渲染与本地文件服务

• parallelCoordinator（parallelCoordinator.ts）负责把帧区间分发给多个 worker 进程：calculateOptimalWorkers/computeWorkerSizing按 CPU 与内存启发式定尺寸，distributeFramesInterleaved做交错分发以平衡负载，各 worker 结果由mergeWorkerFrames合并。多 worker 的 drawElement 捕获会抬高自校验采样数（deVerifySamples）——N 个并发硬件 GPU 浏览器会放大合成器瓦片逐出等损坏面，而每个 worker 只消化约 1/N 的共享采样网格，正好在风险峰值时把覆盖密度摊薄了，所以必须加密采样补偿。
• fileServer（fileServer.ts）用 Hono 起一个本地静态服务器：createFileServer({ projectDir, compiledDir?, port?, headScripts?, bodyScripts?, stripEmbeddedRuntime })返回{ url, port, close }。.html请求会走"注入脚本"逻辑——往<head>/</body>前注入 runtime 脚本并剥离内嵌运行时，默认index.html才做注入；其他扩展名按 MIME 表直出，找不到文件返回 404。它是"本地 HTML 合成 → 无头浏览器"之间那个不起眼但必要的桥梁。

何时直接使用引擎，何时用上层封装

引擎是低层原语集合，文档与 docs/packages/engine.mdx 都反复强调：大多数集成应该走@hyperframes/producer或hyperframesCLI，仅在需要自己掌控帧捕获、编码、媒体抽取或浏览器管理时才直接使用引擎。

仓库内的关系图如下：

• packages/core —— 类型、解析器、帧适配器（engine 的quantizeTimeToFrame等直接复导出自 core）；
• packages/producer —— 构建在本引擎之上的高层渲染管线（对应包文档 docs/packages/producer.mdx）；
• packages/cli —— 命令行入口；
• docs/packages/engine.mdx —— 引擎的完整包级文档（含可运行示例）。

一句话总结技术选型：要"画面正确、帧可复现、媒体可混、可并行加速"的视频化能力，就直接依赖@hyperframes/engine的九大服务与window.__hf协议；要"一句话把整条管线跑完"，则交给它上层的 Producer 与 CLI。对想深入源码的读者，建议从 types.ts（协议契约）→ config.ts（默认值与门控）→ frameCapture.ts（会话与捕获主流程）→ screenshotService.ts（BeginFrame 截屏与视频帧注入）这条主线读起，每一环都有同目录下大量.test.ts用例可以对照验证行为边界。

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes