Hyperframes 中 VFR 屏幕錄制視頻的幀率凍結問題與回歸測試設計【免費下載鏈接】hyperframesWrite HTML. Render video. Built for agents.項目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesmacOS ScreenCaptureKitReplayKit這類屏幕錄制工具產出的視頻常是可變幀率VFR, Variable Frame Rate格式素材時間戳稀疏且不均勻而r_frame_rate與avg_frame_rate嚴重背離。Hyperframes 的渲染引擎此前在抽取這類素材時會讓畫面在合成器中被凍結——fps濾鏡吐出的幀數少于請求值查幀表返回空合成器便永久保持最后一幀。本文以倉庫中packages/producer/tests/vfr-screen-recording/這套回歸測試夾具為主線講解該夾具的來源與構造方式、VFR 的判定閾值與歸一化修復路徑以及測試對渲染質量的具體校驗指標幫助讀者理解超幀率/低均幀率素材在 Hyperframes 中從探測到抽取、再到合成校驗的完整處理鏈路。一、測試資產全貌一套為 VFR 凍結 bug 而生的回歸夾具回歸夾具位于packages/producer/tests/vfr-screen-recording/目錄內包含NOTICE.md素材來源與版權屬性說明即本篇文章的骨架文檔詳細記錄了源錄制、截取方式與被保留的幀率屬性meta.json回歸用例的描述與質量門禁minPsnr、maxFrameFailures 等src/clip.mp4核心 VFR 輸入素材是 macOS ScreenCaptureKit 錄制的 5 秒片段src/index.html渲染編排的 composition 頁面將素材以data-media-start1定位進一條 3 秒的時間線output/compiled.html、output/output.mp4編譯后的可執行頁面與最終渲染產物。從meta.json的描述可以明確該夾具的定位Regression test for the VFR (variable-frame-rate) screen-recording freeze bug (PR #360). Renders a 3-second composition with a macOS ScreenCaptureKit clip (r_frame_rate120, avg≈36fps) seeked to mediaStart1. Pre-fix, the fps filter emitted long runs of duplicate frames that the compositor held as a frozen image; post-fix, VFR→CFR normalization keeps frame-accurate timing.也就是說它是一段可反復運行的回歸證據只要有人重新引入 VFR 抽取缺陷這個用例的maxFrameFailures與minPsnr門禁就會被觸發從而在 CI 中攔截問題。整套夾具與修復的代碼位置存在明確呼應關系下文逐一拆解。二、素材溯源ReplayKit 錄制的裁剪、降采樣與時間戳保留NOTICE.md的核心義務是講清楚素材從哪里來、改了什么、里面錄的是什么這既是開源倉庫對素材合規性的要求也直接決定了測試的有效性src/clip.mp4取自一段21 秒的 macOS ScreenCaptureKitReplayKit錄制其com.apple.quicktime.authorQuickTime 標簽可用于確認錄制來源截取的是原錄制的16s–21s 區間共 5 秒分辨率從原始的2746×1902 降采樣到 480×332避免把超大素材塞進倉庫重編碼命令刻意保留了原始 VFR 時間戳ffmpeg -fps_mode passthrough -c:v libx264 -preset slow -crf 28 -an關鍵在于-fps_mode passthrough它讓編碼器原樣透傳輸入幀的時間戳間隔不做任何 CFR固定幀率化從而把時間戳不均勻這一 VFR 病灶完整保留下來。-an去掉音頻所以這套用例不校驗音頻呼應 meta.json 中minAudioCorrelation: 0的取值。同時 NOTICE 明確記錄畫面內容僅為公開的heygen-com/hyperframes倉庫主頁不含私有或可識別的個人內容——這保證了夾具可安全地隨開源倉庫分發。三、凍結 bug 的根因VFR 素材在 fps 濾鏡下幀數不足代碼注釋把 bug 講得非常直白見 videoFrameExtractor.ts 的回歸說明When such inputs hitextractVideoFramesRanges-ss start -i ... -t dur -vf fpsNpipeline, the fps filter can emit fewer frames than requested — e.g. a 4-second segment at 30fps would produce ~90 frames instead of 120. FrameLookupTable.getFrameAtTime then returns null for out-of-range indices and the compositor holds the last valid frame, which the user perceives as the video freezing.故障鏈可以拆成四步VFR 素材的時間戳本身稀疏且不均勻舊的-vf fpsN抽取管線在遇到這些不規則時間戳時輸出的幀數少于按時長 × 幀率計算出的期望幀數30fps×4s 應為 120 幀實際可能只有約 90 幀幀查找表FrameLookupTable.getFrameAtTime在索引越界時返回null合成器對null的兜底策略是保持最后一個有效幀于是畫面長時間凍結直到時間線走完。這解釋了為什么一個屏幕錄制里畫面沒變化的正常場景會成為渲染事故統計性內容不動的片段在 VFR 下表現為長時間不出幀一旦抽取數量不足最終渲染就會把長時間定格當成真實畫面輸出。修復方案VFR→CFR 的一趟式歸一化修復的核心是把 VFR 素材從-vf fpsN路徑切換到 FFmpeg一趟式-fps_mode cfr -r fps歸一化路徑見 videoFrameExtractor.ts 的參數分支非 VFR 走原 fps 濾鏡路徑metadata.isVFR為真時追加-fps_mode cfr -r ffmpegFps在抽取的同時把時間軸規整為 CFR。額外好處是無需單獨的歸一化預編碼步驟——packages/engine/src/services/extractionCache.ts中緩存版本從 v2 升到 v3 的注釋也記錄了這一變更one-pass VFR extraction (-fps_mode cfr) replaces the two-pass...。兩套抽取路徑的幀數邊界語義差異由于 CFR 與 VFR 路徑的結束邊界舍入行為不同引擎與 producer 共享了幀數計算以避免誤報。在 videoFrameExtractor.ts 中說明CFR 的 fps 濾鏡在結束邊界四舍五入到最近幀而 VFR 的-fps_mode cfr -r向上取整若不共享該計算完整抽取可能因兩邊差一幀而被誤判失敗。producer 側 videoFrameCoverage.ts 的expectedFramesForClip同樣實現了這一語義并在 expectedFramesForVideo 中依據entry.metadata.isVFR選擇ceilVFR或nearestCFR的舍入策略確保覆蓋率的期望幀數與底層抽取行為嚴格一致。四、夾具保留的屬性與 VFR 判定實現10% 閾值NOTICE.md強調夾具保留了原錄制的全部關鍵幀率屬性這正是讓 bug 可復現的前提。對照 meta.json 的說明核心指標如下表屬性值含義r_frame_rate120/1標稱/容器聲明的最大幀率ScreenCaptureKit 以 120 采樣avg_frame_rate~36.1 fps21720/601實際平均幀率按真實時間戳統計isVFRtrue兩者偏差約 70%遠超ffprobe.ts中的 10% 判定閾值修復前重復幀率中部 3s 片段以 30fps 抽取時約 34%與全量錄制各片段觀測到的 18%–44% 相符VFR 判定的源碼實現producer 的packages/producer/src/utils/ffprobe.ts只是對hyperframes/engine的再導出真正的探測邏輯在 engine 的 ffprobe.ts。extractMediaMetadata中先對r_frame_rate與avg_frame_rate兩個有理數字段做解析然后計算const rFps parseFrameRate(videoStream.r_frame_rate); const avgFps parseFrameRate(videoStream.avg_frame_rate); const fps avgFps || rFps; // VFR: r_frame_rate (max/nominal) differs from avg_frame_rate (actual average) by 10% const isVFR rFps 0 avgFps 0 Math.abs(rFps - avgFps) / Math.max(rFps, avgFps) 0.1;該實現位于 ffprobe.ts L745-L749對應的VideoMetadata.isVFR字段注釋為 True when r_frame_rate and avg_frame_rate differ significantly (10%)。值得強調的是parseFrameRateL654-L689在解析120/1、21720/601這類有理數時做了大量防御拒絕分子分母為 0 或非有限數、拒絕超過兩段的分式、拒絕符號異常避免把異常值泄漏到下游的-r編碼參數與幀數運算中。對照本夾具120 vs 36.1的偏差約 70%遠超 10% 閾值因此isVFR必然為 true素材會被穩定地路由進-fps_mode cfr歸一化路徑——這就是測試要覆蓋的分支。五、編排用例的構造與質量門禁3 秒合成編排src/index.html 是一個極簡 composition根元素聲明data-composition-idvfr-screen-recording、data-duration3、data-width480、data-height332并帶data-no-timeline無復雜時間軸僅一段靜態場景。內部的video指向clip.mp4關鍵參數data-start0、data-duration3該片段在時間線占 3 秒data-media-start1從素材內部第 1 秒起播而非 0 秒刻意讓抽取發生在素材中部因為凍結問題在素材中段 seek時最容易復現——正如 meta.json 所述 Pre-fix, the fps filter emitted long runs of duplicate frames頂層還覆蓋了一個VFR標簽層用于人工目檢。output/compiled.html是引擎編譯后內嵌字體與樣式的最終頁面可與src/index.html對照理解編譯產物的形態。渲染參數與質量斷言meta.json 同時攜帶了該用例的通過標準renderConfig: { fps: 30, workers: 1 }以 30fps、單 worker 確定性渲染便于逐幀比對minPsnr: 28渲染結果與參考視頻的 PSNR 不低于 28dB用于防止畫面出現大幅劣化例如整段凍結成同一幀maxFrameFailures: 2允許最多 2 幀級失敗閾值校驗對邊界幀有顯式容差可對比 videoFrameCoverage.test.ts 中容忍 VFR 抽取短片段邊界差一幀的用例設計minAudioCorrelation: 0、maxAudioLagWindows: 1由于素材以-an編碼為無音軌音頻相關度要求放寬為 0但音頻滯后窗口上限仍保留 1防止回歸用例因渲染器對靜音軌的錯誤處理而翻車。這些門禁直接作用于output/output.mp4把畫面是否真的在動轉化為可自動量化的數字而非依賴人工觀看。六、更接近生產環境的 VFR 合成回歸測試除真實錄屏夾具外引擎還提供了用 FFmpeg 現場合成的 VFR 素材回歸測試見 videoFrameExtractor.test.ts L1563 起testsrc2s320x180:d10:rate60生成 10 秒 60fps 測試圖再用select表達式丟棄四段 1 秒窗口幀 30–89、180–239、330–389、480–539配合-vsync vfr編碼模擬屏幕錄制中畫面無變化的靜態段落得到聲明 60fps、實際約 36fps的素材——與真機錄屏的屬性同構。測試同時用-g 600 -keyint_min 600強制單一關鍵幀確保中段 seek 不會吸附到 IDR 幀造成計數漂移。這說明倉庫對 VFR 的防護是雙保險既有貼近真實的 ReplayKit 錄屏夾具producer 端回歸又有完全可控的合成夾具engine 端回歸覆蓋從底層抽取到上層合成的整條鏈路。此外captureHdrResources.test.ts 也用sparse-vfr.mp4夾具驗證了元數據層面對稀疏 VFR 素材的isVFR判定。七、編譯期的 VFR 提示與建議預編碼命令在用戶側如果 HTML 素材里引用了 VFR 視頻producer 的編譯階段會給出非阻塞告警。見 htmlCompiler.ts 的 advisory 檢查編譯器對每個本地video并發執行關鍵幀間隔分析與媒體元數據探測若metadata.isVFR為真則向 stderr 輸出類似[Compiler] Video id is variable frame rate (VFR); the engine will normalize it to CFR before frame extraction. If rendering feels slow on this video, pre-encode once with: ffmpeg -i src -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags faststart -c:a copy output.mp4幾點值得注意的實現細節這些探測是fire-and-forget的且通過withMediaProbeSlot限流只產生警告、不阻塞編譯返回通過isHttpUrl直接跳過遠程 URL遠程素材無法在編譯期本地探測告警走defaultLogger.warnstderr而非console.infostdout注釋明確指出這是為了不污染check --json/validate --json的 stdout 輸出引擎雖然會自動把 VFR 歸一化到 CFR但對于體量較大的錄屏素材先手動預編碼一次仍能顯著縮短每次渲染的抽取耗時——這是工程上推薦的素材入庫習慣。八、如何在本地復現與驗證這套回歸讀者可在本倉庫中完整走查這套回歸流程閱讀 NOTICE.md確認素材來源與保留屬性檢查 src/clip.mp4可用ffprobe驗證r_frame_rate120/1、avg_frame_rate≈21720/601并運行extractMediaMetadata確認isVFRtrue用 src/index.html 作為 composition對比 output/compiled.html 觀察編譯產物差異以 meta.json 的renderConfig30fps、單 worker執行渲染依據minPsnr、maxFrameFailures等門禁判定通過與否修復前該用例會因 fps 濾鏡的重復幀長串而凍結修復后 VFR→CFR 歸一化保證逐幀時間精確。小結VFR 屏幕錄制素材在 Hyperframes 中走一條完整的探測—判定—歸一化—覆蓋率校驗鏈路ffprobe.ts用 10% 偏差閾值識別 VFRvideoFrameExtractor.ts用-fps_mode cfr -r一趟式歸一化消除凍結缺陷videoFrameCoverage.ts針對兩種抽取路徑維護一致的幀數舍入語義而packages/producer/tests/vfr-screen-recording/這套夾具則以一份嚴格溯源、完整保留幀率屬性的 ReplayKit 錄屏把這條鏈路固化成了可持續回歸的質量門檻——既是一份合規的素材來源說明更是一個可復現、可量化的渲染缺陷標本。【免費下載鏈接】hyperframesWrite HTML. Render video. Built for agents.項目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 Hyperframes 中 VFR 屏幕錄制視頻的幀率凍結問題與回歸測試設計
Hyperframes 中 VFR 屏幕錄制視頻的幀率凍結問題與回歸測試設計【免費下載鏈接】hyperframesWrite HTML. Render video. Built for agents.項目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesmacOS ScreenCaptureKitReplayKit這類屏幕錄制工具產出的視頻常是可變幀率VFR, Variable Frame Rate格式素材時間戳稀疏且不均勻而r_frame_rate與avg_frame_rate嚴重背離。Hyperframes 的渲染引擎此前在抽取這類素材時會讓畫面在合成器中被凍結——fps濾鏡吐出的幀數少于請求值查幀表返回空合成器便永久保持最后一幀。本文以倉庫中packages/producer/tests/vfr-screen-recording/這套回歸測試夾具為主線講解該夾具的來源與構造方式、VFR 的判定閾值與歸一化修復路徑以及測試對渲染質量的具體校驗指標幫助讀者理解超幀率/低均幀率素材在 Hyperframes 中從探測到抽取、再到合成校驗的完整處理鏈路。一、測試資產全貌一套為 VFR 凍結 bug 而生的回歸夾具回歸夾具位于packages/producer/tests/vfr-screen-recording/目錄內包含NOTICE.md素材來源與版權屬性說明即本篇文章的骨架文檔詳細記錄了源錄制、截取方式與被保留的幀率屬性meta.json回歸用例的描述與質量門禁minPsnr、maxFrameFailures 等src/clip.mp4核心 VFR 輸入素材是 macOS ScreenCaptureKit 錄制的 5 秒片段src/index.html渲染編排的 composition 頁面將素材以data-media-start1定位進一條 3 秒的時間線output/compiled.html、output/output.mp4編譯后的可執行頁面與最終渲染產物。從meta.json的描述可以明確該夾具的定位Regression test for the VFR (variable-frame-rate) screen-recording freeze bug (PR #360). Renders a 3-second composition with a macOS ScreenCaptureKit clip (r_frame_rate120, avg≈36fps) seeked to mediaStart1. Pre-fix, the fps filter emitted long runs of duplicate frames that the compositor held as a frozen image; post-fix, VFR→CFR normalization keeps frame-accurate timing.也就是說它是一段可反復運行的回歸證據只要有人重新引入 VFR 抽取缺陷這個用例的maxFrameFailures與minPsnr門禁就會被觸發從而在 CI 中攔截問題。整套夾具與修復的代碼位置存在明確呼應關系下文逐一拆解。二、素材溯源ReplayKit 錄制的裁剪、降采樣與時間戳保留NOTICE.md的核心義務是講清楚素材從哪里來、改了什么、里面錄的是什么這既是開源倉庫對素材合規性的要求也直接決定了測試的有效性src/clip.mp4取自一段21 秒的 macOS ScreenCaptureKitReplayKit錄制其com.apple.quicktime.authorQuickTime 標簽可用于確認錄制來源截取的是原錄制的16s–21s 區間共 5 秒分辨率從原始的2746×1902 降采樣到 480×332避免把超大素材塞進倉庫重編碼命令刻意保留了原始 VFR 時間戳ffmpeg -fps_mode passthrough -c:v libx264 -preset slow -crf 28 -an關鍵在于-fps_mode passthrough它讓編碼器原樣透傳輸入幀的時間戳間隔不做任何 CFR固定幀率化從而把時間戳不均勻這一 VFR 病灶完整保留下來。-an去掉音頻所以這套用例不校驗音頻呼應 meta.json 中minAudioCorrelation: 0的取值。同時 NOTICE 明確記錄畫面內容僅為公開的heygen-com/hyperframes倉庫主頁不含私有或可識別的個人內容——這保證了夾具可安全地隨開源倉庫分發。三、凍結 bug 的根因VFR 素材在 fps 濾鏡下幀數不足代碼注釋把 bug 講得非常直白見 videoFrameExtractor.ts 的回歸說明When such inputs hitextractVideoFramesRanges-ss start -i ... -t dur -vf fpsNpipeline, the fps filter can emit fewer frames than requested — e.g. a 4-second segment at 30fps would produce ~90 frames instead of 120. FrameLookupTable.getFrameAtTime then returns null for out-of-range indices and the compositor holds the last valid frame, which the user perceives as the video freezing.故障鏈可以拆成四步VFR 素材的時間戳本身稀疏且不均勻舊的-vf fpsN抽取管線在遇到這些不規則時間戳時輸出的幀數少于按時長 × 幀率計算出的期望幀數30fps×4s 應為 120 幀實際可能只有約 90 幀幀查找表FrameLookupTable.getFrameAtTime在索引越界時返回null合成器對null的兜底策略是保持最后一個有效幀于是畫面長時間凍結直到時間線走完。這解釋了為什么一個屏幕錄制里畫面沒變化的正常場景會成為渲染事故統計性內容不動的片段在 VFR 下表現為長時間不出幀一旦抽取數量不足最終渲染就會把長時間定格當成真實畫面輸出。修復方案VFR→CFR 的一趟式歸一化修復的核心是把 VFR 素材從-vf fpsN路徑切換到 FFmpeg一趟式-fps_mode cfr -r fps歸一化路徑見 videoFrameExtractor.ts 的參數分支非 VFR 走原 fps 濾鏡路徑metadata.isVFR為真時追加-fps_mode cfr -r ffmpegFps在抽取的同時把時間軸規整為 CFR。額外好處是無需單獨的歸一化預編碼步驟——packages/engine/src/services/extractionCache.ts中緩存版本從 v2 升到 v3 的注釋也記錄了這一變更one-pass VFR extraction (-fps_mode cfr) replaces the two-pass...。兩套抽取路徑的幀數邊界語義差異由于 CFR 與 VFR 路徑的結束邊界舍入行為不同引擎與 producer 共享了幀數計算以避免誤報。在 videoFrameExtractor.ts 中說明CFR 的 fps 濾鏡在結束邊界四舍五入到最近幀而 VFR 的-fps_mode cfr -r向上取整若不共享該計算完整抽取可能因兩邊差一幀而被誤判失敗。producer 側 videoFrameCoverage.ts 的expectedFramesForClip同樣實現了這一語義并在 expectedFramesForVideo 中依據entry.metadata.isVFR選擇ceilVFR或nearestCFR的舍入策略確保覆蓋率的期望幀數與底層抽取行為嚴格一致。四、夾具保留的屬性與 VFR 判定實現10% 閾值NOTICE.md強調夾具保留了原錄制的全部關鍵幀率屬性這正是讓 bug 可復現的前提。對照 meta.json 的說明核心指標如下表屬性值含義r_frame_rate120/1標稱/容器聲明的最大幀率ScreenCaptureKit 以 120 采樣avg_frame_rate~36.1 fps21720/601實際平均幀率按真實時間戳統計isVFRtrue兩者偏差約 70%遠超ffprobe.ts中的 10% 判定閾值修復前重復幀率中部 3s 片段以 30fps 抽取時約 34%與全量錄制各片段觀測到的 18%–44% 相符VFR 判定的源碼實現producer 的packages/producer/src/utils/ffprobe.ts只是對hyperframes/engine的再導出真正的探測邏輯在 engine 的 ffprobe.ts。extractMediaMetadata中先對r_frame_rate與avg_frame_rate兩個有理數字段做解析然后計算const rFps parseFrameRate(videoStream.r_frame_rate); const avgFps parseFrameRate(videoStream.avg_frame_rate); const fps avgFps || rFps; // VFR: r_frame_rate (max/nominal) differs from avg_frame_rate (actual average) by 10% const isVFR rFps 0 avgFps 0 Math.abs(rFps - avgFps) / Math.max(rFps, avgFps) 0.1;該實現位于 ffprobe.ts L745-L749對應的VideoMetadata.isVFR字段注釋為 True when r_frame_rate and avg_frame_rate differ significantly (10%)。值得強調的是parseFrameRateL654-L689在解析120/1、21720/601這類有理數時做了大量防御拒絕分子分母為 0 或非有限數、拒絕超過兩段的分式、拒絕符號異常避免把異常值泄漏到下游的-r編碼參數與幀數運算中。對照本夾具120 vs 36.1的偏差約 70%遠超 10% 閾值因此isVFR必然為 true素材會被穩定地路由進-fps_mode cfr歸一化路徑——這就是測試要覆蓋的分支。五、編排用例的構造與質量門禁3 秒合成編排src/index.html 是一個極簡 composition根元素聲明data-composition-idvfr-screen-recording、data-duration3、data-width480、data-height332并帶data-no-timeline無復雜時間軸僅一段靜態場景。內部的video指向clip.mp4關鍵參數data-start0、data-duration3該片段在時間線占 3 秒data-media-start1從素材內部第 1 秒起播而非 0 秒刻意讓抽取發生在素材中部因為凍結問題在素材中段 seek時最容易復現——正如 meta.json 所述 Pre-fix, the fps filter emitted long runs of duplicate frames頂層還覆蓋了一個VFR標簽層用于人工目檢。output/compiled.html是引擎編譯后內嵌字體與樣式的最終頁面可與src/index.html對照理解編譯產物的形態。渲染參數與質量斷言meta.json 同時攜帶了該用例的通過標準renderConfig: { fps: 30, workers: 1 }以 30fps、單 worker 確定性渲染便于逐幀比對minPsnr: 28渲染結果與參考視頻的 PSNR 不低于 28dB用于防止畫面出現大幅劣化例如整段凍結成同一幀maxFrameFailures: 2允許最多 2 幀級失敗閾值校驗對邊界幀有顯式容差可對比 videoFrameCoverage.test.ts 中容忍 VFR 抽取短片段邊界差一幀的用例設計minAudioCorrelation: 0、maxAudioLagWindows: 1由于素材以-an編碼為無音軌音頻相關度要求放寬為 0但音頻滯后窗口上限仍保留 1防止回歸用例因渲染器對靜音軌的錯誤處理而翻車。這些門禁直接作用于output/output.mp4把畫面是否真的在動轉化為可自動量化的數字而非依賴人工觀看。六、更接近生產環境的 VFR 合成回歸測試除真實錄屏夾具外引擎還提供了用 FFmpeg 現場合成的 VFR 素材回歸測試見 videoFrameExtractor.test.ts L1563 起testsrc2s320x180:d10:rate60生成 10 秒 60fps 測試圖再用select表達式丟棄四段 1 秒窗口幀 30–89、180–239、330–389、480–539配合-vsync vfr編碼模擬屏幕錄制中畫面無變化的靜態段落得到聲明 60fps、實際約 36fps的素材——與真機錄屏的屬性同構。測試同時用-g 600 -keyint_min 600強制單一關鍵幀確保中段 seek 不會吸附到 IDR 幀造成計數漂移。這說明倉庫對 VFR 的防護是雙保險既有貼近真實的 ReplayKit 錄屏夾具producer 端回歸又有完全可控的合成夾具engine 端回歸覆蓋從底層抽取到上層合成的整條鏈路。此外captureHdrResources.test.ts 也用sparse-vfr.mp4夾具驗證了元數據層面對稀疏 VFR 素材的isVFR判定。七、編譯期的 VFR 提示與建議預編碼命令在用戶側如果 HTML 素材里引用了 VFR 視頻producer 的編譯階段會給出非阻塞告警。見 htmlCompiler.ts 的 advisory 檢查編譯器對每個本地video并發執行關鍵幀間隔分析與媒體元數據探測若metadata.isVFR為真則向 stderr 輸出類似[Compiler] Video id is variable frame rate (VFR); the engine will normalize it to CFR before frame extraction. If rendering feels slow on this video, pre-encode once with: ffmpeg -i src -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags faststart -c:a copy output.mp4幾點值得注意的實現細節這些探測是fire-and-forget的且通過withMediaProbeSlot限流只產生警告、不阻塞編譯返回通過isHttpUrl直接跳過遠程 URL遠程素材無法在編譯期本地探測告警走defaultLogger.warnstderr而非console.infostdout注釋明確指出這是為了不污染check --json/validate --json的 stdout 輸出引擎雖然會自動把 VFR 歸一化到 CFR但對于體量較大的錄屏素材先手動預編碼一次仍能顯著縮短每次渲染的抽取耗時——這是工程上推薦的素材入庫習慣。八、如何在本地復現與驗證這套回歸讀者可在本倉庫中完整走查這套回歸流程閱讀 NOTICE.md確認素材來源與保留屬性檢查 src/clip.mp4可用ffprobe驗證r_frame_rate120/1、avg_frame_rate≈21720/601并運行extractMediaMetadata確認isVFRtrue用 src/index.html 作為 composition對比 output/compiled.html 觀察編譯產物差異以 meta.json 的renderConfig30fps、單 worker執行渲染依據minPsnr、maxFrameFailures等門禁判定通過與否修復前該用例會因 fps 濾鏡的重復幀長串而凍結修復后 VFR→CFR 歸一化保證逐幀時間精確。小結VFR 屏幕錄制素材在 Hyperframes 中走一條完整的探測—判定—歸一化—覆蓋率校驗鏈路ffprobe.ts用 10% 偏差閾值識別 VFRvideoFrameExtractor.ts用-fps_mode cfr -r一趟式歸一化消除凍結缺陷videoFrameCoverage.ts針對兩種抽取路徑維護一致的幀數舍入語義而packages/producer/tests/vfr-screen-recording/這套夾具則以一份嚴格溯源、完整保留幀率屬性的 ReplayKit 錄屏把這條鏈路固化成了可持續回歸的質量門檻——既是一份合規的素材來源說明更是一個可復現、可量化的渲染缺陷標本。【免費下載鏈接】hyperframesWrite HTML. Render video. Built for agents.項目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考