

## 一、背景：为什么要在本地跑

我做的是工业设备讲解类短视频，素材来自车间实拍，每期 1~2 分钟。这类视频有两个硬约束：

1. 必须上硬字幕。短视频平台大量用户静音刷，没字幕等于没看。
2. 术语密度极高。一期口播里"吹塑机""型坯""锁模力""壁厚控制"能出现几十次，随便错一个字，专业观众立刻划走。

九月份有一次，常用那款剪辑 App 的字幕识别额度用完了，手上那条片子当天就要发。急着找替代方案，我索性想：能不能不依赖任何平台，在自己机器上把字幕加上？路子就是本地跑 Whisper 识别，再用 ffmpeg 把字幕烧进画面。这就是后来这套流水线的起点。

在那之前我也试过云端的语音识别接口，三个问题劝退：

- **按分钟计费**，素材是批量产出，长期成本不低
- **素材要上传**，车间实拍里有客户设备和工艺细节，不方便外传
- **术语照样错**，通用模型对垂类词一样束手无策，最后还是得人工逐条改

所以最后选了本地跑 Whisper + ffmpeg 烧录这条路：素材不出本机，一次装好之后零边际成本，术语可以靠自己的词表越用越准。

这套流水线能跑起来，是我一边翻文档、一边写脚本，一步步磨出来的：装环境、下载模型、写处理脚本，到后面每一个报错的定位，都踩过坑。我负责判断术语对错、看画面定夺；查文档、写脚本这类重复活，我尽量交给 AI 助手。

本文记录的是这套流程跑通后的完整实现，包括实测数据、13 个踩过的坑，以及哪些活可以交给 AI、哪些必须我自己把关。所有数字都是我自己跑出来的，不是估的。

