HyperFrames v0.7.61透明媒体代理Media Proxy管线、扁平检查器默认启用与 GSAP 时间线安全规则解析【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames v0.7.612026-07-17 发布是本仓库以「写 HTML、渲视频、为 Agent 而生」为核心理念的一次综合性更新。本版最核心的工程动作是把「自动媒体代理automatic media proxying」从 studio-server 一路打通到预览、播放、静态项目服务器与发布归档让 HEVC、带 alpha 通道视频、无法解码的格式在预览态自动转码为 H.264或 VP8代理而最终渲染始终使用原始文件同时把 Studio 的扁平属性检查器flat inspector设为默认面板并为 GSAP 时间线 lint 新增 seek 顺序与相对值安全校验。读完本文你将掌握代理机制何时触发、如何按项目关闭、hyperframes publish如何把代理烘焙进归档以及 Studio 扁平检查器与 GSAP 规则各自解决的工程问题。版本概览v0.7.61 的功能主线分为四大块媒体代理Media Proxy从 codec 探测、按需转码、LRU 缓存到运行时三路触发换源再到发布归档静态烘焙形成一条完整的透明链路。Studio 扁平检查器bug 修复右对齐数值、Stroke 宽度/样式拆分、非可视元素分区门控、修复 Slideshow 标签页后默认启用。GSAP 时间线 lint新增 seek 顺序安全、相对值二次写入者、tl.set初始隐藏、SVG draw-on 规则。Skills 与 CLI媒体技能新增 HeyGen 头像视频 本地 LTX 兜底的视频生成能力CLI 的 doctor 暴露 extract-cache 目录并新增--frames-cache-dir新增可配置转写超时。渲染管线始终不受代理影响无论代理开关如何render 一律用 FFmpeg 帧抽取解码原始文件见 mediaProxy.ts 中isRenderMode的实现说明代理只服务于浏览器预览态。自动媒体代理从探测到换源的全链路为什么需要代理浏览器对视频编解码器的支持因厂商而异HEVCH.265在 Chrome 上通常不可解码、Safari 依赖硬件ProRes 浏览器从不原生解码VP9 在 Chrome 可解而 Safari 不定带 alpha 通道的视频则需要在 Chromium 构建间保持一致。这些「browser-hostile」codec 会让video在预览时黑屏或报错但同一文件在 FFmpeg 渲染路径上却毫无问题。v0.7.61 的答案不是让用户手动转码而是在服务端探测 codec、按需转码出 H.264/VP8 代理并让运行时自动把预览元素切到代理地址——全程对用户透明。第一步Codec 事实探测与宿主表代理决策的第一步是回答「这个资产是什么 codec、浏览器是否友好」。实现集中在 mediaCodecMap.ts它基于mediaMetadata.ts的 ffprobe 探针每个资产只探测一次。宿主 codec 表BROWSER_HOSTILE_CODECSmediaCodecMap.ts给出每个 codec 的「代表性 MIME」供浏览器canPlayType判断Codec代表性 MIME说明hevcvideo/mp4; codecshvc1.1.6.L120.B0Chrome 一般不可解主要代理对象proresnull浏览器从不解码运行时直接代理、不查canPlayTypeav1video/mp4; codecsav01.0.08M.08按canPlayType条件判定vp9video/webm; codecsvp09.00.10.08条件性宿主Chrome 可解、Safari 不定支持处保留原文件不支持处透明代理注意这些 MIME 是刻意「粗糙」的ffprobe 无法输出精确的 RFC 6381 codec 字符串而一个误判为正的成本只是一次代理转码绝不影响正确性误判为负漏掉应代理的文件则由运行时 reactive 的videoWidth 0换源兜底。探测同时记录hasAlpha源自 ffprobe pix_fmt。带 alpha 的源会选用 VP8/WebM 代理变体保证透明度跨 Chromium 构建存活。探测结果通过scanProjectMediaCodecMap收集项目 HTML 中的video src解析为项目根相对路径名如/assets/videos/clip.mp4只把 browser-hostile 的资产写进注入映射——即运行时看到的window.__HF_MEDIA_CODEC_MAP__。第二步按需转码、有界并发与 LRU 缓存代理的转码执行体是 proxyTranscoder.ts。它把浏览器宿主 codec 转成缓存的、可 seek 的 H.264.mp4或 VP8.webm代理缓存落在项目目录下的.transcode-cache/。几个值得注意的工程设计有界并发ffmpeg 内部多线程2 个并发转码已能占满典型笔记本。全局信号量默认MAX_CONCURRENT_TRANSCODES 2、等待队列MAX_QUEUED_TRANSCODES 8可通过环境变量HYPERFRAMES_PROXY_MAX_CONCURRENCY1–16与HYPERFRAMES_PROXY_MAX_QUEUE0–256调节。同 key 去重in-flight dedupe同一缓存 key 的并发调用预热的 pre-warm 与元素触发的请求竞速共享同一个 ffmpeg 子进程与同一个 Promise绝不重复转码。请求生命周期解耦转码 Promise 不挂接 AbortSignal。页面刷新/HMR 取消请求时ffmpeg 子进程照常跑完缓存条目照样落盘下个请求直接命中。硬超时TRANSCODE_TIMEOUT_MS 15 * 60 * 1000挂死的 ffmpeg 会被 SIGKILL 并释放槽位长资产按约实时转码的耗时足够覆盖。失败负缓存转码失败按缓存 key 记忆 60 秒FAILURE_CACHE_TTL_MS浏览器对坏资产的重复?hf-proxy请求会立即重抛错误而不是每轮重起 ffmpeg。FfmpegUnavailableError刻意不进负缓存——中途安装 ffmpeg 必须无需重启即恢复。缓存 key 的稳定性SHA-256 混合项目相对源路径、规范源身份外部 symlink 重定向时不误用旧代理、mtime 文件大小同秒重导出防碰撞、参数版本 tokenPROXY_PARAMS_VERSION v4改配方即失效全部旧缓存与变体。缓存空间由 proxyCache.ts 的cleanupProxyCache管理默认 10 GiB 上限、30 天闲置回收、1 小时前的.tmp-残留清扫、5 分钟最小清扫间隔全部可用HYPERFRAMES_PROXY_CACHE_MAX_BYTES、HYPERFRAMES_PROXY_CACHE_MAX_IDLE_DAYS、HYPERFRAMES_PROXY_CACHE_STALE_TEMP_MS、HYPERFRAMES_PROXY_CACHE_SWEEP_INTERVAL_MS覆盖。清扫带protectedPaths当前 in-flight 的缓存路径保护且失败只告警、绝不让可播放的预览变成错误。HDR 素材走 zscale/tonemap 滤镜链zscaletlinear:npl100,tonemaphable:desat0,zscalepbt709:...做色调映射到 bt709若 ffmpeg 缺少 libzimgzscale/tonemap会抛出明确的FfmpegMissingFilterError。VP8 变体保留源色彩值HDR 的 tonemap 会丢弃 alpha所以 alpha 代理不经过它。第三步运行时三路触发换源浏览器端换源逻辑在 mediaProxy.ts。codec 映射以window.__HF_MEDIA_CODEC_MAP__注入注入而非 fetch保证确定性键为项目根相对路径名运行时deriveCodecMapKey把元素currentSrc解析为同源、percent-decoded、去 query 的 pathname 后查表。路由前缀场景studio-server 预览路由注入base href/api/projects/:id/preview/用「先精确、后最长后缀、再大小写/Unicode 规范化后缀」三级查找兼容。换源有三个触发时机ProxyTrigger proactive | reactive | tertiaryproactive主动首次load()前查表browserHostile且canPlayType不给probably/maybe就提前换源避免错误闪烁。audio永不代理——HEVC 容器里的 AAC 轨在不解视频的浏览器中也能正常 demux。reactive反应式主兜底loadedmetadata时videoWidth 0。HEVCAAC 文件因 AAC 轨满足了 demuxer 而不会触发 error 事件这是最常见的「不可解码」表现。换源后evictMediaSyncState清掉按原源计算的漂移偏移等同步状态让下一 tick 按首 tick 处理。tertiary错误事件极少数「零可解码流」的文件纯视频宿主 codec连loadedmetadata都不触发靠error事件兜底。若映射标记为浏览器安全却仍报错说明文件本身损坏代理无用只发诊断。换源 URL 追加?hf-proxyh264或 alpha 源为?hf-proxyvp8无映射条目时为auto。每个元素用WeakSet保证只换一次杜绝循环换源。每次换源或无法换源都会发出带稳定 code 的诊断runtime_media_proxy_fallback/runtime_media_proxy_unavailableconsole 行保留 code token 供checkBrowser.ts的 console 抓取器匹配。换源永远只影响预览元素诊断 note 明确写着 render output is unaffected; only this preview element was swapped to an authoring proxy。第四步预览、播放、check 与发布归档全线接入同一套代理设施被多个命令复用Studio Server预览路由按需转码并服务 H.264 代理PR #2589代理缓存做 LRU 记账PR #2588codec 事实探测PR #2587预览路由直接 serve 代理PR #2590。CLI play / 静态项目服务器从 play 与静态项目服务器 serve 代理PR #2593。CLI check代理解析先于 check 的定时浏览器阶段完成PR #2594浏览器阶段可依赖已就绪的代理。发布归档烘焙见下一节。发布归档把代理静态烘焙进_proxy/预览/play 面是有服务端的可以按需?hf-proxy协商但发布后的页面是静态的、没有服务端无法在运行时换源。所以 publishProxyBake.ts 在打包时就把代理「烘焙」进归档扫描归档内 HTML 条目里的本地video src复用scanProjectMediaCodecMap对每个 browser-hostile 资产经 studio-server 共享的转码器waitForProxy(resolveProxy(...), TRANSCODE_TIMEOUT_MS)得到代理文件把代理字节写入归档的_proxy/前缀下镜像localizeExternalAssets的_ext/约定只重写归档 HTML 副本中匹配的video src属性指向代理磁盘上的项目文件从不动——只改内存中的归档文件 MapbuildPublishFileMap→ bake →zipPublishFileMap。失败语义很关键某个 hostile 资产的转码失败会抛ProxyBakeError并携带结构化 manifestproxied/failed数组中止发布而不是静默交付一个无法播放的资产。alpha 源烘焙为 VP8/WebM 保留透明。audio永不重写AAC 在 HEVC 容器中可独立 demux。cloud render不经过烘焙R2 路径直接构建并压缩文件 Map。发布命令的对应开关publish.tshyperframes publish # 默认烘焙 H.264 代理 hyperframes publish --no-proxy # 跳过烘焙除非 hyperframes.json 里显式开启--proxy/--no-proxy显式标志在任一方向上都优先于项目配置。按项目关闭hyperframes.json的media.autoProxy自动代理默认开启但不需要它的项目可以显式关闭。配置位于项目根目录hyperframes.json的media节读写实现在 projectConfig.ts{ registry: https://hyperframes.heygen.com/registry, paths: { blocks: compositions, components: compositions/components, assets: assets }, media: { autoProxy: false } }ProjectConfigMedia.autoProxy的语义在 projectConfig.ts 中写得很清楚为支持的预览面自动把浏览器宿主 codec 转码为缓存的 alpha-aware 代理render 无论该设置如何都使用原始文件。默认值trueDEFAULT_PROJECT_CONFIG。解析优先级由resolveAutoProxy(projectDir, flagValue)projectConfig.ts定义调用方的显式--proxy/--no-proxy布尔标志最优先其次读hyperframes.json的media.autoProxy两者都未设置时回退true。Studio 扁平检查器成为默认面板v0.7.61 在完成一轮 bug 修复后把扁平检查器flat inspector设为 Studio 默认属性面板commita4167ede0。本版涉及的修复源码位于 PropertyPanelFlat.tsx 及其分区组件propertyPanelFlat*Section.tsx包括右对齐值输入FlatRow的 value input 右对齐b32f9a3e8Stroke 宽度/样式拆分Stroke width 不再需要输入 style 名称d5a259a3d非可视元素分区门控Layout 与 Style 分区仅在元素有渲染盒rendered box时才显示8a793ba2bSlideshow 标签页修复非 slideshow 组合隐藏 Slideshow 标签页与面板67696cd8d并用子串检查短路 slideshow-island 检测review N253b362143其他体验项Text 分区行距加大、promote-to-variable 徽标移到行上方并预留 gutter、Design 面板变量提升后重同步共享 SDK 会话578d6202b。另有 runtime 级修复CSS.escape id让数字开头的选择器不再崩溃9bbdcc4ec。GSAP 时间线 lint 新规则lint 的 GSAP 规则集gsap.ts新增两类安全校验服务于 HyperFrames 的确定性 seek 渲染模型——渲染器把帧分发到多 worker冷启动 worker 会按序 seek任何依赖 seek 顺序的状态都会在不同 worker 间产生差异seek 顺序安全PR #2611gsap_cold_seek_hidden_fromto_missing_reveal规则gsap.ts中opacity冷 seek 显隐相关55ee559e4也补上了 cold-seek opacity reveal 的漏网案例。fromTo的from值会成为任何 seek 之前的元素静息状态——如果 seek 落在首个 tween 之前元素会停留在from值上必须用tl.set(selector, {...}, 0)建立显式的「硬杀」初值。同理tl.set初始隐藏会警告gsap_timeline_set_initial_hide因为非线性 seek 可能落在淡出之后而留下过期可见性状态。冷 seek 且目标 vars 缺少opacity: 1/autoAlpha: 1时会建议补上可见终态。相对值二次写入者PR #2612相对 tween 值/-在首帧渲染的 tween init 时捕获基准如果该属性上另一个 writer 仍处于活动状态相对值捕获到的基准就取决于先行 writer 的执行次序这在按 start-time 顺序渲染子元素的单个 seek pass 里是顺序敏感的。gsap_relative_value_second_writer正是为此而设另有 SVG draw-onpathLengthtrick规则覆盖常见的单组件描边画线形式。这些规则让「同样的时间线在不同 worker、不同 seek 路径上渲染一致」成为可静态保证的约束而非运行时碰运气。媒体技能视频生成能力skills 的media-use技能新增视频生成PR #2614。按 meta.md 的说明resolve --type video优先走 HeyGen 头像视频免费使用路径OAuth 会话可享用 web 套餐的免费头像视频额度认证失败时向 stderr 提示登录并继续本地 LTX 兜底videogen阶梯落在scripts/lib/local-models.mjsLTX 2.3 on MLX即ltx-video-provider.mjs。HeyGen 的每次生成调用TTS、头像视频、目录条目都带请求标记便于配额与归属审计。图像转视频、照片头像、配音/翻译仍为手动heygenCLI 配方operations.md。其他值得注意的 CLI 与修复doctor 与缓存目录CLI 的 doctor 现在输出 extract-cache 目录并新增--frames-cache-dir糖参数ca3522750render.ts正确导入EXTRACT_CACHE_DIR_DISABLED_ALIASES9fc7390c2。转写超时可配置的转写超时默认按时长缩放f8210d96d转写相关修复包括多语言模型先选再下载584be6d64、卡住的模型下载超时75eedf5cc、避开 Python whisper CLI 冲突9b17a5ad7。分辨率--resolution别名标志接受竖屏比例46e9ecf3faspect-agnostic 分辨率贯通 cloudrun/lambda/batch 与 preflight 重算2d398ed27。运行时/核心导出带documentRef参数的运行时起始解析器fd19a1563并修正 dist 导出94929815f组合变量不再遮蔽作者编写的 CSS 自定义属性PR #2553引擎忽略良性媒体请求中止PR #2423、复用 HyperFrames 浏览器缓存PR #2459、保留单声道音量PR #2392。macOS 提示macOS 13 上 chrome-headless-shell dyld 崩溃时CLI 提示设置HYPERFRAMES_BROWSER_PATH0d16f19b0不支持的新版 Node 会明确失败e846cd600。GCP Cloud Run包含工作区全部构建依赖PR #2608。结语v0.7.61 的工程重心清晰让「浏览器播不了」的素材在预览面彻底隐形——服务端有界并发转码 LRU 缓存 失败负缓存浏览器端三路触发换源发布时静态烘焙进_proxy/而渲染路径自始至终只碰原始文件。配合默认启用的扁平检查器与更严格的 GSAP seek 确定性校验这一版同时改善了交互体验与多 worker 渲染的一致性。若你想深入代理链路建议从 mediaCodecMap.ts、proxyTranscoder.ts、mediaProxy.ts 三份源码及对应测试proxyCache.test.ts、proxyTranscoder.test.ts、mediaProxy.test.ts、publishProxyBake.test.ts入手。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考