D6 剪辑台：用 ffmpeg 把素材合成一集竖屏成片

今日目标

能用 ffmpeg 把多个镜头按时间轴拼接成一集竖屏成片
能给成片加上字幕、音轨、转场与封面，并输出平台能接受的编码参数
能让程序按结构化时间轴生成命令，而不是把命令交给模型自由发挥

昨天你已经有了每一镜的画面、每一句台词的声音，还有一张时间轴表。今天要做的就一件事：把这些散落的文件变成一个能发出去的 mp4。读完回到页面顶部把三条目标勾掉。

小白版讲解

剪辑台上只有一张表

剪辑师面前的屏幕分成两半：上面是预览窗，下面是一条横着铺开的轨道。轨道上一格一格排着素材，每一格标着从第几秒到第几秒。剪辑师干的活说白了就是把这些格子按顺序摆好，让画面和声音在同一个时刻对上。

我们要做的事一模一样，只是那条轨道不是拖出来的，是算出来的。昨天 D5 已经把它定义好了：一个数组，每一条记录说清「哪一镜、从第几毫秒到第几毫秒、放哪个视频文件、配哪段声音、打哪句字幕」。这就是时间轴（timeline），今天所有工作都从它开始。

它长这样，一集四镜，二十一秒：

JSONJSON

[
  {
    "shotId": "s01",
    "startMs": 0,
    "endMs": 6000,
    "clipPath": "work/runs/run-20260907-001/shots/s01/clip.mp4",
    "voicePath": "work/runs/run-20260907-001/shots/s01/voice.mp3",
    "subtitle": "这手机怎么自己亮了"
  },
  { "shotId": "s02", "startMs": 6000, "endMs": 11000, "...": "..." }
]

请先记住一条规矩：这张表是唯一的真相。 成片多长、字幕什么时候出、封面从第几秒截，全部只能从这张表算出来，代码里不许出现手敲的时间数字。当读者反馈「第三镜的字幕慢了半秒」时，你不用去翻十几条 ffmpeg 命令找那个 0.5，只要看表里第三条的 startMs 是怎么算出来的。bug 有且只有一个藏身之处。

第一条从表里算出来的东西，就是字幕文件。SRT 的格式简单到有点朴素：一个序号、一行起止时间码、一到两行文字，中间空行隔开。

srt.js

// 时间码格式是 时:分:秒,毫秒 —— 毫秒前面是逗号，不是点。
// 写成点的字幕文件，多数播放器会直接当作没有字幕，而且不报错。
function srtTime(ms) {
  const p = (n, w = 2) => String(n).padStart(w, '0')
  const h = Math.floor(ms / 3600000)
  const m = Math.floor(ms / 60000) % 60
  const s = Math.floor(ms / 1000) % 60
  return `${p(h)}:${p(m)}:${p(s)},${p(ms % 1000, 3)}`
}
 
export function renderSrt(entries, leadInMs = 200) {
  let index = 0
  return entries
    .filter((e) => e.subtitle)
    .map((e) => {
      index += 1
      // 首尾各留一点呼吸：镜头刚切进来的那一瞬间不出字，镜尾也提前收掉。
      const from = e.startMs + leadInMs
      const to = Math.max(from + 500, e.endMs - leadInMs)
      return `${index}\n${srtTime(from)} --> ${srtTime(to)}\n${e.subtitle}\n`
    })
    .join('\n')
}

srt.py

# 时间码格式是 时:分:秒,毫秒 —— 毫秒前面是逗号，不是点。
# 写成点的字幕文件，多数播放器会直接当作没有字幕，而且不报错。
def srt_time(ms: int) -> str:
    h, m, s = ms // 3_600_000, ms // 60_000 % 60, ms // 1000 % 60
    return f"{h:02d}:{m:02d}:{s:02d},{ms % 1000:03d}"
 
 
def render_srt(entries: list[dict], lead_in_ms: int = 200) -> str:
    blocks = []
    for index, e in enumerate((x for x in entries if x.get("subtitle")), start=1):
        # 首尾各留一点呼吸：镜头刚切进来的那一瞬间不出字，镜尾也提前收掉。
        start = e["startMs"] + lead_in_ms
        end = max(start + 500, e["endMs"] - lead_in_ms)
        blocks.append(f"{index}\n{srt_time(start)} --> {srt_time(end)}\n{e['subtitle']}\n")
    return "\n".join(blocks)

