HyperFrames CLI 渲染排障完全指南composition 识别、FFmpeg 依赖、lint 校验与确定性渲染【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes本篇排障指南围绕 HyperFrames 官方 troubleshooting.md 展开覆盖开发者使用hyperframesCLI 渲染 HTML 视频时最常遇到的五类问题——目录无法被识别为 composition、FFmpeg 缺失、lint 报错、预览不刷新以及渲染结果与预览不一致。读完你将能独立定位问题根因掌握npx hyperframes init / lint / render / preview的正确姿势并理解 CLI 内部的项目解析、依赖探测与 lint 规则实现从而在交付到本地渲染、Docker 确定性渲染或云端前把问题拦截在源头。一、故障速查表先对号入座下表汇总了官方文档列出的核心报错场景与处置方向后文逐条展开源码级细节。报错 / 现象根因一句话解决方案No composition found项目目录缺少入口index.html在项目根目录运行npx hyperframes init脚手架FFmpeg not found本机未安装 FFmpeg本地渲染缺编码器按操作系统安装 FFmpegmacOS/Linux/Windowslint errors缺少data-composition-id、classclip时间轴重叠或数据属性非法运行npx hyperframes lint并按错误码修复Preview not updating编辑的文件不是项目目录内被监听的index.html确认修改的是项目目录下的index.html预览服务会自动重载Render looks different from preview字体可用性与 Chrome 版本差异导致使用--docker模式获得确定性输出二、No composition found为什么我的目录不被识别根因缺少入口文件HyperFrames 遵循一个目录即一个 composition 项目的约定项目的入口必须是目录根部的index.html。CLI 在解析项目时会对该文件做存在性校验。真正抛出该错误的逻辑在 utils/project.tsif (options.requireIndex ! false !existsSync(indexPath)) { throw new InvalidProjectError( No composition found in dir, No index.html file found., Run npx hyperframes init to create a new composition., ); }对应测试 utils/project.test.ts 也验证了这一行为对一个不含index.html的空目录调用resolveProjectOrThrow会抛出No composition found。注意错误文案包含目录路径若你看到No composition found in xxx含义不是找不到 xxx而是在 xxx 中没有找到 composition 入口文件。解决方案用 init 脚手架生成 index.html文档给出的修复命令是npx hyperframes init。脚手架实现位于 commands/init.ts它会把内置模板如blank复制进目标目录生成完整的可运行项目结构除index.html外还包括meta.json、hyperframes.json记录 registry 与技能归属、package.json注入dev/check/render/publish四个 npm scripts以及给 AI Agent 参考的CLAUDE.md、AGENTS.md。常用脚手架示例# 交互式向导最常用直接补全 index.html npx hyperframes init my-video # 指定起始示例 npx hyperframes init my-video --example warm-grain # 非交互模式适合 CI 或 AI Agent必须显式提供 --example / --video / --audio npx hyperframes init my-video --example blank --non-interactive # 指定画布分辨率landscape 1920x1080 / portrait / 4k / square 等预设 npx hyperframes init my-video --resolution portrait几个来自源码的细节值得注意非交互模式下如果同时不提供--example、--video、--audioCLI 会直接报错并要求显式传--example blank目标目录已存在且非空时会拒绝覆盖Directory already exists and is not empty--template参数已重命名为--example传旧参数会收到清晰的改名提示并中止执行。三、FFmpeg not found本地渲染的编码依赖为什么本地渲染需要 FFmpegHyperFrames 渲染管线由浏览器捕获帧Puppeteer 内置 Chromium 负责把index.html时间轴渲染成帧与媒体合成两部分组成FFmpeg 负责把帧序列合成为 MP4 并处理音频混流。因此本地渲染默认模式强依赖系统级 FFmpeg只有在 Docker 模式下 FFmpeg 才随镜像一起被固定下来无需手工安装。按操作系统安装官方排障文档给出的三平台方案# macOSHomebrew brew install ffmpeg # Ubuntu / Debian 系 sudo apt install ffmpeg # Windows前往 https://ffmpeg.org/download.html 下载构建包 # 并将 bin/ 目录加入 PATH从源码看CLI 为各平台提供了一致的安装命令推导逻辑 browser/ffmpeg.ts 与 Linux 发行版探测 browser/linuxDeps.ts实际支持的安装命令比文档列举的更广平台 / 发行版安装命令macOSbrew install ffmpegDebian / Ubuntusudo apt-get update sudo apt-get install -y ffmpegFedorasudo dnf install -y ffmpegArchsudo pacman -S --needed ffmpegAlpinesudo apk add ffmpegWindows 10 1809 / 11winget install --id Gyan.FFmpeg -e或官网手动下载CLI 通过findFFmpeg()/findFFprobe()在标准 PATH 中查找二进制browser/ffmpeg.ts同时支持通过环境变量覆盖二进制路径导出自FFMPEG_PATH/FFPROBE_PATH适合把 FFmpeg 安装在非标准目录的开发者。容易被忽略的编码器兼容问题并非装了 FFmpeg 就万事大吉。源码 browser/ffmpeg.ts 中的resolveH264EncoderMode揭示了另一类坑某些 macOS FFmpeg 发行版只带 VideoToolbox 而没有 libx264。CLI 会先枚举ffmpeg -encoders存在libx264→ 走软件编码路径没有libx264但有h264_videotoolbox→ 回退到 GPU 编码路径两者皆无 → 直接报错 This FFmpeg build has neither libx264 nor VideoToolbox H.264 encoding.同理npx hyperframes init --video clip.mp4导入素材时也会用ffprobe探测编码遇到浏览器不支持的编码非 H.264/VP8/VP9/AV1/Theora会提示转码为 H.264 MP4见 init.ts 中handleVideoFile的逻辑。若此时本机没有 FFmpeg则只能降级为原样复制并在界面上提示安装命令。四、lint errors渲染前把结构性错误拦下来认识hyperframes lintnpx hyperframes lint是排查写了 HTML 但渲染不出预期效果的第一道工具。它扫描当前项目或通过位置参数指定的目录对 HTML 结构、时间轴、CSS 与脚本做静态校验。命令入口见 commands/lint.ts支持两个实用参数# 校验当前目录 npx hyperframes lint # 校验指定目录 npx hyperframes lint ./my-video # 输出 JSON便于脚本/AI 解析--json 模式下退出码 0 表示通过 npx hyperframes lint --json # 连 info 级发现一起展示默认只显示 error warning npx hyperframes lint --verboselint 的结果按error / warning / info分级存在 error 时退出码为 1会阻断后续发布等依赖 lint 的操作仅有 warning 时退出码为 0。--json输出包含ok、errorCount、warningCount、findings、filesScanned等结构化字段非常便于接入 CI 与 Agent 工作流。错误一根元素缺少data-composition-id文档强调的Missingdata-composition-idon root element在 lint 规则中对应root_missing_composition_iderror 级规则实现见 packages/lint/src/rules/core.ts。同样被强制的还有root_missing_dimensions缺少数值型data-width/data-height。为什么必须是根元素因为 HyperFrames 通过data-composition-id把某个 HTML 子树识别为可独立寻址、可嵌套、可挂载时间轴window.__timelines的composition 单元。根元素没有它运行时不知道把哪一层当作 composition 的起点。正确的入口结构骨架div idroot classclip >!-- 错误带时间属性但缺 clip -- div idbox># 本地快速迭代默认需 FFmpeg npx hyperframes render # 生产 / 交付 / CI确定性输出需 Docker 运行中 npx hyperframes render --docker本地渲染与 Docker 模式在浏览器帧捕获层面的更多参数GPU/软件渲染策略、帧提取格式等可参考同目录下的 rendering.md。把不一致消灭在源头的其他手段除了切 Docker还可以在渲染前做两件事一是用 lint 消除非确定性代码。上一节提到的non_deterministic_code规则会拦截Math.random()、Date.now()、gsap.utils.random()等模式。源码给出的替换建议是使用种子化伪随机数生成器如 mulberry32替代Math.random()用 GSAP 时间轴位置替代墙钟时间。这样每个渲染 worker 初始化出的画面保持一致从根上避免每台机器渲染结果不同。二是保证本机渲染环境可预期。本地渲染会按平台自动探测 GPU 与编码器可用性浏览器捕获侧首次启动探测 WebGL探测不到 GPU 时自动回退 SwiftShader 软件渲染可用--browser-gpu强制硬件、--no-browser-gpu强制软件Docker 模式固定走软件渲染FFmpeg 编码侧--gpu可启用 NVENC / VideoToolbox / AMF / VAAPI / QSV 等硬件编码软件路径则依赖libx264存在性判定见第三节。若你希望本地输出尽量贴近生产可在render前先用npx hyperframes lint清零 error再用--docker出正式文件。七、预防胜于排障把检查嵌入日常流程npx hyperframes init生成的项目package.json自带四个脚本dev/check/render/publish见 init.ts 中buildPackageScripts推荐工作流cd my-video npm run dev # 预览 自动重载 npm run check # 结构校验基于 lint 项目级检查见 utils/lintProject.ts 的实现 npm run render # 渲染 MP4需要 FFmpeg追求确定性加 --docker把校验前置到render之前能让上述五类问题中的绝大多数缺 composition id、缺 clip、时间轴重叠、非确定性代码在数秒内暴露而不是在漫长的渲染结束后才发现画面异常。八、进一步阅读packages/cli/src/docs/rendering.mdrender 命令的 fps / quality / workers / CRF / GPU 等全部参数说明与调优建议packages/cli/src/docs/compositions.mdcomposition 的目录结构与嵌套子 composition 概念packages/cli/src/docs/data-attributes.md时间轴相关data-*属性的完整语义packages/lint/src/rules/core.ts 与 packages/lint/src/rules/composition.ts本文所述 lint 错误码的完整规则与修复提示源码packages/cli/src/browser/ffmpeg.tsFFmpeg 探测与安装命令的平台映射实现packages/cli/src/utils/project.tsNo composition found的项目解析与错误抛出实现。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HyperFrames CLI 渲染排障完全指南composition 识别、FFmpeg 依赖、lint 校验与确定性渲染【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes本篇排障指南围绕 HyperFrames 官方 troubleshooting.md 展开覆盖开发者使用hyperframesCLI 渲染 HTML 视频时最常遇到的五类问题——目录无法被识别为 composition、FFmpeg 缺失、lint 报错、预览不刷新以及渲染结果与预览不一致。读完你将能独立定位问题根因掌握npx hyperframes init / lint / render / preview的正确姿势并理解 CLI 内部的项目解析、依赖探测与 lint 规则实现从而在交付到本地渲染、Docker 确定性渲染或云端前把问题拦截在源头。一、故障速查表先对号入座下表汇总了官方文档列出的核心报错场景与处置方向后文逐条展开源码级细节。报错 / 现象根因一句话解决方案No composition found项目目录缺少入口index.html在项目根目录运行npx hyperframes init脚手架FFmpeg not found本机未安装 FFmpeg本地渲染缺编码器按操作系统安装 FFmpegmacOS/Linux/Windowslint errors缺少data-composition-id、classclip时间轴重叠或数据属性非法运行npx hyperframes lint并按错误码修复Preview not updating编辑的文件不是项目目录内被监听的index.html确认修改的是项目目录下的index.html预览服务会自动重载Render looks different from preview字体可用性与 Chrome 版本差异导致使用--docker模式获得确定性输出二、No composition found为什么我的目录不被识别根因缺少入口文件HyperFrames 遵循一个目录即一个 composition 项目的约定项目的入口必须是目录根部的index.html。CLI 在解析项目时会对该文件做存在性校验。真正抛出该错误的逻辑在 utils/project.tsif (options.requireIndex ! false !existsSync(indexPath)) { throw new InvalidProjectError( No composition found in dir, No index.html file found., Run npx hyperframes init to create a new composition., ); }对应测试 utils/project.test.ts 也验证了这一行为对一个不含index.html的空目录调用resolveProjectOrThrow会抛出No composition found。注意错误文案包含目录路径若你看到No composition found in xxx含义不是找不到 xxx而是在 xxx 中没有找到 composition 入口文件。解决方案用 init 脚手架生成 index.html文档给出的修复命令是npx hyperframes init。脚手架实现位于 commands/init.ts它会把内置模板如blank复制进目标目录生成完整的可运行项目结构除index.html外还包括meta.json、hyperframes.json记录 registry 与技能归属、package.json注入dev/check/render/publish四个 npm scripts以及给 AI Agent 参考的CLAUDE.md、AGENTS.md。常用脚手架示例# 交互式向导最常用直接补全 index.html npx hyperframes init my-video # 指定起始示例 npx hyperframes init my-video --example warm-grain # 非交互模式适合 CI 或 AI Agent必须显式提供 --example / --video / --audio npx hyperframes init my-video --example blank --non-interactive # 指定画布分辨率landscape 1920x1080 / portrait / 4k / square 等预设 npx hyperframes init my-video --resolution portrait几个来自源码的细节值得注意非交互模式下如果同时不提供--example、--video、--audioCLI 会直接报错并要求显式传--example blank目标目录已存在且非空时会拒绝覆盖Directory already exists and is not empty--template参数已重命名为--example传旧参数会收到清晰的改名提示并中止执行。三、FFmpeg not found本地渲染的编码依赖为什么本地渲染需要 FFmpegHyperFrames 渲染管线由浏览器捕获帧Puppeteer 内置 Chromium 负责把index.html时间轴渲染成帧与媒体合成两部分组成FFmpeg 负责把帧序列合成为 MP4 并处理音频混流。因此本地渲染默认模式强依赖系统级 FFmpeg只有在 Docker 模式下 FFmpeg 才随镜像一起被固定下来无需手工安装。按操作系统安装官方排障文档给出的三平台方案# macOSHomebrew brew install ffmpeg # Ubuntu / Debian 系 sudo apt install ffmpeg # Windows前往 https://ffmpeg.org/download.html 下载构建包 # 并将 bin/ 目录加入 PATH从源码看CLI 为各平台提供了一致的安装命令推导逻辑 browser/ffmpeg.ts 与 Linux 发行版探测 browser/linuxDeps.ts实际支持的安装命令比文档列举的更广平台 / 发行版安装命令macOSbrew install ffmpegDebian / Ubuntusudo apt-get update sudo apt-get install -y ffmpegFedorasudo dnf install -y ffmpegArchsudo pacman -S --needed ffmpegAlpinesudo apk add ffmpegWindows 10 1809 / 11winget install --id Gyan.FFmpeg -e或官网手动下载CLI 通过findFFmpeg()/findFFprobe()在标准 PATH 中查找二进制browser/ffmpeg.ts同时支持通过环境变量覆盖二进制路径导出自FFMPEG_PATH/FFPROBE_PATH适合把 FFmpeg 安装在非标准目录的开发者。容易被忽略的编码器兼容问题并非装了 FFmpeg 就万事大吉。源码 browser/ffmpeg.ts 中的resolveH264EncoderMode揭示了另一类坑某些 macOS FFmpeg 发行版只带 VideoToolbox 而没有 libx264。CLI 会先枚举ffmpeg -encoders存在libx264→ 走软件编码路径没有libx264但有h264_videotoolbox→ 回退到 GPU 编码路径两者皆无 → 直接报错 This FFmpeg build has neither libx264 nor VideoToolbox H.264 encoding.同理npx hyperframes init --video clip.mp4导入素材时也会用ffprobe探测编码遇到浏览器不支持的编码非 H.264/VP8/VP9/AV1/Theora会提示转码为 H.264 MP4见 init.ts 中handleVideoFile的逻辑。若此时本机没有 FFmpeg则只能降级为原样复制并在界面上提示安装命令。四、lint errors渲染前把结构性错误拦下来认识hyperframes lintnpx hyperframes lint是排查写了 HTML 但渲染不出预期效果的第一道工具。它扫描当前项目或通过位置参数指定的目录对 HTML 结构、时间轴、CSS 与脚本做静态校验。命令入口见 commands/lint.ts支持两个实用参数# 校验当前目录 npx hyperframes lint # 校验指定目录 npx hyperframes lint ./my-video # 输出 JSON便于脚本/AI 解析--json 模式下退出码 0 表示通过 npx hyperframes lint --json # 连 info 级发现一起展示默认只显示 error warning npx hyperframes lint --verboselint 的结果按error / warning / info分级存在 error 时退出码为 1会阻断后续发布等依赖 lint 的操作仅有 warning 时退出码为 0。--json输出包含ok、errorCount、warningCount、findings、filesScanned等结构化字段非常便于接入 CI 与 Agent 工作流。错误一根元素缺少data-composition-id文档强调的Missingdata-composition-idon root element在 lint 规则中对应root_missing_composition_iderror 级规则实现见 packages/lint/src/rules/core.ts。同样被强制的还有root_missing_dimensions缺少数值型data-width/data-height。为什么必须是根元素因为 HyperFrames 通过data-composition-id把某个 HTML 子树识别为可独立寻址、可嵌套、可挂载时间轴window.__timelines的composition 单元。根元素没有它运行时不知道把哪一层当作 composition 的起点。正确的入口结构骨架div idroot classclip >!-- 错误带时间属性但缺 clip -- div idbox># 本地快速迭代默认需 FFmpeg npx hyperframes render # 生产 / 交付 / CI确定性输出需 Docker 运行中 npx hyperframes render --docker本地渲染与 Docker 模式在浏览器帧捕获层面的更多参数GPU/软件渲染策略、帧提取格式等可参考同目录下的 rendering.md。把不一致消灭在源头的其他手段除了切 Docker还可以在渲染前做两件事一是用 lint 消除非确定性代码。上一节提到的non_deterministic_code规则会拦截Math.random()、Date.now()、gsap.utils.random()等模式。源码给出的替换建议是使用种子化伪随机数生成器如 mulberry32替代Math.random()用 GSAP 时间轴位置替代墙钟时间。这样每个渲染 worker 初始化出的画面保持一致从根上避免每台机器渲染结果不同。二是保证本机渲染环境可预期。本地渲染会按平台自动探测 GPU 与编码器可用性浏览器捕获侧首次启动探测 WebGL探测不到 GPU 时自动回退 SwiftShader 软件渲染可用--browser-gpu强制硬件、--no-browser-gpu强制软件Docker 模式固定走软件渲染FFmpeg 编码侧--gpu可启用 NVENC / VideoToolbox / AMF / VAAPI / QSV 等硬件编码软件路径则依赖libx264存在性判定见第三节。若你希望本地输出尽量贴近生产可在render前先用npx hyperframes lint清零 error再用--docker出正式文件。七、预防胜于排障把检查嵌入日常流程npx hyperframes init生成的项目package.json自带四个脚本dev/check/render/publish见 init.ts 中buildPackageScripts推荐工作流cd my-video npm run dev # 预览 自动重载 npm run check # 结构校验基于 lint 项目级检查见 utils/lintProject.ts 的实现 npm run render # 渲染 MP4需要 FFmpeg追求确定性加 --docker把校验前置到render之前能让上述五类问题中的绝大多数缺 composition id、缺 clip、时间轴重叠、非确定性代码在数秒内暴露而不是在漫长的渲染结束后才发现画面异常。八、进一步阅读packages/cli/src/docs/rendering.mdrender 命令的 fps / quality / workers / CRF / GPU 等全部参数说明与调优建议packages/cli/src/docs/compositions.mdcomposition 的目录结构与嵌套子 composition 概念packages/cli/src/docs/data-attributes.md时间轴相关data-*属性的完整语义packages/lint/src/rules/core.ts 与 packages/lint/src/rules/composition.ts本文所述 lint 错误码的完整规则与修复提示源码packages/cli/src/browser/ffmpeg.tsFFmpeg 探测与安装命令的平台映射实现packages/cli/src/utils/project.tsNo composition found的项目解析与错误抛出实现。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
