上传预检 是做什么的?
一个看起来正常的渲染结果仍然可能被拒绝或重新处理:帧率不符合 API 要求、音频编码器被发布工具拒绝、文件超出大小限制、剪辑长度超过应用程序限制。此技能对文件运行 https://github.com/viewgum/shortform-preflight ,该工具使用 ffprobe 读取文件,并对照各应用发布的技术参数进行检查,然后将每个失败转换为一条 FFmpeg 命令。
不适用的场景:文本在画面中的位置(请使用 short-form-specs),或视频的内容。
工作流程
- 仅在必要时明确范围。默认设置:所有四个应用,以及每个应用中的上传规则(
--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>传递;如果没有该信息,则说明长度未验证。 - 检查工具:
ffprobe -version(FFmpeg)、node -v(18 或更新的版本)和npx --version。首次运行会从 GitHub 下载检查器,因此还需要网络访问权限。如果缺少某些工具,请说明缺少什么、如何安装,然后停止。 - 运行它,以 JSON 格式输出以便读取每一行:
npx -y github:viewgum/shortform-preflight <file> --json(根据需要添加--api或--platform tiktok,youtube-shorts)。 退出码 0 表示没有失败;退出码 1 表示有检查失败或无法读取必需的参数(该应用显示为不完整;请说明缺少哪个测量值);退出码 2 表示输入错误。 - 对于每个失败以及用户可能遇到的每个警告,用一行说明原因、该行引用的来源以及一个修复方法。常见的修复方法(调整路径并保持文件的其余部分不变):
- 帧率超出范围:
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;说明会丢失哪些内容。
- 帧率超出范围:
- 修复后,对新文件再次运行检查器,并显示该行现在已通过。
输出格式
**文件:** 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。始终写入一个新文件。
- 不要猜测检查器报告为未发布的限制。说明该应用未发布该参数。