这段代码里没有一个数字是拍脑袋来的，200 那个呼吸值也在参数里，改一次全片跟着改。它的价值不在于写得多聪明，而在于把「时间从哪来」这个问题彻底关死了。

那么接下来，把这些片段真正拼成一条视频该怎么拼？答案有两条完全不同的路，选错的代价是几十倍的耗时，或者一条从第二镜开始就花屏的片子。

拼接的两条路：一条快得离谱，一条慢得心疼

第一条路叫 concat 分离器（concat demuxer）。你写一个清单文件，一行一个片段，然后让 ffmpeg 按顺序读下去：

BashBash

# concat.txt 的内容：每行一个 file '绝对路径'
ffmpeg -f concat -safe 0 -i concat.txt -c copy -movflags +faststart joined.mp4

-c copy 是这条路的全部意义：不解码、不重新编码，只把数据包按顺序搬进新容器。 二十一秒的片子零点几秒就出来，画质一比特都没损失。

但它有一个不讲情面的前提：各段的编码参数必须完全一致。 分辨率、帧率、像素格式、采样率、声道数有一个对不上，轻则第二段开始花屏掉音，重则甩你一句 Non-monotonous DTS 然后产出一个时长错乱的文件。而 AI 生成的素材恰恰最容易不一致——同一家厂商不同模型的输出尺寸就可能不同，图生视频的产物还经常没有音轨。

第二条路叫滤镜图（filter graph）：把所有输入喂进一张有向图，ffmpeg 一边解码一边算，最后重新编码输出。它什么都能干——缩放、补边、混音、转场——代价是全片重编码，几十倍的耗时和一次画质损失。

新手最容易做的选择是「既然滤镜图什么都能干，那就一直用它」。这是错的，正确的做法是把两条路串起来：

归一化那一步的滤镜链是这样的，现在不必逐字看懂，只要看出它是被程序拼出来的就行：

BashBash

ffmpeg -i clip.mp4 -i voice.mp3 -filter_complex \
  "[0:v]scale=1080:1920:force_original_aspect_ratio=decrease,\
   pad=1080:1920:-1:-1:color=black,fps=24,trim=duration=6.000,setpts=PTS-STARTPTS[v];\
   [0:a]volume=0.25,aformat=sample_fmts=fltp:sample_rates=44100:channel_layouts=stereo,\
   apad,atrim=duration=6.000,asetpts=PTS-STARTPTS[amb];\
   [1:a]aformat=sample_fmts=fltp:sample_rates=44100:channel_layouts=stereo,\
   adelay=200|200,apad,atrim=duration=6.000,asetpts=PTS-STARTPTS[vo];\
   [amb][vo]amix=inputs=2:duration=longest:normalize=0[a]" \
  -map "[v]" -map "[a]" -c:v libx264 -crf 20 -pix_fmt yuv420p -r 24 \
  -c:a aac -b:a 128k -ar 44100 -ac 2 -t 6.000 seg-s01.mp4

转场是这道选择题的一个特例。两镜之间的淡入淡出，那几帧画面是新算出来的，没有不重新编码就能做出转场的办法。所以想加转场就得走滤镜图，用 xfade 把片段两两叠起来。这里有一个非常容易算错的地方：每段的起始偏移都要把前面已经吃掉的转场时长减回去。 四段之间有三个转场，每个 300 毫秒，成片会比时间轴短 900 毫秒——忘了同步修正字幕时间码，字幕就会越到后面偏得越多，而且偏得很均匀，看上去像「整体慢了一点」，最容易被误判成播放器的问题。

concat.js

