2026年6月25日

AiVedio：时间轴编译与最终渲染

从 Canonical Timeline、Semantic Validation、Timeline Compiler、Render DAG、FFmpeg Filter Graph、转场重叠语义、分片渲染、Dependency Window、断点续渲、缓存复用、Render Manifest、代理原片映射、Worker 安全边界和原子发布出发，设计可复现、可重试的最终视频渲染系统。

第16章：时间轴编译与最终渲染

本章主题：如何把浏览器中的非破坏式时间轴，编译为可校验、可重试、可分片、可复现的最终视频。

在上一章中，浏览器已经能够使用代理视频、音频主时钟和帧缓存低延迟预览多轨时间轴。但“预览能播放”并不等于“最终视频能可靠导出”。

最终渲染面对的是另一组问题：原始素材格式不统一、时间戳不从零开始、可变帧率、转场跨片段、音频尾音、字体缺失、GPU 资源有限、FFmpeg 进程异常退出，以及用户修改项目后只希望重渲染受影响的部分。

因此，生产系统不应把时间轴 JSON 直接拼成一条巨大的 FFmpeg 命令，而应先建立一层稳定的编译模型：

Editable Timeline
      ↓
Canonical Timeline
      ↓
Semantic Validation
      ↓
Timeline Compiler
      ↓
Render DAG
      ↓
Chunk Plan / Cache Plan
      ↓
Executable Render Plan
      ↓
FFmpeg / GPU Renderer
      ↓
Validation / Mux / Publish

本章完成后，你应能够回答以下问题：

为什么编辑模型和执行模型必须分离？
Canonical Timeline JSON 应保存哪些不可歧义的信息？
如何把 Clip、Track、Effect、Transition 编译成 Render DAG？
trim、setpts、overlay、xfade、amix 和 concat 分别解决什么问题？
为什么最终渲染不能简单地每 10 秒硬切？
如何计算分片的 dependency window？
如何支持断点续渲、缓存复用和取消？
如何保证代理预览与原始素材导出在语义上一致？
Render Manifest 为什么是故障排查和可复现性的核心？

16.1 最终渲染不是“一条 FFmpeg 命令”

一个最小编辑项目可能只有两个视频顺序拼接，但真实项目通常包含：

多条视频、贴图、字幕和音频轨道；
片段裁剪、变速、缩放、旋转、裁切和透明度；
入场、出场、转场和关键帧动画；
背景音乐、对白、音量包络、淡入淡出和混响；
不同分辨率、帧率、像素格式、色彩空间和声道布局；
代理素材与原始素材的替换；
长视频分片、断点续渲和局部缓存；
多种导出规格，例如横屏 4K、竖屏 1080×1920 和低码率预览版。

如果业务代码边遍历时间轴边拼接命令字符串，会很快出现以下问题：

校验和执行耦合：直到 FFmpeg 运行数分钟后才发现时间轴不合法。
语义不稳定：前端、后端和不同版本渲染器对同一字段解释不同。
无法增量渲染：任何小修改都要重新渲染整个视频。
无法可靠重试：不知道失败发生在哪个逻辑节点，也不知道哪些结果可复用。
命令不可审计：命令过长、参数转义复杂，难以定位素材与滤镜来源。
难以更换引擎：所有业务语义都绑定在 FFmpeg 参数上。

正确的工程抽象是：

时间轴是用户编辑语言，Render DAG 是渲染中间表示，FFmpeg filter graph 只是其中一种执行后端。

FFmpeg 的复杂滤镜图本身可以表达多输入、多输出的有向处理图，但业务系统仍需要在它上方建立类型、版本、校验、缓存和调度能力。[1]

16.2 Canonical Timeline：先消除一切歧义

16.2.1 可编辑 JSON 与规范化 JSON 的区别

前端为了交互方便，可能允许：

省略默认值；
使用临时本地 ID；
按用户拖动顺序保存数组；
同时保存像素坐标和百分比坐标；
使用代理素材的宽高；
以毫秒或浮点秒保存局部字段；
保留已经被覆盖但尚未清理的旧属性。

这些数据适合编辑，不适合作为渲染输入。

编译器首先应把它转换为 Canonical Timeline：字段完整、单位统一、顺序稳定、默认值展开、引用可解析、结果可哈希。

16.2.2 推荐的数据结构

下面是一个经过简化的 Canonical Timeline 示例：

{
  "schema_version": "timeline.v3",
  "project_id": "prj_01J...",
  "project_revision": 184,
  "timebase": { "num": 1, "den": 1000000 },
  "duration_us": 11000000,
  "canvas": {
    "width": 1920,
    "height": 1080,
    "pixel_aspect_ratio": "1/1",
    "background": "#000000FF",
    "working_color_space": "bt709"
  },
  "output": {
    "fps": "30/1",
    "sample_rate": 48000,
    "channel_layout": "stereo",
    "video_codec_profile": "h264-high",
    "audio_codec_profile": "aac-lc"
  },
  "assets": {
    "asset_a": {
      "object_version": "v_7f9c...",
      "checksum_sha256": "8e1d...",
      "duration_us": 9000000,
      "video": {
        "width": 3840,
        "height": 2160,
        "avg_frame_rate": "30000/1001",
        "time_base": "1/90000",
        "rotation_deg": 0,
        "pixel_format": "yuv420p",
        "color_primaries": "bt709"
      },
      "audio": {
        "sample_rate": 48000,
        "channel_layout": "stereo"
      }
    }
  },
  "tracks": [
    {
      "id": "track_v1",
      "type": "video",
      "z_index": 0,
      "clips": [
        {
          "id": "clip_1",
          "asset_id": "asset_a",
          "timeline_start_us": 0,
          "timeline_duration_us": 6000000,
          "source_in_us": 2000000,
          "source_out_us": 8000000,
          "playback_rate": "1/1",
          "transform": {
            "position_x": 960,
            "position_y": 540,
            "scale_x": "1/2",
            "scale_y": "1/2",
            "rotation_mdeg": 0,
            "anchor_x": "1/2",
            "anchor_y": "1/2"
          },
          "opacity": [{ "time_us": 0, "value": "1/1" }],
          "effects": [],
          "transition_out": {
            "type": "crossfade",
            "duration_us": 1000000,
            "version": "crossfade.v2"
          }
        }
      ]
    }
  ],
  "fonts": [
    {
      "family": "Noto Sans CJK SC",
      "weight": 400,
      "object_version": "font_2a91...",
      "checksum_sha256": "7c3b..."
    }
  ]
}

