開發者文件
錄影同步驗證矩陣
SnapTray 如何以合成媒體、故障注入、解碼後檢查、A/B 報告與實機流程,端到端驗證錄影。
錄影同步驗證矩陣
Encoding_SyncMatrix 端到端驗證錄影:合成的影格與音訊經過錄影實際使用的時間元件(SessionClock、FramePacer、TimestampedPcmMixer)進入平台的編碼器與封裝,過程中注入故障;寫出的檔案再被解碼並逐格檢查。只有解碼後的媒體正確才算通過;狀態機跑完或播放器能開檔都不算證據。
原始碼:tests/Encoding/SyncMatrix.{h,cpp}(測試工具與分析)、tests/Encoding/tst_SyncMatrix.cpp(各情境)。
產生的內容
- 影像:每一格以 16 格條碼寫入影格編號,加上移動方塊,並在固定時間(從 350 ms 起每 700 ms)整面白色閃爍。靜止區段會重複同一編號,模擬畫面沒有變化。
- 音訊:每次閃爍時發出 40 ms、1 kHz 的脈衝,來源可以是麥克風、系統音訊或兩者混合,以 10 ms 的擷取回呼送出,時間戳記方式與實際擷取引擎相同。
故障
來源時間戳記與回呼到達時間分開控制:時間戳記抖動、延遲與突發到達、掉格/重複/倒退的影格、靜止畫面、提早與重複的暫停/繼續、單一音源暫時無聲、音訊時鐘偏移與漂移,以及編碼器暫時無法使用(在模擬時鐘上每 2 秒停頓一次;期間影格進入模擬編碼工作佇列,超過 30 格/3 秒的上限時會像實際工作佇列一樣被拒收)。
檢查項目(解碼後的媒體)
- 每個預期的影格都存在(逐次計數,靜止畫面遺失的重複影格也會被算到)、順序正確,並在預期時間呈現(誤差在半格內);沒有暫停期間的影格,暫停處也沒有空隙。
- 結尾完整:最後一格的編號與結束時間。
- 唯一影格與重複影格分開計算(
uniqueFps),不用重複影格湊出影格率。 - 要求音訊時音軌存在、長度涵蓋影片,且每次閃爍都在一個影格間隔加 25 ms 內有對應脈衝(
worstAvOffsetMs)。
預期值來自同一批事件、同一套時間元件、但不注入錯誤的參考執行。
證明檢查有效
detect-* 情境會刻意注入錯誤或管線不會修正的故障,分析必須回報失敗:未移除的暫停、音訊位移 120 ms、結尾被截掉 500 ms、倒退的時間戳記送進編碼器(編碼器會夾住,使影格出現在錯的時間),音訊引擎時鐘晚 150 ms 開始,以及靜止畫面的重複影格遺失。
執行
./scripts/run-tests.sh # 包含快速情境(約 10 秒)
./scripts/run-sync-matrix.sh # 快速情境,JSON 報告存於 build/sync-matrix/<commit>
./scripts/run-sync-matrix.sh reports/a --full # 加上 4K30、4K60 與長片 1080p30
SNAPTRAY_SYNC_LONG_S=600 ./scripts/run-sync-matrix.sh reports/b --full # 10 分鐘長片
scripts/sync-matrix-compare.py reports/a reports/b # 跨 commit A/B 比較
每份報告保存情境設定、預期值與量測值、失敗與略過的檢查,以及成本:實際與 CPU 時間、常駐記憶體、檔案大小、寫入影格數與編碼器拒收數。比較腳本在原本通過的情境失敗、或影音偏移增加超過 10 ms 時以狀態 1 結束。detect-* 情境以「有回報注入的錯誤」為通過(每份報告都記錄 mustPass 與 testSucceeded);候選結果缺少某個情境、候選目錄為空或不存在時,都視為錯誤。成本變化只列出、不判定,直到每台機器建立基準。只比較同一台機器、建置類型、編碼器與電源模式的結果。
平台
| 平台 | 結果 |
|---|---|
| Linux(FFmpeg/VA-API) | 完整:編碼、解碼與分析 |
| macOS、Windows | 略過,不算通過:解碼後分析使用 Linux 建置的 FFmpeg 讀取器,測試程式會明確回報略過。 |
原生 buffer、HDR 轉 SDR、混合 DPI、控制視窗排除與實際裝置變更無法以模擬取代,需要下方的實機流程。
實機流程(macOS、Windows、Linux 硬體)
- 製作含閃爍與嗶聲的參考影片:
ffmpeg -f lavfi -i "color=c=gray:s=1920x1080:r=60,drawbox=enable='lt(mod(t,1),0.05)':c=white:t=fill" \ -f lavfi -i "sine=f=1000:sample_rate=48000,volume=enable='gte(mod(t,1),0.05)':volume=0" \ -t 60 -shortest -pix_fmt yuv420p -c:v libx264 -c:a aac reference.mp4 - 在要錄製的螢幕上全螢幕播放並開啟系統音訊,用 SnapTray 錄製(另外錄一次中途暫停並繼續,以及一次讓麥克風靠近喇叭)。
- 量測錄影中的閃爍與嗶聲:
ffmpeg -i recording.mp4 -vf "signalstats,metadata=print:key=lavfi.signalstats.YAVG" -f null - 2>&1 | grep YAVG ffmpeg -i recording.mp4 -af silencedetect=n=-30dB:d=0.02 -f null - 2>&1 | grep silence_end閃爍影格的
YAVG很高;每個silence_end是嗶聲開始。兩者的差就是影音偏移。請一併記錄機器、作業系統、SnapTray 版本、解析度、影格率、編碼器與電源模式。