// 两条路的选择点只有一处，且是纯函数：给它片段和是否要转场，还回一组参数。
// 参数是算出来的，不是拼字符串拼出来的，更不是模型生成的。
export function buildConcatArgs(segments, durationsMs, { fadeMs = 0 } = {}) {
  if (fadeMs === 0) {
    // 路一：参数一致，直接流拷贝。清单文件由调用方先写好。
    return ['-f', 'concat', '-safe', '0', '-i', 'concat.txt', '-c', 'copy', 'joined.mp4']
  }
  // 路二：xfade 链。offset 要减掉前面所有转场已经吃掉的时长。
  const fade = (fadeMs / 1000).toFixed(3)
  const chains = []
  let v = '0:v'
  let offsetMs = 0
  for (let i = 1; i < segments.length; i += 1) {
    offsetMs += durationsMs[i - 1] - fadeMs
    chains.push(`[${v}][${i}:v]xfade=transition=fade:duration=${fade}:offset=${(offsetMs / 1000).toFixed(3)}[v${i}]`)
    v = `v${i}`
  }
  return [...segments.flatMap((p) => ['-i', p]), '-filter_complex', chains.join(';'), '-map', `[${v}]`, 'joined.mp4']
}

concat.py

# 两条路的选择点只有一处，且是纯函数：给它片段和是否要转场，还回一组参数。
# 参数是算出来的，不是拼字符串拼出来的，更不是模型生成的。
def build_concat_args(segments: list[str], durations_ms: list[int], fade_ms: int = 0) -> list[str]:
    if fade_ms == 0:
        # 路一：参数一致，直接流拷贝。清单文件由调用方先写好。
        return ["-f", "concat", "-safe", "0", "-i", "concat.txt", "-c", "copy", "joined.mp4"]
 
    # 路二：xfade 链。offset 要减掉前面所有转场已经吃掉的时长。
    fade = f"{fade_ms / 1000:.3f}"
    chains, v, offset_ms = [], "0:v", 0
    for i in range(1, len(segments)):
        offset_ms += durations_ms[i - 1] - fade_ms
        chains.append(f"[{v}][{i}:v]xfade=transition=fade:duration={fade}:offset={offset_ms / 1000:.3f}[v{i}]")
        v = f"v{i}"
 
    inputs = [arg for p in segments for arg in ("-i", p)]
    return [*inputs, "-filter_complex", ";".join(chains), "-map", f"[{v}]", "joined.mp4"]

竖屏这块画布：一千零八十乘一千九百二十

短剧是竖着看的，画布固定 1080x1920，比例 9 比 16。这个数字本身没什么可讲的，值得讲的是素材尺寸和画布对不上时怎么办，因为这几乎必然会发生。

有两种处理：放大到填满画布、多出来的裁掉；或者等比缩小到装得下、四周补黑边。上面那条命令里的 force_original_aspect_ratio=decrease 加 pad 就是第二种——先保证不丢内容，再补边。为什么默认选它？因为裁切会切掉人物的头顶或下巴，而 AI 生成的画面里人脸的位置本来就不可控，一裁就容易翻车。补黑边至少是可预期的难看，不是随机的毁片。

还有一件比分辨率更容易被忽略的事：安全区。手机上播竖屏视频，画面最上和最下并不是全都看得见——刘海、圆角、进度条、平台叠上去的用户名和话题标签，都会压掉一部分。所以字幕不能贴着底边，画面主体也不要顶到最上面。把字幕放在从底部往上大约十分之一到六分之一的那条带子里，两侧各留一成空白，是比较稳的做法。

字幕一行放几个字也要定死。竖屏宽度只有 1080，一行超过十三四个汉字，字号就得缩到手机上看着费劲。超长的台词要在生成字幕时就断行，而不是指望播放器帮你断。

这就引出今天最重要的一个工程习惯。

探测能力，然后降级

遇到「这个功能不一定有」的时候，新手的做法是写进文档：「请确保你的 ffmpeg 支持 subtitles 滤镜」。这句话的实际效果约等于没写——读者不会看，看了也不知道怎么查，最后卡在一个看不懂的报错上放弃。

正确的做法是程序自己去探，探不到就走另一条路，并且告诉用户它走了哪条。ffmpeg 把支持的滤镜全列在 ffmpeg -filters 里，探测就是一次命令加一次匹配：

BashBash

ffmpeg -hide_banner -filters | grep -w subtitles

探得到就烧录，探不到就回落成软字幕——把 SRT 作为一条独立的字幕轨封装进 mp4 容器，用 mov_text 这个 mp4 认识的字幕编码：

