video-assembler

视频合成器

根据分镜文件中的参数，将镜头图片合成为带动画、音频、字幕的完整视频。

目录结构规范: specs/directory-structure.md

输入文件

1. 分镜文件 — 包含镜头参数

   releases/{project_id}/video/storyboard/chapter-{NNNN}.yaml
   

2. 镜头图片 — 每个镜头对应一张图（按章节分目录）

   releases/{project_id}/video/images/shots/chapter-{NNNN}/shot-{NNN}.png
   

3. 音频文件

   releases/{project_id}/tts/audio/{NNNN}.mp3
   

4. 字幕文件

   releases/{project_id}/tts/subtitles/{NNNN}.srt
   

文件命名规范

文件类型	命名格式	示例
分镜文件	chapter-{NNNN}.yaml	chapter-0001.yaml
镜头图片目录	chapter-{NNNN}/	chapter-0001/
镜头图片	shot-{NNN}.png	shot-001.png
动画片段	shot-{NNN}.mp4	shot-001.mp4
输出视频	chapter-{NNNN}.mp4	chapter-0001.mp4

说明：

• 章节号 {NNNN} 使用四位数补零
• 镜头号 {NNN} 使用三位数补零，每章从 001 开始

---

工作流程

1. 读取分镜文件
    ↓
2. 检查图片是否齐全
    ↓
3. 为每个镜头生成 Ken Burns 动画
    ↓
4. 拼接所有视频片段
    ↓
5. 添加音频
    ↓
6. 烧录字幕
    ↓
7. 输出最终视频

---

依赖检查

执行前必须检查 ffmpeg：

which ffmpeg || echo "❌ ffmpeg 未安装"

如未安装，提示用户：

• macOS: brew install ffmpeg
• Ubuntu: sudo apt install ffmpeg

---

步骤1: 读取分镜文件

从 YAML 文件中读取每个镜头的参数：

shots:
  - id: "001"
    duration: 32.5
    camera:
      type: "push_in"
      start_scale: 1.0
      end_scale: 1.3
      start_position: [0.5, 0.5]
      end_position: [0.5, 0.45]

---

步骤2: 检查图片

# 检查所有镜头图片是否存在
for shot in 001 002 003 ...; do
  [ -f "releases/{project_id}/video/images/shots/shot-${shot}.png" ] || echo "缺少 shot-${shot}.png"
done

---

步骤3: 生成 Ken Burns 动画

ffmpeg zoompan 滤镜

Ken Burns 效果通过 ffmpeg 的 zoompan 滤镜实现。

命令模板:

ffmpeg -y -loop 1 -i {input_image} \
  -vf "zoompan=z='min(max({start_scale}+{scale_delta}*(on-1),1),10)':x='(iw-iw/zoom)*({start_x}+{x_delta}*(on-1))':y='(ih-ih/zoom)*({start_y}+{y_delta}*(on-1))':d={total_frames}:s=1920x1080:fps=30" \
  -t {duration} \
  -c:v libx264 -pix_fmt yuv420p -preset medium -crf 23 \
  {output_video}