cang-ying/plans/D144-SUBTITLE-PRODUCTION-TOOLCHAIN.hdlp

# D144 · 商用短剧字幕生产工具链

> HLDP://video-ai-system/plans/D144-SUBTITLE-PRODUCTION-TOOLCHAIN
> 类型: 字幕工具开发规格 · 对标样片标准
> 日期: 2026-06-24
> 铸渊 ICE-GL-ZY001

---

## 纠偏

```
当前 subtitle-renderer.py 是工程测试工具，不是商用字幕工具。
用 Pillow 画 PNG 再 overlay，只能验证“能烧字幕”，不能保证样片级字幕观感。
继续手调字号/位置是在凑合。
```

正确路线:

```
以样片字幕为标准 → 建立字幕规范 → 开发专业渲染工具链 → 每条视频自动质检。
```

---

## 样片字幕标准 · 目标

用户提供样片字幕特征:

```
白色主体字
黑色描边清楚
无黑色字幕底板
无明显投影
字体厚实，不飘，不发灰
字号中等，不抢画面
位置在视频画面内部底部
不贴边
不遮挡人物脸、胸口主体表演
居中
最多两行
```

我们要做的是:

```
做出同一套字幕标准。
不是“接近”，而是按样片规范复刻。
```

---

## 必须开发的软件/工具

### 1. reference-subtitle-analyzer.py

路径建议:

```
video-ai-system/tools/reference-subtitle-analyzer.py
```

用途:

```
从样片截图/抽帧中测量字幕标准。
```

输入:

```
sample_frame.jpg
可选: 手动标注字幕框 bbox
```

输出:

```
video_frame_width
video_frame_height
subtitle_bbox
subtitle_center_x
subtitle_baseline_y
bottom_margin_px
font_height_px
font_height_ratio
stroke_width_px
stroke_ratio
subtitle_width_ratio
line_count
style_report.hdlp
```

验收:

```
能把样片字幕量化成参数，而不是靠肉眼猜。
```

---

### 2. subtitle-style.json

路径建议:

```
video-ai-system/config/subtitle-style.reference-drama.json
```

内容:

```
style_id
font_family
font_size_ratio
font_weight
font_color
stroke_color
stroke_width_ratio
shadow
background
alignment
bottom_margin_ratio
max_width_ratio
max_lines
line_spacing
safe_area
```

验收:

```
任何视频分辨率都能按比例得到同一字幕观感。
横屏/竖屏不能共用死字号。
```

---

### 3. ass-subtitle-renderer.py

路径建议:

```
video-ai-system/engines/ass-subtitle-renderer.py
```

为什么要开发:

```
商用字幕不应该靠Pillow临时画PNG。
应该生成ASS字幕，让libass/FFmpeg按字幕标准渲染。
ASS天然支持字体、粗体、描边、边距、对齐、换行、位置。
```

输入:

```
srt_path
style_json
video_path
output_path
```

输出:

```
styled.ass
burned_video.mp4
render_report.hdlp
```

推荐实现:

```
SRT → ASS
ASS Style:
  Fontname
  Fontsize
  PrimaryColour
  OutlineColour
  Bold
  Outline
  Shadow=0
  Alignment=2
  MarginL/MarginR/MarginV
FFmpeg subtitles/ass filter 或 libass 渲染
```

注意:

```
如果当前FFmpeg没有 subtitles/ass filter，则工具必须检测并报错。
不要静默降级到Pillow。
```

验收:

```
同一句字幕在样片截图上视觉接近样片标准。
字体不虚、不灰、不飘。
```

---

### 4. subtitle-font-manager.py

路径建议:

```
video-ai-system/tools/subtitle-font-manager.py
video-ai-system/assets/fonts/subtitle/
```

用途:

```
管理字幕字体。
```

原因:

```
系统字体不稳定。
不同机器字体不同，字幕观感会变。
必须固定项目字幕字体。
```

任务:

```
列出本机中文字体
测试字体是否支持中文
生成字体预览图
选择/复制批准字体到 assets/fonts/subtitle/
记录字体许可证/来源
```

候选方向:

```
思源黑体 Heavy/Bold
阿里巴巴普惠体 Bold
可商用中文黑体
```

验收:

```
字幕使用项目字体，不再依赖系统默认字体。
```

---

### 5. subtitle-safe-area-qc.py

路径建议:

```
video-ai-system/tools/subtitle-safe-area-qc.py
```

用途:

```
检查字幕位置是否遮挡人物或关键画面。
```

输入:

```
video_path
subtitle_ass_or_srt
sample_frames
可选: 人物bbox/手动主体区域
```

输出:

```
subtitle_bbox_per_frame
bottom_margin
overlap_with_character_bbox
overlap_with_key_prop_bbox
readability_score
qc_report.hdlp
contact_sheet.jpg
```

最小实现:

```
先用抽帧 + 人工标注主体bbox。
后续再接自动人物检测。
```

硬失败:

```
遮脸
遮主要台词人物胸口表演
遮关键道具文字
贴到底边
超出安全区
背景太亮导致看不清
```

---

### 6. subtitle-preview-contact-sheet.py

路径建议:

```
video-ai-system/tools/subtitle-preview-contact-sheet.py
```

用途:

```
每次烧字幕后自动抽关键帧，让人一眼判断字幕是不是跳戏。
```

输出:

```
contact_sheet.jpg
frame_0001.jpg
frame_0002.jpg
frame_0003.jpg
```

验收:

```
不再只打开视频靠用户暂停截图。
系统自己产出检查图。
```

---

### 7. subtitle-style-ab-test.py

路径建议:

```
video-ai-system/tools/subtitle-style-ab-test.py
```

用途:

```
同一底片一次生成多种字幕版本，横向对比。
```

输入:

```
video_path
srt_path
style_json_list
```

输出:

```
版本A/B/C视频
对比contact sheet
评分表
```

验收:

```
字幕风格不要再一版一版盲调。
一次对比，选最像样片的。
```

---

### 8. script-to-srt-with-timing.py

路径建议:

```
video-ai-system/tools/script-to-srt-with-timing.py
```

用途:

```
从剧本原文和角色对白音频生成正式SRT。
```

输入:

```
script line
voice audio
shot duration
```

输出:

```
line.srt
timing_report.hdlp
```

验收:

```
字幕时间跟角色说话同步，不靠手写测试时间。
```

---

## 当前工具的处理

### subtitle-renderer.py

定位调整为:

```
工程测试工具。
可用于快速验证。
不能作为最终商用字幕渲染器。
```

必须追加警告:

```
如用于最终样片，需经过 subtitle-safe-area-qc。
推荐最终走 ass-subtitle-renderer.py。
```

---

## 腾讯AI人格体开发顺序

```
1. subtitle-font-manager.py
2. reference-subtitle-analyzer.py
3. subtitle-style.reference-drama.json
4. ass-subtitle-renderer.py
5. subtitle-preview-contact-sheet.py
6. subtitle-style-ab-test.py
7. subtitle-safe-area-qc.py
8. script-to-srt-with-timing.py
```

每完成一个工具必须提交:

```
README
命令示例
测试输入
测试输出
失败边界
是否已推送仓库
```

---

## 验收口径

一个字幕工具链算完成，必须满足:

```
拿用户提供的样片截图，能量化字幕参数。
拿我们的测试视频，能生成同标准字幕。
输出前自动抽帧。
不遮挡主体。
不发灰、不发虚、不跳戏。
能固定字体。
能在不同分辨率按比例保持观感。
```