16.2.3 Canonical Timeline 的强约束

建议至少满足以下约束：

维度	约束
时间	全部使用同一有理时间基，业务层通常用整数微秒
速率	使用有理数，例如 `1001/1000`，不要只用二进制浮点数
顺序	Track、Clip、Effect、Keyframe 使用稳定排序规则
引用	每个 `asset_id`、字体、滤镜模板都能解析到不可变版本
默认值	所有默认值在规范化阶段展开
坐标	明确像素坐标、归一化坐标和锚点的定义
颜色	明确工作色彩空间、Alpha 语义和目标像素格式
文本	明确字体、字重、行高、字距、换行和 shaping 规则
版本	时间轴规范、效果、转场和渲染器均带版本
安全	不允许任意本地路径、任意 URL 或未注册滤镜表达式

Canonical Timeline 不是前端数据库表的镜像，而是编译器的稳定输入协议。

16.3 时间轴编译器的完整流水线

推荐把编译过程拆为独立阶段，每个阶段有确定输入和输出：

1. Load Snapshot
2. Resolve Assets
3. Normalize Timeline
4. Validate Semantics
5. Build Interval Model
6. Lower to Render IR
7. Build and Optimize DAG
8. Partition into Chunks
9. Resolve Cache
10. Emit Render Plan and Manifest

16.3.1 Load Snapshot：固定项目版本

用户点击导出时，不要让 Worker 直接读取“当前项目”。应先创建不可变快照：

render_request
- render_id
- project_id
- project_revision
- timeline_snapshot_object
- output_profile
- requested_by
- created_at

即使用户继续编辑，当前导出仍然绑定 project_revision=184，不会渲染到一半混入第 185 版数据。

16.3.2 Resolve Assets：解析到不可变对象

asset_id 不能只解析到一个可变对象键。编译时应固定：

对象存储版本号；
checksum；
原始素材或指定母版；
ffprobe 元数据；
旋转、像素宽高比和色彩信息；
音频流索引；
是否存在可解码代理。

若素材仍在上传、转码或审核中，编译应直接失败为可解释的业务错误，而不是进入渲染后才失败。

16.3.3 Normalize Timeline：展开默认值

规范化阶段负责：

将所有时间转换为统一时间基；
将默认透明度、音量和变换显式写出；
将百分比位置转换为画布坐标；
对关键帧排序并消除重复时间点；
将颜色转成统一表示；
将转场转换为明确重叠区间；
将空轨道和不可见节点按规则移除；
为未指定的音频声道布局补充明确值；
对 JSON 做稳定字段顺序和稳定数组顺序处理。

16.3.4 Validate Semantics：在昂贵执行前失败

编译器应提前拒绝：

source_in_us >= source_out_us；
源区间超过素材时长；
timeline_duration 与源区间、播放速率不一致；
同一主视频轨出现不允许的重叠；
转场时长大于任一侧可用片段；
关键帧时间不在 Clip 内；
字体版本不存在；
输出尺寸、帧率或编码配置不受支持；
HDR 素材被放入 SDR 项目但没有明确 tone mapping 策略；
效果依赖 GPU，但目标资源池不支持；
效果版本已下线且没有兼容实现；
资产审核状态不允许导出。

错误应带结构化路径：

{
  "code": "TRANSITION_HANDLE_TOO_SHORT",
  "path": "tracks[0].clips[3].transition_out",
  "clip_id": "clip_4",
  "required_us": 1000000,
  "available_us": 420000
}

这比向用户返回一整段 FFmpeg stderr 更有价值。

16.4 时间模型：PTS、时间基与变速

16.4.1 不要把“第几帧”当成唯一事实

输入视频可能是可变帧率，帧间隔并不固定。时间轴应以逻辑时间为事实源，帧号只是特定输出帧率下的派生结果。

输出帧时间可按下式计算：

frame_time(n) = n × fps_den / fps_num

但源素材采样应依据时间戳，而不是假设“第 300 帧一定是第 10 秒”。

16.4.2 Clip 的时间映射

设：

时间轴时间为 T；
Clip 起点为 S；
源素材入点为 I；
播放速率为 R。

则源时间为：

sourceTime(T) = I + (T - S) × R

如果播放速率为 2/1，时间轴播放 1 秒，源素材前进 2 秒；如果为 1/2，时间轴播放 1 秒，源素材只前进 0.5 秒。

Clip 的时间轴时长为：

timelineDuration = (sourceOut - sourceIn) / playbackRate

生产实现中应使用整数或有理数计算，并定义统一舍入规则，例如“向最近输出帧边界舍入，半值向偶数舍入”。前后端必须共享该规则。

