1小时录音5分钟出稿：whisperX语音识别、词级时间戳与说话人分离上手全指南

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

你是否曾在深夜对着两小时的会议录音反复拖拽进度条，只为确认某句话到底是谁说的？是否受够了"转写工具虽然能出文字，但时间轴对不上、更分不清说话人"的尴尬？如果你正被这些琐事消耗精力，whisperX就是为你准备的答案——它把语音识别、词级时间戳和说话人分离封装进一条开箱即用的流水线，转写速度最高达实时的70 倍，从环境搭建到产出带说话人名字的字幕，全程只需3 条命令。下面我们借一次真实的周会场景，从零跑通全流程。

图为 whisperX 完整处理流程：音频输入 → VAD 语音检测 → 裁剪合并 → 批处理 → Whisper 转写 → 音素强制对齐 → 输出带词级时间戳的文本

一、普通转写为何总"差口气"？先看懂它在解决什么

在认识 whisperX 之前，不妨先和"原生 Whisper"做个对比。Whisper 是 OpenAI 开源的语音识别模型，识别准确率很高，但它有三个天然短板：

• 时间戳是句子级的：只能给出"这句话大概从第几秒开始"，逐词对齐误差可达数秒，做字幕时经常"画面说完了、字幕还没蹦出来"；
• 不支持批处理：一次只能处理一个音频段，长录音耗时惊人；
• 没有说话人信息：两个人对话，输出只有一段文字，谁说的全靠猜。

whisperX 正是针对这些痛点而来，两者差异一目了然：

一句话总结：Whisper 负责"听得懂"，whisperX 负责"听得准、分得清、跑得快"。

二、三大模块如何协同？用一条流水线看懂原理

把 whisperX 想象成一家"语音文字加工厂"，原材料是录音文件，成品是带时间戳和说话人标签的字幕。工厂里主要有四个工位：

1. VAD 质检员（语音活动检测）：先把音频里的静音、噪声段落"剪掉"，只保留有效语音，既避免了静音处的幻觉，也让后续处理更聚焦。这也是 whisperX 相比原生 Whisper识别错误率更低的原因之一；
2. Whisper 速记员（ASR 转写）：把裁剪后的语音一次性批量转成文字。因为支持批处理，所以能把一个小时的音频压缩到几分钟甚至更短；
3. 音素对齐师（强制对齐）：这是 whisperX 的"杀手锏"。它用 wav2vec2 这类音素级模型，把"词"和"声音"在时间轴上精确对位，从而输出每个单词的起止时间。就算你不懂什么是"音素"，可以这样理解：音素是发音的最小单位，好比"拼音的声母韵母"，对齐师靠它把每个字"钉"在正确的秒数上；
4. 说话人分诊台（说话人分离）：通过分析不同片段的声学特征差异，自动把"谁在何时开口"划分出来，再为每一段文字贴上SPEAKER_00、SPEAKER_01这样的标签。

这四个工位的调度逻辑就在 whisperx/transcribe.py 中，转写、对齐、分离三大步骤由命令行逐段驱动；而说话人分离的核心类DiarizationPipeline与说话人分配函数assign_word_speakers则位于 whisperx/diarize.py。你完全不用改代码，只需通过参数告诉它"要做什么、做多细"。

三、两步完成环境配置：复制粘贴即可

配置环境是新手最容易劝退的一步，其实核心就两件事：准备好 Python 环境，再装好 whisperX。项目官方在 Python 3.10 + PyTorch 2.0 环境下测试通过，推荐按下面的顺序操作：

conda create --name whisperx python=3.10 conda activate whisperx conda install pytorch==2.0.0 torchaudio==2.0.0 pytorch-cuda=11.8 -c pytorch -c nvidia pip install whisperx

如果你没有 conda，也可以直接pip install whisperx，然后确保系统里装了ffmpeg（用于音频解码），这是 whisperX 读取音频文件的前置依赖。

想体验最新开发版或参与源码修改，可以克隆仓库后以可编辑模式安装：

git clone https://gitcode.com/gh_mirrors/wh/whisperX cd whisperX pip install -e .

💡 小提示：CPU 环境也能跑！把后面的参数换成--compute_type int8即可在 Mac 或纯 CPU 机器上运行，只是速度会慢一些。

四、第一条命令：让录音秒变带词级时间戳的文本

装好后，把周会录音放到项目目录，执行最简单的一条命令：

whisperx meeting_20250310.wav

默认使用small模型，几秒钟后你就会得到一版带逐词时间戳的转写结果。想让时间戳更精准、字幕更专业，可以换成更大的模型并开启单词高亮：

