Communitygithub.com

上傳預檢

當使用者已渲染或匯出垂直影片,並想知道 TikTok、YouTube Shorts、Instagram Reels 或 Facebook Reels 是否會接受它,或為何上傳或排程發布失敗時使用。使用 ffprobe 執行已發布的檢查程式,並為每個失敗提供 FFmpeg 修復方案。

上傳預檢 是什麼?

上傳預檢技能可自動檢查垂直影片是否符合 TikTok、YouTube Shorts、Instagram Reels 與 Facebook Reels 等主要短影音平台的規範。它使用 GitHub 上的 shortform-preflight 工具,透過 ffprobe 讀取檔案,並對照各平台公開的技術規格進行比對,例如幀率、音訊編碼、檔案大小與持續時間。當檢查失敗時,技能會直接提供對應的 FFmpeg 命令來修復問題,避免使用者手動搜尋解決方案。此技能支援在 Claude Code、Cursor 等 AI 編碼代理程式中使用,透過 npx 執行檢查,並以 JSON 格式輸出詳細結果。它能區分不同平台的上傳規則(應用程式上傳、網頁上傳、API 發布),並特別處理直接發布端點的限制。使用者可以一次檢查所有平台或指定特定平台,並在修復後重新驗證檔案,確保完全符合規範後才進行上傳。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/viewgum/skills/tree/HEAD/skills/upload-preflight

在你喜歡的 AI 中提問

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

說明文件

上傳預檢 是做什麼的?

一個看起來沒問題的渲染仍然可能被拒絕或重新處理:某個 API 不接受的幀率、發布工具拒絕的音訊編碼器、超過大小限制的檔案、比應用程式允許時間更長的片段。此技能在檔案上執行 https://github.com/viewgum/shortform-preflight,該工具使用 ffprobe 讀取檔案,並根據每個應用程式發布的數據進行檢查,然後將每個失敗轉換為一個 FFmpeg 命令。

不適用於:判斷文字在畫面中的位置(請使用 short-form-specs),或影片的內容。

工作流程

  1. 僅在需要時釐清範圍。預設值:所有四個應用程式,以及每個應用程式的上傳規則(--route app)。對於 TikTok 的網頁上傳,請使用 --route web。如果使用者透過排程器或自己的程式碼發布,請使用發佈 API 規則(--api),這對 Facebook Reels 和 Instagram 更嚴格。對於 TikTok 的 Direct Post,請將帳戶的限制(來自 TikTok 創作者資訊的 max_video_post_duration_sec)作為 --tiktok-endpoint direct --tiktok-max-seconds <n> 傳遞;如果沒有提供,請說明長度未經驗證。
  2. 檢查工具:ffprobe -version(FFmpeg)、node -v(18 或更新版本)和 npx --version。第一次執行會從 GitHub 下載檢查器,因此也需要網路存取。如果缺少某個工具,請說明缺少什麼、如何安裝它,然後停止。
  3. 以 JSON 格式執行它,以便您能讀取每一行: npx -y github:viewgum/shortform-preflight <file> --json(視需要添加 --api 或 --platform tiktok,youtube-shorts)。 退出碼 0 表示沒有檢查失敗;1 表示檢查失敗或無法讀取必要的數值(應用程式顯示為不完整;請說明缺少哪個測量值);2 表示輸入錯誤。
  4. 對於每個失敗以及使用者可能遇到的每個警告,請用一行說明原因、該行引用的來源,以及一個修復方案。常見的修復方案(調整路徑並保持檔案的其他部分不變):
    • 幀率超出範圍:ffmpeg -i in.mp4 -r 30 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a copy -movflags +faststart -use_editlist 0 out.mp4
    • 編碼器、色度取樣或設定檔被拒絕:ffmpeg -i in.mp4 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a aac -b:a 192k -movflags +faststart -use_editlist 0 out.mp4
    • Moov atom 在結尾,或存在編輯列表(Instagram 的 API 拒絕這兩者):ffmpeg -i in.mp4 -c copy -movflags +faststart -use_editlist 0 out.mp4
    • 音訊取樣率、聲道或位元率(Facebook Reels API 列出 48 kHz 立體聲,128 kbps 或更高;設定為正好 128k 的編碼器通常平均會略低):ffmpeg -i in.mp4 -c:v copy -c:a aac -b:a 192k -ar 48000 -ac 2 -movflags +faststart -use_editlist 0 out.mp4
    • 時間太長:剪輯它,ffmpeg -i in.mp4 -t 89.9 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a aac -b:a 192k -movflags +faststart -use_editlist 0 out.mp4 (將 -t 設定得略低於限制:剪輯可能會多出一幀)。
    • 同時出現多行:將選項合併到一次重新編碼中,而不是串聯多次處理,如同範例執行所示。
    • 每次重新編碼:在 30 fps 時添加 -g 90(在 24 fps 時為 -g 72),以便關鍵幀每 3 秒出現一次;Facebook 的 API 要求封閉式圖像群組長度為 2 到 5 秒,檢查器無法測試這一點。請使用以下命令檢查: ffprobe -v error -select_streams v -skip_frame nokey -show_entries frame=pts_time -of csv=p=0 out.mp4
    • 檔案太大:降低品質設定(較高的 -crf)而不是降低解析度。
    • 不是 9:16:僅在使用者想要時才填充或裁切成 1080 x 1920;說明將會遺失哪些內容。
  5. 修正後,在新檔案上再次執行檢查器,並顯示該行現在通過。

輸出格式

**檔案:** demo.mp4 · 1080 x 1920 · 95 s · 23.976 fps · H.264 · AAC
**規則:** 發布 API

| 應用程式 | 結果 | 失敗或警告行 |
|---|---|---|
| Facebook Reels | 失敗 | 長度 95 秒(API 接受 3 至 90 秒);幀率 23.976(需要 24 至 60);44.1 kHz 和單聲道(列出 48 kHz 立體聲,警告) |
| Instagram Reels | 失敗 | 存在編輯列表(不允許任何編輯列表);moov atom 在媒體資料之後(必須在最前面) |

### 修復

一次重新編碼解決所有行:`ffmpeg -i demo.mp4 -t 89.9 -r 30 -c:v libx264 -crf 18 -pix_fmt yuv420p -c:a aac -b:a 192k -ar 48000 -ac 2 -g 90 -movflags +faststart -use_editlist 0 fixed.mp4`
(來源:Meta for Developers、Reels Publishing API 和 IG User Media)

**修復後:** 沒有失敗。
  • 引用檢查器自己的行;不要憑記憶重述限制。
  • 說明使用了哪些規則:應用程式上傳、網頁上傳或發布 API。
  • 資訊行(建議的位元率、測量的響度)不算失敗;僅在使用者詢問時才提及它們。

常見陷阱

  • 當重新封裝可以修復時,不要重新編碼。-c copy 加上 +faststart 可以保持品質。
  • 除非使用者要求,否則不要更改解析度或長寬比;先詢問,因為裁切會遺失畫面。
  • 不要將警告視為拒絕。僅根據來源的說法說明應用程式可能會做什麼(重新處理、透過 API 拒絕)。
  • 不要在原始檔案上執行 FFmpeg。始終寫入一個新檔案。
  • 不要猜測檢查器報告為未發布的限制。說明該應用程式未發布此限制。

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

相關技能