16.4.3 `trim` 之后为什么还要 `setpts`

FFmpeg 的 trim 和 atrim 只选择需要保留的帧或采样，并不会自动把输出时间戳重置为零。因此，裁剪后的独立片段通常还要接：

trim=start=2:end=8,setpts=PTS-STARTPTS
atrim=start=2:end=8,asetpts=PTS-STARTPTS

否则多个片段进入 overlay、concat 或转场滤镜时，时间轴可能从原始 PTS 开始，导致空白、延迟或不同步。[2]

16.4.4 变速的音视频处理不同

视频变速通常通过调整时间戳：

setpts=PTS/2        # 2 倍速
setpts=PTS*2        # 0.5 倍速

音频不能只改 PTS，还需要时间伸缩。常见策略是：

在 atempo 支持范围内串联多个 atempo；
对音质要求更高时使用专门的 time-stretch 引擎；
将变速算法及其版本写入 Render Manifest。

视频和音频必须使用同一个逻辑速率来源，不能由两套代码分别近似。

16.5 Render DAG：把编辑语义降级为执行语义

16.5.1 为什么是 DAG

一条 Clip 可能经过：

Input
  → Decode
  → Trim
  → Retime
  → Crop
  → Scale
  → Color Convert
  → Effect Chain
  → Composite

同一素材可能被多个 Clip 复用；同一中间结果也可能同时用于预览图、主画面和转场。DAG 可以表达共享依赖，而线性命令列表不能。

16.5.2 建议的节点类型

InputAsset
DecodeVideo / DecodeAudio
TrimVideo / TrimAudio
RetimeVideo / TimeStretchAudio
Scale / Crop / Rotate / ColorConvert
EffectVideo / EffectAudio
GenerateText / GenerateShape
TransitionVideo / TransitionAudio
CompositeVideo
MixAudio
NormalizeAudio
EncodeVideo / EncodeAudio
Mux
ValidateOutput
PublishArtifact

每个节点至少包含：

node_id
node_type
input_edges
normalized_parameters
output_stream_type
resource_class
cache_policy
engine_version

16.5.3 一个简化 DAG

asset_a ─ decode ─ trim ─ scale ─┐
                                  ├─ xfade ─ composite_text ─ encode_video ─┐
asset_b ─ decode ─ trim ─ scale ─┘                                        │
                                                                           ├─ mux
asset_a ─ audio ─ atrim ─ gain ─┐                                         │
                                 ├─ acrossfade ─ mix_bgm ─ encode_audio ────┘
asset_b ─ audio ─ atrim ─ gain ─┘

16.5.4 节点哈希与缓存键

节点缓存键不能只包含“项目 ID + 节点 ID”。推荐：

node_hash = SHA256(
  node_type
  + canonical_parameters
  + ordered_upstream_hashes
  + asset_checksums
  + font_checksums
  + effect_versions
  + renderer_image_digest
  + output_working_format
)

这样，只有真正影响结果的输入变化才会使缓存失效。

需要注意：

含随机性的效果只有在 seed 固定时才可安全缓存；
依赖系统字体、系统时区或未固定 GPU 实现的节点不具备强可复现性；
缓存元数据必须包含租户和权限边界，避免跨租户泄漏私有素材；
缓存命中前应校验对象存在、checksum 和编码参数。

16.6 从 Render DAG 生成 FFmpeg Filter Graph

FFmpeg 的 -filter_complex 适合描述多输入、多输出滤镜图；overlay 是典型双视频输入节点，amix 是典型多音频输入节点。[1]

16.6.1 片段裁剪与规格统一

两个素材进入转场前，通常先统一：

分辨率；
帧率；
像素格式；
时间基；
声音采样率；
声道布局。

示例：

ffmpeg \
  -i clip-a.mp4 \
  -i clip-b.mp4 \
  -filter_complex "
    [0:v]trim=start=2:end=8,setpts=PTS-STARTPTS,
         scale=1920:1080:force_original_aspect_ratio=decrease,
         pad=1920:1080:(ow-iw)/2:(oh-ih)/2,
         fps=30,settb=AVTB,format=yuv420p[v0];
    [1:v]trim=start=1:end=7,setpts=PTS-STARTPTS,
         scale=1920:1080:force_original_aspect_ratio=decrease,
         pad=1920:1080:(ow-iw)/2:(oh-ih)/2,
         fps=30,settb=AVTB,format=yuv420p[v1];
    [v0][v1]xfade=transition=fade:duration=1:offset=5[v];

    [0:a]atrim=start=2:end=8,asetpts=PTS-STARTPTS,
         aresample=48000[a0];
    [1:a]atrim=start=1:end=7,asetpts=PTS-STARTPTS,
         aresample=48000[a1];
    [a0][a1]acrossfade=d=1[a]
  " \
  -map "[v]" -map "[a]" \
  -c:v libx264 -pix_fmt yuv420p \
  -c:a aac -ar 48000 \
  output.mp4

这里第一个片段长度为 6 秒，转场从第 5 秒开始并持续 1 秒。xfade 要求两路输入具有相同分辨率、像素格式、帧率和时间基，因此编译器必须在生成该节点前完成统一化。[3]

上述命令用于解释编译结果。生产系统应使用参数数组调用 FFmpeg，不应把用户内容拼入 Shell 字符串。

16.6.2 Overlay：图层合成

贴图、画中画和文本光栅层通常会被编译成 overlay：

[base][overlay]overlay=x=main_w-overlay_w-40:y=40

如果叠加层在时间轴第 3 秒开始，应先让其时间戳偏移：

