Communitygithub.com

上传预检

当用户导出竖版视频并想知道 TikTok、YouTube Shorts、Instagram Reels 或 Facebook Reels 是否会接受它,或者上传/定时发布失败的原因时使用。通过 ffprobe 运行发布的检查器,并为每个失败提供 FFmpeg 修复命令。

上传预检 是什么?

该技能用于在导出竖版视频后,自动检查其是否符合 TikTok、YouTube Shorts、Instagram Reels 和 Facebook Reels 等平台的上传要求。它利用 ffprobe 分析视频文件,并与各平台公开发布的技术规范进行比对,然后针对每个检测出的问题(如帧率、编码器、文件大小、时长等)生成对应的 FFmpeg 修复命令。用户无需记忆繁杂的平台限制,只需一步即可获得诊断和修复方案。支持上传 API、网页上传以及 TikTok Direct Post 等不同场景,并且可以一次检查多个平台。所有结果以 JSON 格式输出,便于自动化处理。

兼容平台~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。
  • 信息行(推荐的比特率、测量的响度)不是失败;仅在用户询问时提及。

常见陷阱

  • 当重新封装即可修复时,不要重新编码。配合 +faststart 的 -c copy 可以保持质量。
  • 除非用户要求,否则不要更改分辨率或宽高比;先询问,因为裁剪会丢失画面内容。
  • 不要将警告视为拒绝。仅按照来源所述说明应用可能采取的措施(重新处理、通过 API 拒绝)。
  • 不要对原始文件运行 FFmpeg。始终写入一个新文件。
  • 不要猜测检查器报告为未发布的限制。说明该应用未发布该参数。

Individual skills in this repo

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

相关技能