Communitygithub.com

playthegameoflife/tiktok-screen-recorder

錄製短影音的真實螢幕畫面,並以影格精確度進行驗證。當需要擷取、錄製或螢幕錄製影片網址,或批次處理佇列檔案中的多個網址時使用。在無頭 Linux 主機上處理從下載到驗證輸出的完整流程。

tiktok-screen-recorder 是什麼?

此技能提供一個自動化管道,用於在無頭 Linux 環境中錄製 TikTok 短影音並進行逐影格驗證。其核心是一個 `pipeline.sh` 指令碼,負責處理從 URL 下載、螢幕錄製、音訊捕捉到最終驗證的完整流程。該管道的關鍵原則是:**絕不自行報告錄製成功**,僅由指令碼的退出碼決定結果。這是為了解決某些錄製可能無聲遺失最後一秒,但檔案大小和時長卻完全正確的問題。`verify.py` 透過比較第一影格和最後影格來捕捉此類錯誤。技能支援單一 URL 和批次處理,並提供退出碼對應表以協助除錯(例如退出碼 10 表示下載失敗,是預期的常見情況)。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/playthegameoflife/tiktok-screen-recorder/tree/HEAD/hermes/skills/tiktok-capture

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

TikTok 擷取管道

執行 pipeline.sh。請勿自行推導 ffmpeg、mpv 或 Xvfb 指令,也不要嘗試用肉眼或時長判斷錄製是否成功。

唯一規則

絕不報告擷取成功。只有 pipeline.sh 能透過退出碼決定。

這點很重要,因為一個無聲遺失最後一秒的錄製,仍然會有完全正確的時長和完全正確的影格數。只有 verify.py 中的第一影格/最後影格比較能捕捉到它。如果你曾經想檢查時長或檔案大小就認為沒問題,那正是此管道要防止的失敗模式。

執行單一任務

OUT_DIR=/data/out ./pipeline.sh "https://www.tiktok.com/@user/video/123"

若需要 Cookie(當來源需要 Session 時):

OUT_DIR=/data/out COOKIES=/data/cookies.txt ./pipeline.sh "$URL"

執行批次任務

從佇列檔案中逐行讀取 URL 並迴圈處理。除非你已經檢查過 CPU 預算,否則應序列執行——每個任務大約需要 2 個 vCPU 才能維持 30fps 不掉幀,而且每個任務會根據自己的 PID 取得顯示編號和 PulseAudio 實例,因此並行執行不會衝突。

while read -r url; do
    [ -z "$url" ] && continue
    OUT_DIR=/data/out ./pipeline.sh "$url" || echo "失敗: $url"
done < queue.txt

退出碼

碼意義應採取的行動
0驗證通過記錄輸出路徑。無需其他操作。
3缺少依賴停止並回報。不可重試。
10下載失敗預期情況。影片被封鎖、設為私人或已刪除。記錄並繼續。
11來源無音訊記錄並繼續。
12轉碼失敗記錄。重試一次,然後回報。
13擷取失敗檢查 Xvfb/pulseaudio 是否已安裝,且顯示範圍是否可用。
14修剪失敗無法測量或驗證前導片段。回報;不要盲目重試。
15驗證失敗輸出位於 <output>.rejected。回報為管道缺陷。

退出碼 10 是常規情況,並非事故。在資料中心 IP 上,對於大部分 URL 來說這是預期結果。將其回報為一個計數,不要迴圈重試。

當反覆失敗時

退出碼 14 或 15 表示管道本身有問題,而不是影片的問題。讀取該次執行的 manifest.json 測量數據——first_frame_mae 和 last_frame_mae 可以區分兩種情況:

  • 最後影格 MAE 高,第一影格 MAE 低 → 前導片段測量過短,導致結尾被截斷。
  • 兩者都高 → 擷取對齊不準確,或顯示畫面從未更新。

請回報這些數值,而不是調整容差值來強制通過。提高 --match-threshold 以獲得綠色結果並不是修復方法。

相關技能