[1:v]trim=start=0:end=4,
     setpts=PTS-STARTPTS+3/TB,
     scale=480:-2[ov];
[0:v][ov]overlay=x=W-w-40:y=40:eof_action=pass[outv]

编译器必须明确：

坐标是基于输出画布还是源素材；
anchor 如何影响位置；
Alpha 是 straight 还是 premultiplied；
图层结束后主画面是否继续；
旋转和缩放的执行顺序。

操作顺序不同会产生不同像素结果，因此必须写入规范，而不能由不同客户端自行决定。

16.6.3 Concat：顺序拼接

当片段已被转成同一规格并重置时间戳，可以使用 concat filter。若使用 concat demuxer 做无重编码拼接，则各文件需要具有相同流结构、编码、时间基等条件；各段时长不准确还可能造成时间戳间隙。[4]

工程上常见两种策略：

策略	适用场景	特点
concat filter	输入需要裁剪、缩放、转码或音视频分别处理	灵活，但需要解码和重新编码
concat demuxer	已生成完全同规格的中间分片	可做流复制，速度快，但约束严格

长视频分片渲染通常先把每个 Chunk 编码为统一的中间格式，再由 concat demuxer 合并。

16.6.4 Audio Mix：不要只做简单相加

amix 可以把多路音频混为一路，并支持 duration、weights 和 normalize 等参数。其内部使用浮点采样；若输入是整数采样，FFmpeg 会插入重采样转换。[5]

时间轴音频编译通常需要：

Trim
→ Reset PTS
→ Time Stretch
→ Channel Layout Convert
→ Resample
→ Gain Envelope
→ Fade / Ducking
→ Delay to Timeline Position
→ Mix
→ Limiter / Loudness Stage

例如对白和背景音乐：

[dialog]volume=1.0[d];
[music]volume=0.22[m];
[d][m]amix=inputs=2:duration=longest:normalize=0,
      alimiter=limit=0.95[aout]

是否启用自动归一化必须显式决定，不能依赖 FFmpeg 默认值；否则升级版本或修改输入数量后，音量可能发生非预期变化。

16.6.5 字幕与字体

字幕可以先编译为 ASS，再使用 subtitles 滤镜烧录。该滤镜依赖 libass，生产镜像需要明确启用相应构建能力；fontsdir 可提供项目绑定的字体目录。[6]

subtitles=filename=subtitle.ass:fontsdir=/render/fonts

字体必须版本化，因为同一个 family name 在不同系统中可能解析到不同文件。Render Manifest 应记录：

font family
font weight
font file checksum
libass version
text shaping mode
fallback font chain

仅记录“微软雅黑”或“Noto Sans”不足以复现排版结果。

16.7 转场不是装饰，而是时间轴重叠语义

16.7.1 转场会改变序列时长

设片段 A 时长为 6 秒，片段 B 时长为 6 秒，转场为 1 秒，则序列总时长不是 12 秒，而是：

6 + 6 - 1 = 11 秒

多个片段时：

sequenceDuration
= Σ clipDuration
- Σ transitionOverlap

因此转场必须在 Canonical Timeline 中表现为明确的重叠区间，而不是一个只供 UI 展示的标签。

16.7.2 Handle 校验

假设 A 的转场需要其切点之后仍有 1 秒可用源画面，B 的转场需要其切点之前仍有 1 秒可用源画面。若 A 已经裁到源文件最后一帧，或 B 恰好从源文件第一帧开始，可用 handle 就可能不足。编译器必须在执行前完成校验。

常见策略：

严格模式：handle 不足则拒绝导出；
缩短模式：自动把转场缩短到可用长度；
冻结帧模式：不足部分使用首帧或尾帧延展；
透明补齐模式：适用于叠加轨，不适用于主叙事轨。

选择哪种策略必须是产品规则，不应由底层 Worker 临时决定。

16.7.3 视频转场和音频转场应分开定义

画面 crossfade 不代表音频一定使用相同曲线。一个专业时间轴可分别定义：

video_transition:
  type: dissolve
  duration: 1s
  curve: linear

audio_transition:
  type: equal_power_crossfade
  duration: 600ms

编译器应分别生成视频和音频节点，再在输出时对齐总时长。

16.8 分片渲染与 Dependency Window

16.8.1 为什么不能固定每 10 秒硬切

假设在第 10 秒切分，但第 9.5～10.5 秒存在 1 秒转场。若两个 Chunk 各自只读取自己的输出范围：

前一段缺少转场后半部分；
后一段缺少转场前半部分；
合并处会出现跳变或黑帧。

类似问题还包括：

帧间去噪需要前后帧；
光流补帧需要相邻帧；
运动模糊需要采样窗口；
音频混响和延迟有尾音；
字幕动画跨越边界；
关键帧插值区间跨越边界。

16.8.2 核心区间与读取区间

对输出 Chunk：

core interval = [S, E)

根据依赖向前、向后扩展：

read interval = [S - lookbehind, E + lookahead)

渲染完整读取区间后，只保留核心区间：

render expanded interval
→ trim to [S, E)
→ encode chunk artifact

例如：

core:        [20s, 30s)
lookbehind:  1.2s
lookahead:   0.8s
read:        [18.8s, 30.8s)

16.8.3 依赖窗口如何计算

每种节点声明自己的时间依赖：

CrossFade(1s):       before=1s, after=1s
TemporalDenoise:     before=4 frames, after=4 frames
MotionBlur:          before=shutter/2, after=shutter/2
AudioReverb:         before=0, after=tail_duration
StaticColorAdjust:   before=0, after=0

编译器沿 DAG 反向传播依赖，得到 Chunk 的最大读取范围。