whisperx meeting_20250310.wav --model large-v2 --batch_size 4 --highlight_words True

这里的几个参数值得记牢：

• --model：模型大小，从tiny到large-v2/large-v3可选，越大越准、越耗资源；
• --batch_size：批大小，显存吃紧时调小（如 4），显存充裕可调大提升速度；
• --highlight_words True：在 SRT/VTT 字幕中为每个单词标注出现时间；
• --output_format：输出格式，默认生成all（SRT/VTT/TXT/TSV/JSON 全部生成）。

转录结果的 JSON 里，每个片段都带有精确到秒级的起止时间，例如：

{ "start": 12.5, "end": 14.7, "text": "那我们这周的排期", "words": [ {"word": "那我们", "start": 12.5, "end": 13.1} ] }

有了词级时间戳，你不仅能做高质量字幕，还能按时间点跳转检索内容——这就是"5 分钟出稿"的第一个关键。

五、进阶玩法：给每一句话贴上说话人标签

转写只是第一步，周会场景里大家更关心的是"这话是谁说的"。开启说话人分离只需加两个参数：

whisperx meeting_20250310.wav --model large-v2 --diarize \ --min_speakers 3 --max_speakers 5 --hf_token YOUR_HF_TOKEN

这里有两处新手容易卡住的地方，提前说明：

• --diarize：打开说话人分离开关；
• --min_speakers/--max_speakers：如果已知参会人数，可以收紧范围提升准确率，比如"就 4 个人开会"，就都写成4；
• --hf_token：说话人分离依赖 pyannote 的模型，需要你在 Hugging Face 生成一个只读 Access Token，并到对应模型页面同意使用协议（README 中有详细指引）。没有这个 token，分离功能无法加载模型。

开启后，输出的 SRT 字幕会自动带上说话人前缀，效果类似：

00:00:12,500 --> 00:00:14,700 SPEAKER_00: 那我们这周的排期先对齐一下 00:00:15,200 --> 00:00:18,900 SPEAKER_01: 我觉得需求方那边还要再确认

从此整理会议纪要、按发言人筛选关键观点，都变成一条grep命令的事。说话人分配的核心逻辑位于 whisperx/diarize.py 中的assign_word_speakers函数——它通过计算每个词与说话人片段的时间重叠度，把文字归属到重叠最多的发言人名下，实现"词级"的说话人标注。

六、场景实战：把 whisperX 嵌入你自己的 Python 脚本

命令行适合快速出活，但如果你想把转写能力集成进自己的工具（比如自动出周报的脚本），whisperX 也提供了简洁的 Python API。核心三步如下：

import whisperx device = "cuda" audio_file = "meeting_20250310.wav" 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, min_speakers=3, max_speakers=5) result = whisperx.assign_word_speakers(diarize_segments, result) print(result["segments"]) # 每个片段都带 speaker 标签

整个过程与命令行完全对应：转写 → 对齐 → 分离。公共 API 全部从 whisperx/init.py 导出，音频加载统一由 whisperx/audio.py 完成，内部自动做重采样与格式转换，你只需关心业务逻辑。

七、避坑指南：新手最常踩的 4 个坑与调优技巧

结合社区反馈，以下 4 个问题出现频率最高，附上解决方案：

进阶调优技巧，按性价比排序：

1. 先裁剪后处理：把 1 小时录音先切成 10 分钟片段，减少长音频的累积误差，也方便并行处理；
2. 调节 VAD 阈值：如果发现"该识别的语音没识别出来"，降低--vad_onset（默认 0.5）和--vad_offset（默认 0.363）试试；
3. 多语言支持：whisperX 已内置英语、法语、德语、西语、意语、日语、中文等 10 种语言的音素对齐模型，处理中文只需--language zh --model large-v2，对齐模型会自动选择；
4. 关掉逐段依赖：--condition_on_previous_text False（默认已关闭）可减少长音频中的"复读机"幻觉。

八、总结与展望

把一段多人混谈的录音，变成"谁、什么时候、说了什么"的结构化文本——这就是 whisperX 的核心价值。它适合三类人：需要高频整理会议纪要的职场人、需要快速剪辑播客金句的创作者，以及想在产品里集成语音检索与字幕功能的开发者。该项目已发表于 INTERSPEECH 2023，并在 Ego4d 转写挑战赛中夺冠，技术实力有目共睹。

展望未来，随着更多语言的音素模型被社区补充、说话人分离精度的持续优化，whisperX 有望覆盖更复杂的声学场景，比如重叠语音与多人嘈杂会议。与其继续手动逐句听写，不如现在就 clone 仓库、跑通第一条命令，让语音处理真正"快人一步"。

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