![配图1_车间实拍_硬字幕效果.png](https://developer.qcloudimg.com/http-save/yehe-12801250/874d4210eef270d24b82e610c6a51b1f.png)

---

## 二、选型：三个决定成败的选择

### 2.1 用 faster-whisper，不用云端 ASR

faster-whisper 是 Whisper 的 CTranslate2 重实现，CPU 上跑 int8 量化就能用。

实测：74.6 秒的视频 + medium 模型，全程 54.5 秒。也就是说 1 分钟素材的处理时间不到 1 分钟，批量产出完全跟得上。

模型有两个档位：

| 模型     | 体积     | 特点               |
| ------ | ------ | ---------------- |
| small  | 484 MB | 快，中文够用           |
| medium | 1.5 GB | 慢一些，明显更准，做正式字幕推荐 |

**关键做法：双模型交叉验证。** 让 small 和 medium 各跑一遍，逐句对比——两者一致的地方基本可信，分歧的地方才是真正的难点，需要结合画面和上下文定夺。

举个真实例子：口播里有一句，small 输出"最少人算贷"，medium 输出"最少人算对"。单看都别扭，但后文紧接着"你算对了几个，回我一个数字"——立刻能判定 medium 是对的。这一招把准确率往上提了一截。

### 2.2 用 ASS，不用 SRT

SRT 只能表达"谁在什么时候说了什么"，管不了字体、字号、描边、位置。

硬字幕烧进画面，必须要有黑边，否则在浅色画面上白字直接消失。这些都得 ASS 才能控制。所以流程是 SRT 做中间产物（方便上传平台、方便人工校对），最终烧录用 ASS。

### 2.3 真人露脸的视频，绝对不要用 AI 配音

这一条决定了成品是不是废片，比任何技术细节都重要：

| 画面           | 声音               | 结论                              |
| ------------ | ---------------- | ------------------------------- |
| **真人露脸**     | **真人原声 + AI 字幕** | 嘴型天然同步，AI 只干打字幕的苦活              |
| 车间空镜（B-roll） | AI 配音            | 画面里没有嘴，看不出破绽                    |
| 真人露脸         | AI 配音            | **最亏的组合**，观众看到嘴在动、听到别人的声音，信任直接崩 |

一句话：AI 配音不是用来替代你的声音的，是用来给"没有嘴的画面"配声音的。

---

## 三、完整流程

### 环境准备

隔离 venv，不污染系统环境：

```bash
python -m venv envs/default
PY -m pip install faster-whisper "av<14" modelscope edge-tts
```

注意 `av<14`：faster-whisper 1.x 配 av 19.x 会直接报 `TypeError: open() got an unexpected keyword argument 'metadata_errors'`，实测降到 13.1.0 可用。

模型建议走 ModelScope（阿里，国内快且稳）。我自己在 HF 官方站和 hf-mirror 上反复下载失败——表现为下载"成功"但 `model.bin` 是 0 字节，加载时报 `RuntimeError: File model.bin is incomplete`。下载后校验一下：small 的 `model.bin` 应该约 484 MB。

### 步骤一：抽音频

Whisper 要 16kHz 单声道 WAV：

```bash
ffmpeg -y -v error -i "输入.mp4" -vn -ac 1 -ar 16000 -c:a pcm_s16le audio.wav
```

### 步骤二：语音识别

```python
model = WhisperModel(MODEL_DIR, device="cpu", compute_type="int8")
segments, info = model.transcribe(
    AUDIO, language="zh", beam_size=5,
    vad_filter=True, vad_parameters=dict(min_silence_duration_ms=300),
    initial_prompt="以下是普通话的内容转写，请使用简体中文并加上标点。",
)
```

三个要点：

- `vad_filter=True` 跳过静音段，**能显著减少幻听**（Whisper 在静音/音乐段会自己编内容）
- `initial_prompt` 指定简体中文 + 标点，对输出质量影响很大
- **一定要开 `word_timestamps=True`**，原因见下面第 3 个坑

### 步骤三：术语纠错（这套流程真正值钱的地方）

Whisper 对专业术语的同音字错误率高得离谱。真实错例：

| 识别结果            | 正确写法      |
| --------------- | --------- |
| 吹树机 / 吹熟机 / 吹术机 | **吹塑机**   |
| 形胚 / 型培 / 形培    | **型坯**    |
| 所摸力 / 索摩力       | **锁模力**   |
| 背后控制            | **壁厚控制**  |
| 出飞鞭             | **出飞边**   |
| 反攻              | **返工**    |
| 停计一下午           | **停机一下午** |

解决办法是维护一份术语纠错表，格式一行一条：

```
吹树机=>吹塑机
索摩力=>锁模力
!梅荷盐=>没合严          # 前缀 ! = 只在报告里提示，不自动替换（有歧义）
```

两个关键设计：

**① 术语表同时喂给 `initial_prompt`，能显著提升识别率。**  
实测同一段音频：不带提示词 →「索摩力」；带术语提示词 →「锁模力」。这一步几乎不花时间，收益却很大。

**② 错一次加一行，永久生效。**  
每次看校对报告，发现新错例就补一行。目前这份表已经积累到 84 条自动替换规则 + 13 条待人工定夺。跑得越多，越准。

校对时几个实用技巧：

- 结合画面抽帧判断场景（画面能提供关键上下文）
- 留意成对的比喻/排比（"心脏、手臂、肺"三者并列，就不可能是"心脏手臂废"）
- 专有名词直接联网搜一次，往往一击命中
- 有歧义的 1~3 秒单独切出来重识别——**上下文会带偏模型，切出来反而听得更准**
![配图2_术语纠错表_terms.png](https://developer.qcloudimg.com/http-save/yehe-12801250/bfd39b0568f0214f6c5435c14219ed02.png)

### 步骤四：切句

Whisper 对中文长口播不会自己切句。实测 74 秒的口播只输出 2 个 segment，每条 33 秒——直接当字幕就是一屏塞满字。

所以必须拿词级时间戳，自己按标点和长度切。切完一行别超过 14 个字。

### 步骤五：生成 ASS 并烧录

```bash
cd "<工作目录>"
ffmpeg -y -v error -i "输入.mp4" \
  -vf "ass=subtitle.ass:fontsdir='C\:/Windows/Fonts'" \
  -c:v libx264 -preset medium -crf 20 -pix_fmt yuv420p \
  -c:a copy -movflags +faststart \
  "输出.mp4"
```

要点：

- 先 `cd` 到工作目录，用 `ass=` 相对路径，**避开 Windows 盘符转义地狱**
- `fontsdir` 必须指定，否则中文变方块
- **`-c:a copy` 音频直接复制**——实测输出音频与原片 **MD5 完全一致**，原声零损耗且快
- `-crf 20` 画质好体积小，实测 84 MB 原片 → 23 MB

### 步骤六：抽帧验证（不可跳过）

```bash
ffmpeg -y -v error -ss 3  -i output.mp4 -frames:v 1 check1.png
ffmpeg -y -v error -ss 46 -i output.mp4 -frames:v 1 check2.png
```

必须人工看这两张图，确认：字幕真的渲染上去了、中文没变方块、长句没被左右裁切、位置不遮人脸。发现问题就回去调字号重烧。

![配图3_真人出镜_长句折行效果.png](https://developer.qcloudimg.com/http-save/yehe-12801250/e64a3409e042f5b53a8c443690814268.png)

---

## 四、13 个坑（按坑人程度排序）

### 坑 1：字幕叠在一起显示，或者该显示时完全不显示

原因：SRT 的毫秒是 3 位（`00:00:37,488`），ASS 只认 2 位小数（`0:00:37.48`）。直接把 3 位写进去，libass 会解析错乱。

这个坑最坑的地方在于症状：看起来像逻辑 bug，其实是时间格式问题，非常难查。

```python
def ts(t):  # "00:00:37,488" -> "0:00:37.48"
    h, m, rest = t.replace(",", ".").split(":")
    s, _, frac = rest.partition(".")
    return "%d:%02d:%02d.%s" % (int(h), int(m), int(s), (frac + "00")[:2])
```

### 坑 2：字幕读不通，每 16 个字硬切一刀

原因：Whisper 把中文逗号吐成了全角数字 `１`（U+FF11）。整段没有任何标点，切句逻辑彻底失效。

全角数字在中文口播里几乎不可能真实出现，所以统一把 `１`~`９` 归一化成逗号即可，顺便把中文句里的半角标点转全角。

同样隐蔽：模型有输出、时间轴也对，只是内容读不通，很容易误判成"识别精度不行"。

### 坑 3：一条字幕 30 多秒，一屏塞满字

原因：Whisper 不会自动切中文长句（见步骤四）。

解决：`word_timestamps=True` + 自己按标点切。

### 坑 4：中文长句不折行，左右被裁掉

原因：libass 的 `WrapStyle: 0` 对中文长句不可靠，实测中文长句会直接超框被左右裁掉。

解决：自己按像素宽度算断点——中文按 1 个字宽、英文数字按半个字宽，单行上限取 `(PlayResX - 左右边距) * 0.98`；断点尽量落在标点后、下一行不能以标点开头、末行不留孤字。

注意 U+2010~U+203B 这段（中文引号 ""、破折号 —、省略号 …）容易被误判成半角，要单独按全角算。

### 坑 5：英文单词被从中间拆开

`ModelScope` 被折成 `Model` / `Scope`。原因是折行函数按半角宽度算宽度，断点落在了词内部。

解决：候选断点若左右都是 ASCII 字母/数字/`_-.'+` 就跳过，并做兜底左移到词首。

### 坑 6：`File model.bin is incomplete`

HF 和镜像站下载大文件会失败，文件是 0 字节。改用 ModelScope 下载并校验体积。

### 坑 7：`unexpected keyword argument 'metadata_errors'`

av 版本过新。`pip install "av<14"`。

### 坑 8：中文显示成方块

没指定字体目录。加 `fontsdir`，字体用 Microsoft YaHei。

### 坑 9：字幕左右被裁切

字号过大。竖屏 720 宽降到 46，横屏用 56。实测字号 56 配长句会直接超出画面。

另外 PlayRes 必须与视频分辨率一致，否则字号缩放错乱。

### 坑 10：`No such file or directory`，但路径明明是对的

脚本里 `os.chdir()` 之后，相对输出路径失效。输出路径先 `os.path.abspath()` 再 `chdir`。

### 坑 11：`error: argument --rate: expected one argument`

负号开头的值被 argparse 当成选项了。写成 `--rate=-12%`（等号形式）。

### 坑 12：音量检测没有输出

`ffmpeg -v error` 把 `volumedetect` 的 info 级日志吞了。改用 `-hide_banner ... 2>&1 | grep mean_volume`。

### 坑 13：`Unrecognized option 'vsync'`

新版 ffmpeg 移除了 `-vsync`。改用 `-fps_mode passthrough`。

---

## 五、变体：用新文案替换原口播

如果画面是车间空镜（没有嘴），可以直接换成新文案的 AI 配音。核心思路是逐行合成，不要整段合成：

把文案拆成字幕行，每行单独 TTS 成一个文件，用 ffprobe 量出每行真实时长。这样字幕时间轴是精确已知的，不需要再跑一遍 Whisper 对齐，也不会有漂移。

行间停顿按公式算，落在 0.8~1.5s 最舒服。太小就调慢语速，太大就再调慢（而不是硬拉停顿）。

几个实测出来的经验值：

- 各语速下的朗读密度：`-12%` ≈ **3.5 字/秒**，`-6%` ≈ 3.6，`-2%` ≈ 3.8，`0%` ≈ 3.9
- 需要的最低密度 = `文案字数 ÷ (视频时长 - 1.2 - 尾部留白 - 0.4 × 行数)`
- 算出来超过 3.9，说明这条源片装不下，得换更长的片子或精简文案
- **实测参考**（源片 74.6s）：190 字从容用 `-12%`；232 字要 `-6%`；245 字得压到 `-2%`

结论：想要语速统一在 `-12%`，单条文案控制在 190~210 字最稳。

还有一条：`amix` 必须加 `normalize=0`，否则会把音量按输入数除小。

---

## 六、合规：AI 生成内容标注（别漏）

按平台现行要求，AI 生成内容需要标注，分两层：

| 层级         | 要求                                         |
| ---------- | ------------------------------------------ |
| 后台声明       | 发布页勾选"含有 AI 生成内容"                          |
| **画面可见标识** | 左上角或右下角；**前 3 秒出现**；**全程常驻**；不得透明虚化、不得一闪而过 |

只勾后台、画面没标识 = 不合规，在评论区或简介写一句也不算。

而这条流水线产出的视频，天然命中至少两项（AI 配音、AI 文案、AI 字幕），所以角标不能靠发布前临时想起来——要把它做成流水线里的固定一步。

批量生产最典型的翻车方式就是：漏标的那条正好是跑得最好的那条。

样式上，纯描边字在浅色画面上看不清，建议带不透明底色：左上角、白字、75% 不透明黑底、字号取画面宽度的 3.3% 左右。

![配图4_AI角标效果_空镜.png](https://developer.qcloudimg.com/http-save/yehe-12801250/2ddebad0891febfce9bbe2f5c598be41.png)

（各平台规则更新频繁，具体要求请以发布时的官方说明为准。）

---

## 七、哪些交给 AI，哪些必须自己把关

这套东西我一个人也能写，但会慢很多。跑下来分工大概是这样。

**可以交给 AI 做的部分：**

- **查报错。** 像 `metadata_errors` 这种"库版本不兼容"的报错，让它查一次就能给出根因和 `av<14` 的解法；我自己翻 issue 要翻好几页才能定位。
- **写胶水代码。** 抽音频、调模型、切句、生成 ASS、烧录——把这些串成一条命令，让它一次性写出来比我手敲快得多。
- **维护术语表。** 把校对报告丢给它，它能按 `错误=>正确` 的格式整理好，我只需要确认对不对。
- **查陌生名词。** 口播里出现不确定的专有名词，让它联网搜一次，往往一击命中。

**必须我自己把关的部分：**

- **术语对错。** 行业黑话它不懂。同一个音到底该是哪个词，只有干这行的人能定。
- **画面判断。** "这个镜头该配哪句话"要靠看画面，它看不到。
- **合规。** AI 角标加没加、加得对不对，它不会主动提醒你"这条漏标了"。
- **最终目检。** 抽帧出来的图必须人眼看——字幕有没有超框、有没有遮脸，它看不了。

还有一条不在视频流程里、但同一个道理的经验：让它整理我以前的旧资料时，它默认把材料放在了临时位置，没有归进我原来的知识库。我只补了一条明确的指令——"所有资料都存进我的知识库"——它很快就全部重做完了。

这让我更确认一件事：执行层面它很强，但"东西该放在哪、该叫什么名字"这类规则，得由我自己定清楚。

一句话总结：AI 把"写代码"这件苦活接走了，把"做判断"这件事留给了我。

这套流程里真正的护城河，是那份术语表和我自己的行业判断，不是脚本。

---

## 八、收益总结

| 指标    | 实测结果                                |
| ----- | ----------------------------------- |
| 处理速度  | 74.6 秒视频 + medium 模型 = **54.5 秒**   |
| 原声音质  | 输出音频与原片 **MD5 完全一致**（`-c:a copy`）   |
| 文件体积  | 84 MB → **23 MB**（`-crf 20`）        |
| 术语准确率 | 靠 84 条纠错规则 + 词表喂 prompt 持续提升        |
| 素材安全  | 全程本地，素材不出机器                         |
| 人力投入  | 单人完成。脚本一次写好长期复用，后续每条视频只需要做术语校对和抽帧目检 |

**这套流程最大的价值不在代码，在那份术语表。** 代码是一次性的，术语表是持续增值的——每踩一次坑往里加一行，下次就自动修掉了。跑到第一百条视频的时候，它比任何通用模型都懂你的行业。

---

## 参考资料

- **faster-whisper** —— Whisper 的 CTranslate2 重实现，本文的识别引擎
- **ModelScope 模型库** —— 国内下载大模型文件更稳
- **ffmpeg**（libass 的 `ass` 字幕滤镜）—— 本文的烧录环节
- **edge-tts** —— 变体方案里用到的逐行配音工具

---

本文所有数据均为本机实测，环境为 Windows + CPU int8 推理，不同硬件下耗时会有所差异。


我做的是工业设备讲解类短视频，素材来自车间实拍，每期 1~2 分钟。这类视频有两个硬约束：

Whisper 视频加硬字幕：13 个坑

本地 faster-whisper + ffmpeg 给车间视频烧硬字幕的完整流程。实测：74.6 秒素材处理耗时 54.5 秒；原声音频 MD5 无损；84 MB 原片压到 23 MB。记录六步流程与 13 个真实踩过的坑（毫秒格式不一致、全角数字导致切句失效、中文折行被裁切、模型下载落地 0 字节等），以及一份 84 条规则的吹塑术语纠错表。数据均为本机实测。

音视频

人工智能

开发工具

本地跑Whisper+ffmpeg解决工业视频硬字幕，实测74.6秒素材54.5秒处理完，用small+medium双模型交叉验证提升术语准确率，靠84条纠错表持续优化，全程素材不出本机，音频零损耗，文件84MB压至23MB，AI负责写代码，人工把关术语和画面判断。

语音产品特惠新用户14.9元起


2026上云采购 | AI焕新·智启新局

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Whisper 视频加硬字幕：13 个坑-腾讯云开发者社区-腾讯云

Whisper 视频加硬字幕：13 个坑

Whisper 视频加硬字幕：13 个坑

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