如果某个效果具有无限历史依赖，或实现不支持状态快照，则应：

将其所在区间标记为不可切分；
扩大为一个原子渲染区；
或切换到支持状态序列化的渲染实现。

16.8.4 Chunk 边界选择

边界不应只按固定时长决定，可综合：

Clip 起止点；
转场边界；
字幕段落边界；
场景复杂度；
关键帧位置；
GPU 显存估算；
中间文件目标大小；
不可切分效果区间。

常见做法是先生成候选边界，再通过代价函数寻找近似均衡分片：

cost(chunk)
= decoded_pixels
+ effect_complexity
+ audio_complexity
+ dependency_overlap_cost

16.8.5 合并分片

若最终使用无重编码合并，所有 Chunk 必须统一：

编解码器与 profile；
分辨率、帧率和像素格式；
time base；
音频采样率和声道布局；
编码参数和封装约束。

FFmpeg segment muxer 的精确切点依赖关键帧；若切点没有对应关键帧，分段可能从后续关键帧开始。因此，生产系统通常在中间编码阶段控制关键帧位置，或由自己的 Chunk 计划直接生成独立文件。[7]

16.9 断点续渲：把渲染当成可恢复工作流

16.9.1 状态模型

RenderJob
- CREATED
- COMPILING
- READY
- RUNNING
- FINALIZING
- SUCCEEDED
- FAILED
- CANCEL_REQUESTED
- CANCELED

每个 Chunk 独立记录：

RenderChunk
- chunk_id
- render_id
- core_start_us
- core_end_us
- read_start_us
- read_end_us
- dag_subgraph_hash
- cache_key
- attempt
- status
- worker_id
- output_object_version
- output_checksum
- started_at
- heartbeat_at
- finished_at
- error_code

16.9.2 幂等执行

Worker 处理 Chunk 时应遵循：

读取 Chunk 状态和期望 cache key；
检查目标对象是否已存在且 checksum 正确；
使用唯一执行租约抢占任务；
输出到临时对象键；
ffprobe 校验结果；
原子发布为正式对象版本；
以 CAS 更新数据库状态；
重复消息到达时直接返回已完成结果。

不要把“FFmpeg 退出码为 0”当成唯一成功条件。还需要验证输出对象、媒体流和时间长度。

16.9.3 重试分类

错误	是否重试	处理方式
Worker 被驱逐、节点重启	是	换节点继续
对象存储临时 5xx	是	指数退避
GPU 暂时无槽位	是	延迟调度
FFmpeg 进程被 OOM Kill	有条件	降低并发或换大规格节点
素材损坏、无法解码	否	标记资产错误
字体缺失	否	编译或预检阶段失败
时间轴语义非法	否	返回结构化业务错误
特定硬件编码器异常	有条件	降级到软件编码或其他节点池

16.9.4 进度计算

按 Chunk 数量平均计算进度通常不准确。一个 10 秒 4K 多效果 Chunk 可能比 30 秒纯拼接 Chunk 更慢。

推荐使用编译阶段估算的工作量权重：

progress
= Σ(completed_node_weight)
  / Σ(all_node_weight)

运行 FFmpeg 时可通过 -progress 获取面向程序的 key=value 进度输出，stderr 则保留用于日志和错误诊断。[8]

16.10 缓存复用与增量渲染

16.10.1 三层缓存

缓存层	示例	生命周期
资产派生缓存	解码索引、规范化音频、代理、色彩转换母版	较长
DAG 节点缓存	某 Clip 裁剪、缩放和滤镜后的中间结果	中等
Chunk 缓存	20～30 秒最终工作格式分片	与项目版本和渲染器版本绑定

16.10.2 修改影响范围

用户只修改第 42 秒字幕时：

素材解码缓存不变；
0～40 秒 Chunk 不变；
字幕节点及其下游 composite 节点失效；
如果字幕动画只影响 40～45 秒，则仅对应 Chunk 需要重渲染；
最终 concat 和 mux 需要重新执行，但成本远低于全量渲染。

16.10.3 缓存失效的常见遗漏

以下变化都可能改变像素结果：

字体文件升级；
FFmpeg 或 libass 版本升级；
GPU 驱动或硬件滤镜实现变化；
色彩转换矩阵变化；
默认滤镜参数变化；
代理到原片的映射规则变化；
输出 fps 或 pixel format 变化；
时间舍入规则变化。

因此缓存键必须包含渲染环境版本，而不能只包含时间轴 JSON。

16.11 Render Manifest：让每次导出可解释、可复现

每次导出都应生成不可变 render_manifest.json：

{
  "render_id": "rnd_01J...",
  "project_id": "prj_01J...",
  "project_revision": 184,
  "timeline_schema_version": "timeline.v3",
  "timeline_snapshot_sha256": "e1b4...",
  "compiler_version": "[email protected]",
  "renderer": {
    "image_digest": "sha256:9d7a...",
    "ffmpeg_build_id": "ffmpeg-custom-2026.06.14",
    "effect_bundle_version": "effects@14",
    "transition_bundle_version": "transitions@8"
  },
  "assets": [
    {
      "asset_id": "asset_a",
      "object_version": "v_7f9c...",
      "checksum_sha256": "8e1d...",
      "selected_video_stream": 0,
      "selected_audio_stream": 1
    }
  ],
  "fonts": [
    {
      "family": "Noto Sans CJK SC",
      "checksum_sha256": "7c3b..."
    }
  ],
  "output": {
    "width": 1920,
    "height": 1080,
    "fps": "30/1",
    "video_codec": "h264",
    "pixel_format": "yuv420p",
    "sample_rate": 48000,
    "channel_layout": "stereo"
  },
  "dag_hash": "6dd2...",
  "chunks": [
    {
      "chunk_id": "c0001",
      "core": [0, 10000000],
      "read": [0, 11000000],
      "subgraph_hash": "73af...",
      "output_checksum": "2b91..."
    }
  ]
}

