一篇文章搞定语音转写进阶：whisperX 词级时间戳与说话人分离实战

一篇文章搞定语音转写进阶：whisperX 词级时间戳与说话人分离实战

【免费下载链接】whisperXWhisperX: Automatic Speech Recognition with Word-level Timestamps (& Diarization)项目地址: https://gitcode.com/gh_mirrors/wh/whisperX

"「预算翻一倍」这句话，到底是谁在第几分钟说的？"

上周的周会录音只有 32 分钟，同事老王却来回听了两个多小时。不是他听力有问题，而是普通语音识别工具只告诉他"有人说了这句话"，却不告诉他"是谁说的、具体在哪一秒说的"。这正是 whisperX 这类开源语音识别工具存在的意义：它不止把音频变成文字，还能给每一个词标上精确时间戳，并自动区分不同的说话人。本文用一次真实的会议录音处理过程，带你从安装走到进阶 API 调用，全程不需要深厚的算法背景。

一个下午的教训：为什么普通转写救不了会议录音

whisperX 脱胎于 OpenAI 的 Whisper 模型，但它专治 Whisper 的三个"老大难"：

• 时间戳太粗：Whisper 只给句子级时间戳，整体偏移几秒是常事。whisperX 引入音素级强制对齐，把时间精度细化到单个单词，一个词对应音频上哪一秒，一目了然。
• 不支持批量：Whisper 原生无法批量推理，处理长音频慢得让人心焦。whisperX 换用 faster-whisper 后端，并先用语音活动检测（VAD）切出有效语音段再分批喂给模型，官方给出的数据是 large-v2 模型下可达约 70 倍实时速度。
• 分不清谁在说话：这正是老王最痛的一点。whisperX 接入 pyannote.audio 的说话人分离（Speaker Diarization）能力，自动把音频里不同的声音切成不同片段，分别标成 SPEAKER_00、SPEAKER_01……它不负责"认出张三李四"，只负责"把不同的人分开编号"。

图 1：whisperX 的处理流水线。原始音频先经过 VAD 切分合并，补零到 30 秒批量送入 Whisper 识别，再借助音素模型做强制对齐，最终输出词级时间戳。

开工前的装备清单：环境、依赖与一个 HF Token

动笔跑命令之前，先照单备齐这几样东西，能省下大量排错时间：

• Python 3.10：项目 README 明确建议的版本，用其他版本风险自负。
• ffmpeg：音频解码的基础依赖，缺了它连音频都读不进来。
• 合适的硬件：large-v2 模型搭配 beam_size=5 大约需要 8GB 以内显存；没有 GPU 也能跑，后面会说到 CPU 方案。

获取项目代码并安装依赖：

git clone https://gitcode.com/gh_mirrors/wh/whisperX cd whisperX pip install -r requirements.txt

不想用开发版的话，直接pip install whisperx装稳定版也可以。依赖清单在项目的 requirements.txt 里，核心角色有三个：torch/torchaudio 负责推理计算，faster-whisper 负责批量转写，pandas 负责把说话人时间线整理成表格，nltk 则用来把结果按句子切分。

还有一样容易被忽略的准备工作：Hugging Face Access Token（--hf_token）。说话人分离依赖的 pyannote 系列模型是门控模型，需要先到 Hugging Face 上同意对应模型的用户协议并生成一个只读 token，否则--diarize会在加载模型时直接报错——这一步卡住了不少初学者。

第一次实战：一行命令输出带发言人标签的字幕

假设会议录音存放在 audio_files/my_meeting.wav，你估计现场有 2 到 4 个人，那么只需一条命令：

python -m whisperx audio_files/my_meeting.wav --model medium --diarize --min_speakers 2 --max_speakers 4

几个关键参数的速查表：

• --model：Whisper 模型尺寸，可选 tiny/base/small/medium/large-v2，越大越准也越慢，日常推荐 medium 起步。
• --diarize：开启说话人分离的总开关，对应 whisperx/transcribe.py 里的处理逻辑。
• --min_speakers/--max_speakers：限定说话人数量范围。如果你确定只有两个人，干脆都写成 2，识别精度最高。
• --device：默认有 GPU 自动走 cuda；纯 CPU 机器建议追加--compute_type int8，速度与显存占用更友好。

想让字幕里每个词在被说出时高亮显示，可以再加--highlight_words True，在 srt/vtt 里会有下划线逐词扫过的视觉效果，非常直观。

看懂输出：四个文件分别能干什么

默认的--output_format all会在当前目录生成全套结果（也可以用--output_dir指定存放位置），它们各有分工：