BashBash

ffmpeg -i with-bgm.mp4 -i episode-1.srt -c copy -c:s mov_text \
  -metadata:s:s:0 language=chi episode-1.mp4

两条路产出的东西不一样：烧录的字幕是像素，任何播放器都关不掉，短剧发行通常要的就是这个；软字幕是一条可开关的轨道，好处是原片干净、随时能换一版翻译，坏处是很多平台的播放器默认不给你打开。所以默认策略是「能烧就烧，烧不了就封装，并且明确告诉用户现在是哪一种」，而不是二选一写死。

subtitle.js

import { execFile } from 'node:child_process'
import { promisify } from 'node:util'
const run = promisify(execFile)
 
async function hasFilter(name) {
  try {
    const { stdout } = await run('ffmpeg', ['-hide_banner', '-filters'])
    return new RegExp(`(^|\\s)${name}\\s`, 'm').test(stdout)
  } catch {
    return false // ffmpeg 都没有，那更谈不上有这个滤镜
  }
}
 
export async function attachSubtitles(video, srt, out) {
  if (await hasFilter('subtitles')) {
    const escaped = srt.replace(/:/g, '\\:').replace(/'/g, `\\'`)
    await run('ffmpeg', ['-y', '-i', video, '-vf', `subtitles='${escaped}'`, '-c:a', 'copy', out])
    return 'burned'
  }
  // 回落：软字幕轨。成片照样出得来，只是播放器里要手动打开。
  await run('ffmpeg', ['-y', '-i', video, '-i', srt, '-c', 'copy', '-c:s', 'mov_text', out])
  return 'soft'
}

subtitle.py

import re
import subprocess
 
 
def has_filter(name: str) -> bool:
    try:
        out = subprocess.run(["ffmpeg", "-hide_banner", "-filters"], capture_output=True, text=True).stdout
    except FileNotFoundError:
        return False  # ffmpeg 都没有，那更谈不上有这个滤镜
    return re.search(rf"(^|\s){name}\s", out, re.MULTILINE) is not None
 
 
def attach_subtitles(video: str, srt: str, out: str) -> str:
    if has_filter("subtitles"):
        escaped = srt.replace(":", r"\:").replace("'", r"\'")
        subprocess.run(["ffmpeg", "-y", "-i", video, "-vf", f"subtitles='{escaped}'", "-c:a", "copy", out], check=True)
        return "burned"
 
    # 回落：软字幕轨。成片照样出得来，只是播放器里要手动打开。
    subprocess.run(["ffmpeg", "-y", "-i", video, "-i", srt, "-c", "copy", "-c:s", "mov_text", out], check=True)
    return "soft"

这个模式的适用范围远不止字幕。硬件编码器在不在、某个格式的解码器有没有、系统字体装了哪些，都照这个套路：探一次、缓存结果、降级、告知。它比在 README 里写一行「请确保」有效得多。

音画不同步，先看这三个地方

成片出来第一件事是听。音画不同步是这一环最高频的问题，而且现象都长得一样——嘴型和声音差半拍——但原因完全不同。按这个顺序查，绝大多数情况三步之内能定位：

第一，看时间轴表。 把每一条的 endMs 减 startMs，和这一镜视频文件的真实时长比一比。表里写着六秒、文件其实是 5.8 秒，那么从这一镜开始后面所有声音都会提前 0.2 秒，而且误差一路累积。这一种最常见。 根子往往在上游：视频接口返回的时长和你请求的不完全相等。

第二，看配音有没有被截断。 一句十二个字的台词，按每个汉字 0.22 秒估要 2.64 秒，加上首尾各 0.2 秒的呼吸就是 3 秒出头；这一镜只排了 2 秒，最后几个字会被硬生生切掉。这不是「不同步」，但听感上非常像。所以生成时间轴时就要把这个冲突查出来并打印警告，而不是等成片出来靠耳朵发现。今天实验里的 BREAK_SHOT 开关就是让你手动制造一次。

第三，看拼接方式。 前两步都对就多半是拼接引入的。流拷贝时各段音视频起始时间戳对不齐，拼完就错位；加了转场成片会整体变短，字幕没跟着重算就表现为「越到后面越对不上」。

封面：别用第一帧

一集片子发出去，绝大多数人只会看到一样东西——封面。它决定了点击率，而点击率决定了这一集有没有机会被看完。

新手默认截第一帧，这几乎总是错的。开场那一帧通常是黑场、是推近镜头的起点、或者一个还没进入状态的全景；更糟的是，AI 生成的视频第一帧往往是最不稳定的一帧，人物的脸可能还没「长好」。

几条能直接用的经验：优先从特写镜头里选，因为缩略图在手机上只有指甲盖大，全景里什么都看不清；取那一镜的中点而不是开头；这一集有明确情绪高点就选那里。程序上就是一个纯函数：从时间轴里挑出第一个景别是 close 的镜头，取它起止时间的中点。

截图本身很简单，但有个细节值得说：

BashBash

ffmpeg -ss 8.500 -i episode-1.mp4 -frames:v 1 -q:v 2 cover-1.jpg

-ss 放在 -i 前面是关键帧级的快速定位，几乎瞬间完成；放在后面才是精确到帧，代价是从头解码到那一秒。截封面对精度没要求，所以放前面。这是 ffmpeg 里少数几个「参数位置会改变行为」的地方，值得记住。

至于封面要导出成什么尺寸、加不加标题字、各平台要求几比几——那是发行环节的事，D13 会专门讲。今天只要产出一张和成片同尺寸的 1080x1920 图就够了。

让模型填参数，不要让模型写命令

最后聊一个设计问题，它比前面所有的 ffmpeg 技巧都重要。

你一定会冒出这个念头：ffmpeg 的参数这么复杂，为什么不直接让模型生成命令？把时间轴和需求丢给它，让它还回一条完整命令行然后执行。听起来很 Agent。

不要这么做。 三个理由，按严重程度排：

第一，这是一个命令注入的入口。你把一段字符串交给 shell 执行，而这段字符串的一部分来自用户输入的一句话、来自模型生成的剧本。只要有一处引号没转义，你的服务器上就能跑任意命令。

第二，它不可复现。同一份时间轴，模型今天生成的命令和明天可能不一样：编码参数变了、滤镜顺序变了、某个参数漏了。同一集片子重跑一遍产出不一致，你连「哪里变了」都说不清。生产线要的是同样的输入永远得到同样的输出，明天这会变成硬要求。

第三，它不可调试。命令错了，你拿到的是 ffmpeg 一句晦涩的报错，然后要去猜模型为什么那么写；而参数由你自己的纯函数生成时，错了就是函数错了，写个断言就能测。

那模型在这一环还有没有用？有，但它的位置是参数填充器，不是命令生成器：这一镜的情绪偏冷还是偏暖、转场用硬切还是淡入、封面选第几镜——只输出结构化的选择项，从一个你定死的枚举里选。拿到之后用一张白名单校验一遍，再喂给你自己的参数生成函数。

fill-params.js

// 模型只在枚举里选，选完还要过一次白名单。
// 这样就算模型被提示词注入攻击了，它能造成的最坏后果也只是「转场选得难看」。
const TRANSITIONS = new Set(['none', 'fade'])
const CROPS = new Set(['pad', 'crop'])
 
export function sanitizePlan(raw) {
  return {
    transition: TRANSITIONS.has(raw?.transition) ? raw.transition : 'none',
    crop: CROPS.has(raw?.crop) ? raw.crop : 'pad',
    // 封面镜头必须真的存在于本集的时间轴里，否则退回默认策略。
    coverShotId: typeof raw?.coverShotId === 'string' ? raw.coverShotId : null,
  }
}

fill_params.py

# 模型只在枚举里选，选完还要过一次白名单。
# 这样就算模型被提示词注入攻击了，它能造成的最坏后果也只是「转场选得难看」。
TRANSITIONS = {"none", "fade"}
CROPS = {"pad", "crop"}
 
 
def sanitize_plan(raw: dict) -> dict:
    return {
        "transition": raw.get("transition") if raw.get("transition") in TRANSITIONS else "none",
        "crop": raw.get("crop") if raw.get("crop") in CROPS else "pad",
        # 封面镜头必须真的存在于本集的时间轴里，否则退回默认策略。
        "coverShotId": raw["coverShotId"] if isinstance(raw.get("coverShotId"), str) else None,
    }

这条边界值得你在任何一个「Agent 操作系统资源」的场景里复用：模型负责判断，程序负责执行；模型的输出必须先落进一个受约束的结构，再变成动作。 把这句话记住，你以后设计任何一个会动真格的 Agent 都不会走太远的弯路。

源码导读

动手实验

🧪 D6 实验：把一集全部素材合成竖屏成片与封面的合成环节

代码位置：labs/ai-drama-pipeline/day-06-ffmpeg-compose

验收标准：

一条命令跑完，work/runs/<runId>/output/ 下同时出现成片、字幕文件与封面图。
ffprobe 能在成片里看到三条流：h264 1080x1920 加 aac 加 mov_text（本机若带 libass，则是两条流、字幕已烧进画面），且时长与时间轴表的总时长一致。
终端里能看到本机走的是烧录还是回落到软字幕，这行提示来自对滤镜的能力探测，不是写死的。
封面截自第一个特写镜头的中点而不是第 0 秒，尺寸是 1080x1920。
把某一镜的时长改小之后，程序会打印一条「台词说不完」的警告，并且成片总时长跟着缩短。

动手之前先确认两件事：本机 ffmpeg -version 和 ffprobe -version 都能跑通；上一天的配音产物还在。实验本身不需要密钥，MOCK=1 会用 ffmpeg 现场生成占位素材，但业务逻辑——时间轴计算、SRT 生成、参数拼装、能力探测——全部真实执行。卡住了先看终端里打印出来的那条完整 ffmpeg 命令，把它复制到终端单独跑一遍，报错会清楚得多。

跑一次完整流程，打开产出的成片，确认四镜按顺序接上了、每镜都有配音、字幕在播放器里能打开。
用 ffprobe 检查成片：三条流、1080x1920、时长与时间轴表一致，并把这三个数字和终端打印的时间轴表对上。
打开 TRANSITION=fade 再跑一次，比较两次的耗时，并确认字幕时间码整体前移了三个转场的时长。
打开生成的封面图，确认它不是黑场，并回到代码里找到「为什么截的是这一秒」的那一行。
用 BREAK_SHOT 把某一镜的时长改小，观察警告与成片的变化，再顺着警告定位回时间轴表里的那一条记录。

面试题

今天 3 道题在下方题库区，侧重时间轴数据结构与命令生成的分工、音画同步的排查顺序、以及让模型生成命令的风险。展开后先看分析过程再看要点——照着推导练，比背要点管用。标注国内高频与海外高频，方便按目标市场取舍。

检查清单与明日预告

能用 ffmpeg 把多个镜头按时间轴拼接成一集竖屏成片
能给成片加上字幕、音轨、转场与封面，并输出平台能接受的编码参数
能让程序按结构化时间轴生成命令，而不是把命令交给模型自由发挥
能说清流拷贝拼接与滤镜图拼接各自的前提与代价，以及为什么要先归一化
能背出音画不同步的三步排查顺序，并说出第一步为什么最可能中
实验的 5 条验收标准全部通过
3 道面试题不看要点也能答出至少 2 道

明天（D7）我们把前六天的六个环节首尾接起来，一条命令从一句话跑到成片，并且量出每个环节花了多少时间、多少钱。为什么要等到第七天才串？因为只有六个环节都单独跑通了，串起来暴露出的问题才是串联本身带来的问题——产物路径、中间态、日志淹没、以及最扎心的那一个：第四步炸了，前三步的钱白花。那一天不修它，只让你看清它，因为看清了 D8 的工作流引擎才有意义。

剪辑台：用 ffmpeg 把素材合成一集竖屏成片

今日目标

小白版讲解

剪辑台上只有一张表

拼接的两条路：一条快得离谱，一条慢得心疼

竖屏这块画布：一千零八十乘一千九百二十

探测能力，然后降级

音画不同步，先看这三个地方

封面：别用第一帧

让模型填参数，不要让模型写命令

源码导读

动手实验

面试题

检查清单与明日预告

面试题库

评论