Manifest 不应保存：

长期密钥；
临时签名 URL；
Worker 本地绝对路径；
可变的“latest”镜像标签；
未脱敏的用户隐私字段。

Manifest 的价值包括：

回答“这个视频到底用哪版素材渲染的”；
对比两次导出的环境差异；
复现字体或转场问题；
确认缓存是否错误复用；
进行计费、审计和质量回归。

16.12 代理素材替换为原始素材

预览通常使用低分辨率、短 GOP、固定帧率代理；最终导出必须使用原始素材或高质量母版。

替换不能只把文件路径从 proxy.mp4 改成 original.mov，因为两者可能存在：

不同分辨率；
不同裁切区域；
旋转元数据已烘焙或未烘焙；
不同帧率；
不同起始 PTS；
不同音频延迟；
HDR 与 SDR 差异；
代理生成时插入或丢弃的帧。

16.12.1 使用逻辑媒体时间，而不是代理帧号

Clip 应保存：

source_in_us
source_out_us

而不是：

proxy_start_frame
proxy_end_frame

编译器根据逻辑时间分别映射到代理和原片。

16.12.2 保存代理映射元数据

ProxyMapping
- source_asset_checksum
- proxy_asset_checksum
- source_timebase
- proxy_timebase
- source_start_time
- proxy_start_time
- rotation_baked
- crop_baked
- color_transform
- audio_offset_us

如果代理做过裁切或旋转，前端坐标必须能反向映射到原始画面。

16.12.3 导出前预检原片

在正式渲染前完成：

原片对象存在性检查；
checksum 校验；
ffprobe 流信息解析；
选定音视频流可解码性验证；
source 区间越界检查；
色彩和旋转映射检查。

ffprobe 可以按 JSON 输出容器和流信息，适合生成稳定的资产元数据。[9]

16.13 保证预览和最终结果一致

“完全像素一致”在浏览器 GPU 预览与服务端 FFmpeg 之间通常成本很高，但必须做到 语义一致：同一时间点应看到同一素材、同一构图、同一字幕和同一动画阶段。

16.13.1 共享时间轴规范

前端和服务端必须共享：

时间单位；
Clip 时间映射；
关键帧插值；
easing 函数；
变换顺序；
anchor 定义；
转场占用时长；
字幕换行规则；
混合模式；
Alpha 语义；
颜色解释；
边界时刻采用左闭右开还是其他规则。

推荐所有区间统一使用：

[start, end)

这样相邻片段在同一时刻不会同时被选中。

16.13.2 版本化执行语义

Timeline Spec: timeline.v3
Transform Semantics: transform.v2
Text Layout: text-layout.v4
Crossfade: crossfade.v2
Renderer: renderer.2026.06

旧项目继续使用旧语义，或在显式迁移后升级。不要直接修改同名效果的默认行为。

16.13.3 Conformance Test

建立一组标准时间轴：

1 帧 Clip；
VFR 素材；
29.97 fps；
0.5 倍速和 2 倍速；
旋转加非中心 anchor；
多层 Alpha；
中英文混排和字体回退；
转场跨分片；
音频延迟与淡入淡出。

对每个测试向量，在指定时间点截取：

preview frame
server render frame
expected logical state

图像可使用像素差或感知差异阈值；音频则检查采样位置、峰值和总时长。重点是让偏差可测，而不是靠人工观看。

16.14 渲染 Worker 的资源与安全边界

16.14.1 FFmpeg 应运行在受限 Worker 中

不要在普通 Go API 进程中直接无限启动 FFmpeg。建议：

独立渲染 Worker 池；
CPU、内存、GPU、PID 和临时盘配额；
每种输出规格定义资源类；
有界并发和任务队列；
进程组级取消；
硬超时和无进度超时；
Worker 心跳与租约；
临时目录隔离；
完成后清理本地素材。

16.14.2 不要把任意 URL 交给 FFmpeg

FFmpeg 支持多种协议，若直接接收用户 URL，可能形成 SSRF、内网访问或协议滥用。

正确做法：

业务侧只接受 asset_id；
受控下载服务解析并校验来源；
素材进入平台对象存储；
Worker 只读取受信任挂载或内部对象地址；
限制允许的输入协议；
不允许用户提供任意 filter expression、文件路径和字体目录。

16.14.3 使用参数数组，不使用 Shell 拼接

Go 示例：

cmd := exec.CommandContext(ctx, ffmpegPath,
    "-nostdin",
    "-hide_banner",
    "-progress", "pipe:1",
    "-i", inputA,
    "-i", inputB,
    "-filter_complex", filterGraph,
    "-map", "[vout]",
    "-map", "[aout]",
    "-c:v", "libx264",
    "-c:a", "aac",
    tempOutput,
)

进一步应做到：

inputA 和 inputB 来自受控解析，不来自用户原始字符串；
filterGraph 由类型化编译器生成；
stdout 只解析 progress；
stderr 按大小截断并上传日志；
取消时终止整个进程组；
输出写临时文件，校验后再发布。

16.15 Go 中的编译器接口设计

16.15.1 核心接口

type TimelineCompiler interface {
    Compile(
        ctx context.Context,
        snapshot TimelineSnapshot,
        assets map[string]ResolvedAsset,
        profile OutputProfile,
    ) (*RenderPlan, error)
}

