HyperFrames v0.8.18 版本解读Studio 跨目录合成编辑、快照保真与 CLI 渲染修复【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames v0.8.18发布于 2026-08-29是一次聚焦编辑器体验与渲染正确性的维护版本。本次更新让 Studio 可以为项目任意位置不再局限于compositions/目录存储的合成切换画布与时间线并显著提升了项目快照对播放速率、嵌套媒体时序、静态合成与源文件的保真能力同时修复了嵌套视频的时间窗口可见性、修剪/加速视频关键帧采样错误、关键帧输出覆盖源文件风险以及data-no-timeline合成被误报冻结扫描frozen-sweep等问题。阅读本文后你可以准确理解每个修复背后的机制、涉及的源码位置以及如何在自己的项目中规避这些坑。一、Studio任意位置合成的画布与时间线切换在 v0.8.18 之前Studio 假定项目中的合成统一存放在compositions/目录下画布与时间线的切换逻辑对该路径有隐式依赖。本次更新解除了这一限制只要合成通过标准属性声明无论它存储在项目中的哪个目录Studio 都能正确为其切换画布canvas与时间线timeline。从源码结构看Studio 对合成宿主的识别并不依赖固定目录名而是依赖元素上的声明式属性。在 packages/studio/src/components/editor/LayersPanel.tsx 中判断逻辑是return el.hasAttribute(data-composition-src) || el.hasAttribute(data-composition-file);而 packages/studio/src/components/editor/domEditingDom.ts 则通过findClosestByAttribute向上查找携带data-composition-file/data-composition-src的宿主元素来解析合成来源。这意味着合成的真实存储位置只是一个路径值编辑器只要拿到该属性即可定位源文件并加载画布与时间线。这一点在仓库的测试夹具中得到印证例如 packages/producer/tests/nested-sequential-video-local-start/src/index.html 展示了宿主元素的标准写法div idroot>const playbackRate Number.parseFloat(element.dataAttributes[playback-rate] ?? 1) || 1;而在时间线编辑辅助逻辑 packages/studio/src/hooks/timelineEditingHelpers.ts 中修剪trim计算显式参与了播放速率value: Math.max(0, current trimDelta * Math.max(element.playbackRate ?? 1, 0.1)),可见播放速率并非仅仅影响播放预览它还直接参与剪辑边界计算因此快照若丢失该字段恢复后就会出现修剪位置错乱。本次修复正是补上了这类字段的快照持久化确保撤销/恢复后编辑状态完整。三、Core 修复长嵌套视频在宿主窗口前的可见性本次 Core 侧修复PR #3535针对的是嵌套媒体时序的一个边界问题当嵌套视频的本地起始时间local start早于宿主窗口host window的起点时长视频在时间线中可能被错误地隐藏。典型场景是一个长视频作为合成片段嵌入宿主时间线其本地data-start0但宿主中该片段被安排在 1s 处data-start1。此前引擎在计算可见区间时如果按本地起始时间与宿主窗口起点的简单比较判断会误以为视频已结束或尚未开始从而不渲染该片段。修复后引擎正确地将本地时间轴偏移与宿主窗口裁剪分开计算保证长视频在宿主窗口中持续可见。对应的测试夹具 packages/producer/tests/nested-sequential-video-local-start/src/index.html 正是为这类本地起始早于宿主窗口的嵌套顺序场景准备的回归用例。四、CLI 修复修剪/加速视频的关键帧采样正确性CLI 侧第一个修复PR #3536针对hyperframes render中的关键帧keyframe/poster 帧输出当源视频被修剪trim或加速speed up后关键帧采样必须落在正确的源帧上。问题本质是时间映射用户在时间线上看到的合成时间与媒体源文件内部的源帧时间之间存在偏移与缩放关系。修剪引入偏移合成时间 t 对应源文件时间t trimStart加速引入缩放合成时间 t 对应源时间t * rate。此前若直接以合成时间对源文件采样就会截取到错误的源帧导致关键帧画面与视频实际内容错位。引擎侧的帧捕获核心实现在 packages/engine/src/services/frameCapture.ts其中captureFrameCore强调以绝对合成帧索引Math.floor(time * fps)为准进行采样与静态帧去重而不是依赖调用方传入的分块相对索引——这正体现了合成时间 → 帧映射必须端到端一致的设计原则。修复后无论媒体被修剪还是加速关键帧输出都会映射回正确的源帧。五、CLI 修复拒绝关键帧输出覆盖活动合成源第二个 CLI 修复PR #3534是一道防覆盖安全网当关键帧keyframe-shot的输出目标路径恰好指向当前正在使用的合成源文件时CLI 会直接拒绝执行避免渲染过程把项目源文件覆盖成输出产物。这类事故在自动化流程中极易发生比如脚本把--frame output或关键帧导出路径解析为与data-composition-src相同的路径。v0.8.18 在 CLI 层增加了路径比对与拒绝逻辑从源头阻断对活动合成源的破坏性写入。实操建议升级后如果发现关键帧导出报拒绝覆盖类错误请检查输出路径是否与项目中的data-composition-src/data-composition-file指向相同将关键帧输出重定向到独立目录如exports/、shots/即可正常执行。六、CLI 修复data-no-timeline合成不再触发误报的冻结扫描第三个 CLI 修复PR #3533针对hyperframes check审计的冻结扫描frozen-sweep守卫明确声明了data-no-timeline的静态合成不再被误报为sweep_static错误。要理解这个修复需要先理解冻结扫描守卫的设计。在 packages/cli/src/utils/checkPipeline.ts 中审计器为每个布局采样点生成几何透明度指纹geometry signature如果所有采样点的指纹完全相同说明 seek 根本没有推进时间线——此时审计器给出的所有绿色通过结论都不可信因此会报告sweep_static错误message: Timeline did not advance under seek; every green verdict on this run is unreliable., fixHint: Confirm the composition seeks a paused GSAP/CSS timeline under data-* timing attributes rather than only autoplaying.,但存在一类合法静态内容标题卡片、静态封面等本就不需要时间线。它们通过data-no-timeline属性显式声明我是静态的。此前守卫没有识别该声明会把这类合成误判为时间线没有推进产生假阳性错误。v0.8.18 修复后守卫首先检查该声明function detectSweepStatic(duration, geometrySignatures, motionIssues, hasNoTimelineDeclaration) { if (hasNoTimelineDeclaration) return []; if (duration SWEEP_STATIC_MIN_DURATION_SEC) return []; if (geometrySignatures.length 2) return []; if (motionIssues.some((issue) issue.code motion_frozen)) return []; ... }对应的浏览器端读取逻辑在 packages/cli/src/utils/checkBrowser.tsasync function hasNoTimelineDeclaration(page: Page): Promiseboolean { return page.evaluate( () document.querySelector([data-composition-id])?.hasAttribute(data-no-timeline) ?? false, ); }测试用例也同步覆盖了三种边界场景见 packages/cli/src/commands/check.test.ts6 秒合成几何在各采样点完全不变 → 报告sweep_static声明了data-no-timeline的静态内容 →不报告sweep_static其他合法静态场景短时长、单采样、已报motion_frozen→ 均不重复上报。实操建议如果你有意识地制作静态合成标题卡、封面、品牌定格请在根元素上加上data-no-timeline属性如果你确实在使用 GSAP/CSS 时间线且被误报需要确认动画是否依赖data-*时序属性在 seek 下可被推进而不是仅在页面加载时自动播放。七、升级与验证v0.8.18 涉及studio、core、cli三个包的协同修复升级时建议Studio 端升级后先在自定义目录项目中验证合成切换与快照恢复重点检查变速媒体、嵌套片段、静态合成的撤销/重做CLI 端对修剪/加速视频重新生成关键帧确认帧内容与时间线一致检查导出路径与源路径隔离对静态合成重新运行hyperframes check确认不再出现sweep_static假阳性回归参考仓库中的相关测试与夹具check.test.ts、checkPipeline.ts、nested-sequential-video-local-start、frameCapture.ts可直接作为行为基线帮助定位升级后是否出现行为差异。如果你需要回溯完整变更范围可查看 releases/v0.8.18.md发布说明的维护流程如何用bun run release:prepare起草新版本见 releases/README.md。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HyperFrames v0.8.18 版本解读：Studio 跨目录合成编辑、快照保真与 CLI 渲染修复
HyperFrames v0.8.18 版本解读Studio 跨目录合成编辑、快照保真与 CLI 渲染修复【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames v0.8.18发布于 2026-08-29是一次聚焦编辑器体验与渲染正确性的维护版本。本次更新让 Studio 可以为项目任意位置不再局限于compositions/目录存储的合成切换画布与时间线并显著提升了项目快照对播放速率、嵌套媒体时序、静态合成与源文件的保真能力同时修复了嵌套视频的时间窗口可见性、修剪/加速视频关键帧采样错误、关键帧输出覆盖源文件风险以及data-no-timeline合成被误报冻结扫描frozen-sweep等问题。阅读本文后你可以准确理解每个修复背后的机制、涉及的源码位置以及如何在自己的项目中规避这些坑。一、Studio任意位置合成的画布与时间线切换在 v0.8.18 之前Studio 假定项目中的合成统一存放在compositions/目录下画布与时间线的切换逻辑对该路径有隐式依赖。本次更新解除了这一限制只要合成通过标准属性声明无论它存储在项目中的哪个目录Studio 都能正确为其切换画布canvas与时间线timeline。从源码结构看Studio 对合成宿主的识别并不依赖固定目录名而是依赖元素上的声明式属性。在 packages/studio/src/components/editor/LayersPanel.tsx 中判断逻辑是return el.hasAttribute(data-composition-src) || el.hasAttribute(data-composition-file);而 packages/studio/src/components/editor/domEditingDom.ts 则通过findClosestByAttribute向上查找携带data-composition-file/data-composition-src的宿主元素来解析合成来源。这意味着合成的真实存储位置只是一个路径值编辑器只要拿到该属性即可定位源文件并加载画布与时间线。这一点在仓库的测试夹具中得到印证例如 packages/producer/tests/nested-sequential-video-local-start/src/index.html 展示了宿主元素的标准写法div idroot>const playbackRate Number.parseFloat(element.dataAttributes[playback-rate] ?? 1) || 1;而在时间线编辑辅助逻辑 packages/studio/src/hooks/timelineEditingHelpers.ts 中修剪trim计算显式参与了播放速率value: Math.max(0, current trimDelta * Math.max(element.playbackRate ?? 1, 0.1)),可见播放速率并非仅仅影响播放预览它还直接参与剪辑边界计算因此快照若丢失该字段恢复后就会出现修剪位置错乱。本次修复正是补上了这类字段的快照持久化确保撤销/恢复后编辑状态完整。三、Core 修复长嵌套视频在宿主窗口前的可见性本次 Core 侧修复PR #3535针对的是嵌套媒体时序的一个边界问题当嵌套视频的本地起始时间local start早于宿主窗口host window的起点时长视频在时间线中可能被错误地隐藏。典型场景是一个长视频作为合成片段嵌入宿主时间线其本地data-start0但宿主中该片段被安排在 1s 处data-start1。此前引擎在计算可见区间时如果按本地起始时间与宿主窗口起点的简单比较判断会误以为视频已结束或尚未开始从而不渲染该片段。修复后引擎正确地将本地时间轴偏移与宿主窗口裁剪分开计算保证长视频在宿主窗口中持续可见。对应的测试夹具 packages/producer/tests/nested-sequential-video-local-start/src/index.html 正是为这类本地起始早于宿主窗口的嵌套顺序场景准备的回归用例。四、CLI 修复修剪/加速视频的关键帧采样正确性CLI 侧第一个修复PR #3536针对hyperframes render中的关键帧keyframe/poster 帧输出当源视频被修剪trim或加速speed up后关键帧采样必须落在正确的源帧上。问题本质是时间映射用户在时间线上看到的合成时间与媒体源文件内部的源帧时间之间存在偏移与缩放关系。修剪引入偏移合成时间 t 对应源文件时间t trimStart加速引入缩放合成时间 t 对应源时间t * rate。此前若直接以合成时间对源文件采样就会截取到错误的源帧导致关键帧画面与视频实际内容错位。引擎侧的帧捕获核心实现在 packages/engine/src/services/frameCapture.ts其中captureFrameCore强调以绝对合成帧索引Math.floor(time * fps)为准进行采样与静态帧去重而不是依赖调用方传入的分块相对索引——这正体现了合成时间 → 帧映射必须端到端一致的设计原则。修复后无论媒体被修剪还是加速关键帧输出都会映射回正确的源帧。五、CLI 修复拒绝关键帧输出覆盖活动合成源第二个 CLI 修复PR #3534是一道防覆盖安全网当关键帧keyframe-shot的输出目标路径恰好指向当前正在使用的合成源文件时CLI 会直接拒绝执行避免渲染过程把项目源文件覆盖成输出产物。这类事故在自动化流程中极易发生比如脚本把--frame output或关键帧导出路径解析为与data-composition-src相同的路径。v0.8.18 在 CLI 层增加了路径比对与拒绝逻辑从源头阻断对活动合成源的破坏性写入。实操建议升级后如果发现关键帧导出报拒绝覆盖类错误请检查输出路径是否与项目中的data-composition-src/data-composition-file指向相同将关键帧输出重定向到独立目录如exports/、shots/即可正常执行。六、CLI 修复data-no-timeline合成不再触发误报的冻结扫描第三个 CLI 修复PR #3533针对hyperframes check审计的冻结扫描frozen-sweep守卫明确声明了data-no-timeline的静态合成不再被误报为sweep_static错误。要理解这个修复需要先理解冻结扫描守卫的设计。在 packages/cli/src/utils/checkPipeline.ts 中审计器为每个布局采样点生成几何透明度指纹geometry signature如果所有采样点的指纹完全相同说明 seek 根本没有推进时间线——此时审计器给出的所有绿色通过结论都不可信因此会报告sweep_static错误message: Timeline did not advance under seek; every green verdict on this run is unreliable., fixHint: Confirm the composition seeks a paused GSAP/CSS timeline under data-* timing attributes rather than only autoplaying.,但存在一类合法静态内容标题卡片、静态封面等本就不需要时间线。它们通过data-no-timeline属性显式声明我是静态的。此前守卫没有识别该声明会把这类合成误判为时间线没有推进产生假阳性错误。v0.8.18 修复后守卫首先检查该声明function detectSweepStatic(duration, geometrySignatures, motionIssues, hasNoTimelineDeclaration) { if (hasNoTimelineDeclaration) return []; if (duration SWEEP_STATIC_MIN_DURATION_SEC) return []; if (geometrySignatures.length 2) return []; if (motionIssues.some((issue) issue.code motion_frozen)) return []; ... }对应的浏览器端读取逻辑在 packages/cli/src/utils/checkBrowser.tsasync function hasNoTimelineDeclaration(page: Page): Promiseboolean { return page.evaluate( () document.querySelector([data-composition-id])?.hasAttribute(data-no-timeline) ?? false, ); }测试用例也同步覆盖了三种边界场景见 packages/cli/src/commands/check.test.ts6 秒合成几何在各采样点完全不变 → 报告sweep_static声明了data-no-timeline的静态内容 →不报告sweep_static其他合法静态场景短时长、单采样、已报motion_frozen→ 均不重复上报。实操建议如果你有意识地制作静态合成标题卡、封面、品牌定格请在根元素上加上data-no-timeline属性如果你确实在使用 GSAP/CSS 时间线且被误报需要确认动画是否依赖data-*时序属性在 seek 下可被推进而不是仅在页面加载时自动播放。七、升级与验证v0.8.18 涉及studio、core、cli三个包的协同修复升级时建议Studio 端升级后先在自定义目录项目中验证合成切换与快照恢复重点检查变速媒体、嵌套片段、静态合成的撤销/重做CLI 端对修剪/加速视频重新生成关键帧确认帧内容与时间线一致检查导出路径与源路径隔离对静态合成重新运行hyperframes check确认不再出现sweep_static假阳性回归参考仓库中的相关测试与夹具check.test.ts、checkPipeline.ts、nested-sequential-video-local-start、frameCapture.ts可直接作为行为基线帮助定位升级后是否出现行为差异。如果你需要回溯完整变更范围可查看 releases/v0.8.18.md发布说明的维护流程如何用bun run release:prepare起草新版本见 releases/README.md。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考