• .srt / .vtt：标准字幕文件，每一句前面带[SPEAKER_00]之类的标签，直接拖进播放器就是"分人字幕"。
• .json：结构化数据，包含每个词的时间戳与置信度；加上--return_char_alignments True还能拿到字符级对齐信息。
• .txt：纯文本转写结果，适合快速复制引用。
• .tsv：表格格式，方便丢进 Excel 里做二次统计。

举一个最实用的玩法：拿到 .json 之后按"speaker"字段过滤，就能把某一位发言人的所有句子抽出来，拼成一份"个人发言集"——做会议纪要和访谈摘录都靠它。

进阶玩法：用 Python 拆开流水线，自己控制每一步

命令行适合快速出活，想精细控制就得走 Python API。whisperX 把整条流水线拆成了四步，入口全部集中在 whisperx/init.py：

import whisperx device = "cuda" audio_file = "audio.mp3" batch_size = 16 compute_type = "float16" # 显存紧张可换 "int8" # 1. 批量语音识别 model = whisperx.load_model("large-v2", device, compute_type=compute_type) audio = whisperx.load_audio(audio_file) result = model.transcribe(audio, batch_size=batch_size) # 2. 词级时间戳强制对齐 model_a, metadata = whisperx.load_align_model(language_code=result["language"], device=device) result = whisperx.align(result["segments"], model_a, metadata, audio, device) # 3. 说话人分离 diarize_model = whisperx.DiarizationPipeline(use_auth_token=YOUR_HF_TOKEN, device=device) diarize_segments = diarize_model(audio) # 4. 把说话人标签贴到每一句话、每一个词上 result = whisperx.assign_word_speakers(diarize_segments, result)

想理解背后的原理，打开 whisperx/diarize.py 就够了，两个核心部件都很直观：

• DiarizationPipeline 类：封装了 pyannote 的 speaker-diarization-3.1 模型，输入音频后返回一张 DataFrame，记录每个说话片段的起止时间和 SPEAKER 编号。
• assign_word_speakers 函数：逐一计算每个转写片段与各说话人片段的时间重叠量，谁重叠的时长最多，这段话就判给谁。

一句话概括这套算法：时间重叠投票。谁的声音覆盖了这句话的大部分时长，谁就是这句话的主人。

效果不达标？按这份排查清单逐项检查

先建立合理预期：说话人分离本身就不是 100% 完美的技术，两人同时开口这类重叠语音是几乎所有系统的硬伤，whisperX 也不例外。遇到问题，按下面的顺序逐个排查：

1. 说话人数量对不上：知道确切人数就直接写死，--min_speakers 2 --max_speakers 2这类写法最稳。
2. 标签张冠李戴：分离结果只给编号不给身份，编号和真人的对应关系需要自己根据内容确认；太短的片段本来就容易判错。
3. 时间戳和字幕对不齐：换更大的模型（--model large-v2），或者显式指定--align_model。
4. 个别词没有时间戳：像 "2014."、"£13.60" 这类字符不在对齐模型词典里，属于项目已知限制，不是你的操作问题。
5. 明显的语音被当成静音：把--vad_onset从默认的 0.500 往下调。
6. 显存告急：三件套组合拳——--batch_size 4、--compute_type int8、--model base。
7. 中文等非英语录音：加上--language zh并建议配合--model large。whisperX 对中、英、法、德、西、意、日、荷、乌、葡等语言内置了默认对齐模型，其他语种则需要自己到模型库找合适的音素模型。

会开完了，这些场景同样能用上

处理完老王的会议录音，你会发现这套流程的适用面远比想象中宽：

• 会议纪要自动化：跑一遍--diarize，把 srt 按说话人拆开，自动生成"逐人观点清单"，比逐段听录音快一个量级。
• 播客内容二次创作：用 json 按 speaker 筛选，快速圈出嘉宾的金句片段，配合词级时间戳直接定位剪辑点，几分钟就能搭出"金句集锦"的素材池。
• 课程与访谈复习：长访谈变成带时间轴的"谁说了什么"，回头找某一句话不再需要反复拖动进度条。
• 跨语言研究：--task translate能把非英语音频直接转成英文字幕，不过要留意翻译模式不支持对齐。

收尾：去源码里继续挖

whisperX 最值得读的几处代码：命令行全部参数在 whisperx/transcribe.py，Python API 入口在 whisperx/init.py，说话人分离核心逻辑在 whisperx/diarize.py，多语言使用示例在 EXAMPLES.md。装好环境、跑通第一遍之后，剩下的就是按需调整参数的事了。

最后用一句话总结：普通语音识别只告诉你"说了什么"，whisperX 再补上"什么时候说、是谁说的"——这两块拼齐，一段音频才算真正变成了可检索、可编辑、可复用的文字资产。🎯

【免费下载链接】whisperXWhisperX: Automatic Speech Recognition with Word-level Timestamps (& Diarization)项目地址: https://gitcode.com/gh_mirrors/wh/whisperX