type RenderPlan struct {
    RenderID       string
    Revision       int64
    DurationUS     int64
    DAG            RenderDAG
    Chunks         []RenderChunkPlan
    Finalize       FinalizePlan
    Manifest       RenderManifest
    EstimatedCost  ResourceEstimate
}

type RenderNode struct {
    ID             string
    Type           NodeType
    Inputs         []string
    Params         json.RawMessage
    ResourceClass  string
    CacheKey       string
    Cacheable      bool
    EngineVersion  string
}

16.15.2 编译阶段错误分类

type CompileError struct {
    Code       string
    Path       string
    Message    string
    Retryable  bool
    Details    map[string]any
}

错误码示例：

ASSET_NOT_READY
ASSET_STREAM_NOT_FOUND
SOURCE_RANGE_OUT_OF_BOUNDS
TIMELINE_OVERLAP_INVALID
TRANSITION_HANDLE_TOO_SHORT
FONT_VERSION_MISSING
EFFECT_VERSION_UNSUPPORTED
OUTPUT_PROFILE_UNSUPPORTED
COLOR_PIPELINE_UNDEFINED

16.15.3 不要让编译器产生随机 ID

稳定输入应产生稳定 DAG。节点 ID 可由逻辑路径和哈希生成：

video/track_v1/clip_1/trim@73af2d

这样有利于：

对比两次编译结果；
缓存命中；
日志关联；
单元测试；
故障定位。

16.16 最终输出校验与发布

16.16.1 校验清单

FFmpeg 成功退出后，至少检查：

输出文件存在且大小大于最小阈值；
容器可被 ffprobe 打开；
视频流和音频流符合期望；
宽高、帧率、像素格式、采样率和声道布局正确；
总时长在允许误差内；
首尾 PTS 合法；
解码抽检无致命错误；
文件 checksum 已计算；
快速起播所需的 MP4 元数据布局符合产品要求；
内容审核和水印策略已完成；
对象存储上传成功且可读取。

时长误差不应使用固定“允许 1 秒”。更合理的容差是：

video tolerance ≤ 1 output frame
 audio tolerance ≤ 若干 samples 或一个编码帧边界

具体值取决于编码器和封装格式，但必须在输出规格中明确。

16.16.2 原子发布

render/tmp/{render_id}/{attempt}.mp4
        ↓ 校验通过
render/final/{render_id}/{checksum}.mp4
        ↓ 数据库 CAS
RenderJob = SUCCEEDED

用户只能看到 final 对象。失败的临时对象由生命周期策略清理。

16.16.3 发布后的派生任务

最终成品可继续触发：

CDN 预热；
封面图；
低码率分享版；
HLS/CMAF；
字幕旁路文件；
媒体指纹；
内容复审；
成本结算与账单落账。

这些任务不应阻塞“主成品已经可下载”的状态，除非产品明确要求。

16.17 常见故障场景推演

场景	错误做法	正确处理
用户导出后继续编辑	Worker 读取最新项目	导出绑定不可变 revision
转场跨 Chunk	固定 10 秒硬切	dependency window 扩展读取
`trim` 后片段延迟	只使用 `trim`	接 `setpts/asetpts` 重置 PTS
两路 `xfade` 报错	直接连接不同规格素材	先统一 CFR、尺寸、格式和 time base
字幕线上字体变化	使用系统字体	字体文件 checksum 和版本绑定
小改动全量重渲	缓存键绑定整个项目	DAG 节点和 Chunk 级缓存
Worker 重启丢进度	进度仅存在内存	Chunk 状态、租约和对象结果持久化
重复 MQ 消息重复计费	每次执行都记账	render/chunk 幂等键和唯一约束
FFmpeg 退出码 0 但文件异常	直接标记成功	ffprobe、时长、流和 checksum 校验
用户 URL 传给 FFmpeg	直接 `-i https://...`	受控回源并限制协议
代理画面与原片偏移	按代理帧号裁剪	使用逻辑时间和 ProxyMapping
升级渲染镜像后缓存污染	缓存键不含环境版本	包含镜像 digest、字体和效果版本

16.18 面试高频问题与参考回答

问题 1：为什么不能直接把时间轴 JSON 拼成 FFmpeg 命令？

因为时间轴是编辑模型，FFmpeg 是执行模型。中间需要 Canonical Timeline 和 Render DAG 完成规范化、语义校验、依赖分析、分片、缓存、版本化和资源调度。直接拼命令会把业务语义、执行细节和失败处理耦合在一起。

问题 2：为什么 `trim` 后经常要接 `setpts`？

trim 只筛选帧，不会把时间戳自动归零。独立片段进入 concat、overlay 或转场前通常要使用 setpts=PTS-STARTPTS；音频对应 asetpts。

问题 3：转场为什么会影响总时长？

转场本质是两个片段在时间轴上的重叠。1 秒转场会让两个片段重叠 1 秒，因此总时长要减去重叠长度。

问题 4：为什么不能固定每 10 秒分片？

转场、时域滤镜、运动模糊、混响和动画可能跨越边界。分片必须根据节点依赖计算 lookbehind 和 lookahead，并在扩展范围渲染后裁回核心区间。

问题 5：如何支持只重渲染修改过的部分？

把时间轴编译成 DAG，为节点和 Chunk 生成内容寻址缓存键。修改只会使受影响节点及其下游失效，未受影响的中间结果和 Chunk 可复用。

问题 6：如何保证预览与最终导出一致？

共享同一时间轴规范、时间舍入规则、关键帧插值、变换顺序、字体版本和效果版本；建立 conformance test，在固定时间点比较浏览器预览和服务端渲染结果。

问题 7：Render Manifest 记录什么？

记录项目 revision、时间轴快照哈希、资产对象版本和 checksum、字体与效果版本、编译器和渲染器版本、输出规格、DAG 哈希以及 Chunk 结果。它用于复现、审计和故障定位。

问题 8：FFmpeg Worker 如何保证安全？

不接收任意 URL、路径和滤镜表达式；只使用受控资产和类型化编译结果；以参数数组启动进程；限制协议、CPU、内存、GPU、PID、临时盘和运行时间；隔离临时目录并控制并发。

问题 9：Chunk 已经成功，但数据库更新失败怎么办？

结果先写临时对象，校验后发布为带 checksum 的不可变对象。数据库更新使用幂等键和 CAS。消息重投时先检查对象和 Chunk 状态，若结果已存在则补写状态而不是重新渲染。

问题 10：如何处理代理与原片帧率不同？

时间轴保存逻辑媒体时间，不保存代理帧号。编译器根据 ProxyMapping 和各自 time base 将同一 source time 映射到代理或原片，并通过统一舍入规则选帧。

问题 11：为什么 concat demuxer 不是任何场景都能直接用？

它适合流结构、编码和 time base 一致的文件。源片段若需要裁剪、缩放、转场或具有不同规格，通常需要先重新编码为统一 Chunk，再无重编码合并。

问题 12：如何计算渲染进度？

不要平均按 Chunk 个数计算，而应根据分辨率、帧数、滤镜复杂度和编码成本为节点估算权重，再汇总已完成权重；运行中结合 FFmpeg -progress 更新局部进度。

16.19 实战任务

任务一：实现最小 Timeline Compiler

输入：

两个视频 Clip；
1 秒 crossfade；
一条背景音乐；
一段 2～5 秒显示的字幕；
输出 1920×1080、30 fps、48 kHz stereo。

要求输出：

Canonical Timeline JSON；
语义校验结果；
Render DAG；
稳定节点哈希；
FFmpeg 参数数组；
Render Manifest；
输出校验报告。

验收条件：

trim 后正确重置 PTS；
两个视频在转场前规格一致；
序列总时长正确减去转场重叠；
背景音乐按时间轴位置延迟并混音；
字体来自受控目录；
相同输入重复编译得到相同 DAG 哈希；
修改字幕只使相关节点及下游哈希变化。

任务二：增加分片与断点续渲

把 60 秒时间轴分为多个 Chunk，并实现：

dependency window；
Chunk 状态表；
Worker 租约和心跳；
临时对象与原子发布；
重复消息幂等；
失败 Chunk 单独重试；
最终 concat 和 mux；
取消后停止领取新 Chunk，并终止正在执行的进程。

任务三：建立一致性测试集

准备包含以下情况的时间轴：

29.97 fps；
VFR 手机视频；
旋转元数据；
半速播放；
中文、英文和 emoji 混排；
转场跨 Chunk；
音频淡入淡出；
代理与原片分辨率不同。

在关键时间点保存浏览器预览截图和服务端渲染帧，并生成自动差异报告。

16.20 本章关键总结

最终渲染应被设计成一条可恢复媒体工作流，而不是一次同步命令执行。
前端可编辑时间轴必须先转换为字段完整、单位统一、版本固定的 Canonical Timeline。
Timeline Compiler 负责规范化、语义校验、时间映射、DAG 构建、分片和缓存规划。
trim/atrim 选择区间，setpts/asetpts 重置时间戳，overlay 合成图层，xfade/acrossfade 表达转场，amix 处理混音，concat 负责顺序拼接。
转场会形成时间重叠并改变总时长，必须检查两侧素材 handle。
分片渲染必须计算 dependency window；固定时长硬切无法正确处理跨边界依赖。
DAG 哈希、Chunk 缓存和不可变资产版本共同支持增量渲染。
每次导出都应生成 Render Manifest，记录项目、资产、字体、效果、引擎和输出参数。
预览与最终导出的一致性依赖共享规范、版本化语义和自动化 conformance test。
FFmpeg 必须运行在受限 Worker 中，并在退出后执行媒体校验和原子发布。

一句话概括本章：

先把时间轴编译成确定、可验证的 Render DAG，再把 DAG 调度成可分片、可重试、可复现的媒体执行计划。

16.21 下一章预告

下一章将进入 高性能与容量规划，重点讨论：

控制面与数据面分离；
Little’s Law 与在途任务估算；
PostgreSQL、Redis、RocketMQ 和对象存储的容量瓶颈；
HTTP 与数据库连接池；
FFmpeg CPU/GPU 槽位；
有界队列与背压；
p50、p95、p99；
一套完整的 AI 视频平台容量计算案例。

参考依据

本章中的 FFmpeg 行为边界参考其官方文档：

FFmpeg Documentation：complex filtergraph 与 -filter_complex。
FFmpeg Filters Documentation：trim、atrim、setpts、asetpts。
FFmpeg Filters Documentation：xfade 输入约束与转场参数。
FFmpeg Formats Documentation：concat demuxer 的流一致性和时间戳规则。
FFmpeg Filters Documentation：amix 的输入、duration、weights 与 normalize。
FFmpeg Filters Documentation：subtitles、libass 与 fontsdir。
FFmpeg Formats Documentation：segment muxer 与关键帧切分约束。
FFmpeg Documentation：-progress 的机器可读输出。
ffprobe Documentation：流、容器信息及 JSON 输出。