whisper-timestamped

多语言自动语音识别，提供词级时间戳和置信度。

• 描述
  • 关于其他方法的说明
• 安装
  • 首次安装
    • 可能需要的额外包
    • Docker
  • 轻量级 CPU 安装
  • 升级到最新版本
• 使用
  • Python
  • 命令行
  • 实用函数
  • 词对齐图
  • 示例输出
• API 参考
  • 主转录函数
  • 实用函数
  • 文件写入函数
• 可能提升结果的选项
  • 精确的 Whisper 转录
  • 在发送至 Whisper 之前运行语音活动检测 (VAD)
  • 检测口吃现象
• 致谢/支持
• 引用

描述

Whisper 是由 OpenAI 训练的一系列多语言、鲁棒的语音识别模型，在多种语言中均取得了最先进的效果。Whisper 模型被训练为能够预测语音片段的大致时间戳（大多数情况下精度为 1 秒），但其本身无法预测词级时间戳。本仓库提出了一种实现方案，旨在 在使用 Whisper 模型进行转录时预测词级时间戳，并更准确地估计语音片段。此外，每个词和每个片段都会被赋予一个置信度分数。

该方法基于动态时间规整（DTW）应用于交叉注意力权重，正如 Jong Wook Kim 的这个笔记本 所展示的那样。在此基础上，我们做了一些改进：

• 开始和结束时间的估计更加准确。
• 为每个词分配置信度分数。
• 如果可能的话（无需束搜索...），无需额外的推理步骤即可预测词级时间戳（词对齐会在每个语音片段解码后实时完成）。
• 我们特别关注内存使用：与常规使用 Whisper 模型相比，whisper-timestamped 在处理长文件时仅需少量额外内存。

whisper-timestamped 是 openai-whisper Python 包的扩展，旨在与 openai-whisper 的任何版本兼容。它提供了更高效、更准确的词级时间戳，以及以下附加功能：

• 可以在应用 Whisper 模型之前运行语音活动检测 (VAD)，以避免因训练数据中的错误而导致的“幻觉”现象（例如，在完全静音的情况下预测出“感谢观看！”）。目前提供多种 VAD 方法：silero（默认）、auditok 和 auditok:v3.1。
• 当未指定语言时，输出中会提供各语言的概率分布。

免责声明：请注意，此扩展仅用于实验目的，可能会显著影响性能。对于因使用该扩展而产生的任何问题或效率低下，我们概不负责。

关于其他方法的说明

另一种相关的恢复词级时间戳的方法是使用能够预测字符的 wav2vec 模型，如 whisperX 中成功实现的那样。然而，这些方法存在一些缺点，而基于交叉注意力权重的方法（如 whisper_timestamped）则不存在这些问题。这些缺点包括：

• 需要为每种支持的语言找到一个对应的 wav2vec 模型，这与 Whisper 的多语言能力并不相称。
• 需要额外处理至少一个神经网络模型（wav2vec 模型），从而占用更多内存。
• 需要将 Whisper 转录中的字符标准化，以匹配 wav2vec 模型的字符集。这通常涉及繁琐的语言相关转换，例如将数字转换为文字（“2” -> “two”）、符号转换为文字（“%” -> “percent”，“€” -> “euro(s)”）等。
• 对于语音中的不流畅现象（填充词、犹豫、重复词等）缺乏鲁棒性，而这些内容通常会被 Whisper 去除。

另一种不需要额外模型的方法是查看 Whisper 模型在每个（子）词标记被预测后所估计的时间戳概率。例如，whisper.cpp 和 stable-ts 就采用了这种方法。然而，这种方法缺乏鲁棒性，因为 Whisper 模型并未被训练为在每个词之后都输出有意义的时间戳。Whisper 模型往往只会在预测一定数量的词之后才开始预测时间戳（通常是在句末），而在这种条件之外，时间戳的概率分布可能并不准确。实际上，这些方法在某些时间段内可能会产生完全不同步的结果（我们尤其在有广告音乐时观察到了这种情况）。此外，Whisper 模型的时间戳精度通常四舍五入到 1 秒（类似于许多视频字幕），这对于词级时间戳来说过于粗糙，要达到更高的精度也颇具挑战。

安装

首次安装

要求：

• python3（版本不低于 3.7，建议使用 3.9 或更高版本）
• ffmpeg（请参阅 Whisper 仓库 中的安装说明）

您可以通过 pip 安装 whisper-timestamped：

pip3 install whisper-timestamped

或者通过克隆本仓库并运行安装：

git clone https://github.com/linto-ai/whisper-timestamped
cd whisper-timestamped/
python3 setup.py install

可能需要的额外包

如果您想绘制音频时间戳与单词之间的对齐图（如 本节 所示），还需要安装 matplotlib：

pip3 install matplotlib

如果您想使用 VAD 选项（在运行 Whisper 模型之前进行语音活动检测），还需要安装 torchaudio 和 onnxruntime：

pip3 install onnxruntime torchaudio

如果您想使用来自 Hugging Face Hub 的微调 Whisper 模型，还需要安装 transformers：

pip3 install transformers

Docker

可以使用以下命令构建一个约 9GB 的 Docker 镜像：

git clone https://github.com/linto-ai/whisper-timestamped
cd whisper-timestamped/
docker build -t whisper_timestamped:latest .

适用于 CPU 的轻量级安装

如果您没有 GPU（或不想使用 GPU），则无需安装 CUDA 相关依赖。此时，您只需在安装 whisper-timestamped 之前，先安装一个轻量级的 PyTorch 版本，例如：

pip3 install \
     torch==1.13.1+cpu \
     torchaudio==0.13.1+cpu \
     -f https://download.pytorch.org/whl/torch_stable.html

此外，也可以通过以下命令构建一个约 3.5GB 的专用 Docker 镜像：

git clone https://github.com/linto-ai/whisper-timestamped
cd whisper-timestamped/
docker build -t whisper_timestamped_cpu:latest -f Dockerfile.cpu .

升级到最新版本

使用 pip 安装时，可以通过以下命令将库更新至最新版本：

pip3 install --upgrade --no-deps --force-reinstall git+https://github.com/linto-ai/whisper-timestamped

若需使用特定版本的 openai-whisper，可以运行如下命令：

pip3 install openai-whisper==20230124

使用方法

Python

在 Python 中，您可以使用 whisper_timestamped.transcribe() 函数，其用法与 whisper.transcribe() 类似：

import whisper_timestamped
help(whisper_timestamped.transcribe)

与 whisper.transcribe() 的主要区别在于，输出结果中会包含一个 "words" 键，用于记录每个片段中每个单词的起始和结束时间。请注意，单词中会包含标点符号。示例请参见下文中的 [示例输出]。

此外，默认的解码选项也有所不同，以优先考虑高效解码（采用贪婪解码而非束搜索，并且不启用温度采样回退）。若希望与 whisper 的默认设置一致，可使用 beam_size=5, best_of=5, temperature=(0.0, 0.2, 0.4, 0.6, 0.8, 1.0)。

此外，还提供了一些与词对齐相关的附加选项。

通常情况下，只需在 Python 脚本中将 whisper 替换为 whisper_timestamped，并将 model.transcribe(...) 替换为 transcribe(model, ...)，即可正常工作：

import whisper_timestamped as whisper

audio = whisper.load_audio("AUDIO.wav")

model = whisper.load_model("tiny", device="cpu")

result = whisper.transcribe(model, audio, language="fr")

import json
print(json.dumps(result, indent = 2, ensure_ascii = False))

需要注意的是，您可以使用 Hugging Face 上的微调 Whisper 模型，或者从本地文件夹加载模型，只需调用 whisper_timestamped 的 load_model 方法即可。例如，若要使用 whisper-large-v2-nob，可以直接执行以下操作：

import whisper_timestamped as whisper

model = whisper.load_model("NbAiLab/whisper-large-v2-nob", device="cpu")

# ...

命令行工具

您也可以在命令行中使用 whisper_timestamped，其用法与 whisper 类似。可通过以下命令查看帮助信息：

whisper_timestamped --help

与 whisper 命令行工具的主要区别包括：

• 输出文件：
  • 输出的 JSON 文件包含单词的时间戳和置信度分数。示例请参见下文中的 [示例输出]。
  • 新增了 CSV 格式的输出。
  • 对于 SRT、VTT 和 TSV 格式，还会额外保存包含单词时间戳的文件。
• 默认选项有所不同：
  • 默认情况下未设置输出目录：如需与 whisper 默认行为一致，可使用 --output_dir .。
  • 默认情况下不启用详细模式：如需与 whisper 默认行为一致，可使用 --verbose True。
  • 默认禁用束搜索解码和温度采样回退，以提高解码效率。若希望与 whisper 默认设置相同，可使用 --accurate 选项（该选项等价于 --beam_size 5 --temperature_increment_on_fallback 0.2 --best_of 5）。
• 提供了一些额外的特定选项：
  • --compute_confidence 可用于开启或关闭对每个单词置信度分数的计算。
  • --punctuations_with_words 可决定标点符号是否应与前一个单词合并显示。

以下是一个使用 tiny 模型处理多个文件，并将结果输出到当前目录的示例命令，其行为与 whisper 的默认设置一致：

whisper_timestamped audio1.flac audio2.mp3 audio3.wav --model tiny --output_dir .

需要注意的是，您也可以使用来自 Hugging Face 或本地文件夹的微调 Whisper 模型。例如，若要使用 whisper-large-v2-nob 模型，只需执行以下命令：

whisper_timestamped --model NbAiLab/whisper-large-v2-nob <...>

工具函数

除了主函数 transcribe 外，whisper-timestamped 还提供了一些实用工具函数：

remove_non_speech

使用语音活动检测（VAD）去除音频中的非语音部分。

from whisper_timestamped import remove_non_speech

audio_speech, segments, convert_timestamps = remove_non_speech(audio, vad="silero")

load_model

从指定名称或路径加载 Whisper 模型，支持从 Hugging Face 加载微调模型。

from whisper_timestamped import load_model

model = load_model("NbAiLab/whisper-large-v2-nob", device="cpu")

词对齐图示

您还可以使用 whisper_timestamped.transcribe() Python 函数中的 plot_word_alignment 选项，或 whisper_timestamped 命令行工具中的 --plot 选项，来查看每个片段的词对齐情况。

• 上方图表展示了用于对齐的交叉注意力权重经过动态时间规整（DTW）后的变换结果。横轴表示时间，纵轴表示预测的标记，其中开头和结尾是特殊的时间戳标记，中间则是（子）单词和标点符号。
• 下方图表是输入信号的 MFCC 表示（Whisper 使用的基于梅尔频率倒谱的特征）。
• 纵向的红色虚线标示出了单词边界的位置（标点符号被“粘”在前一个单词上）。

示例输出

whisper_timestamped.transcribe() 函数的输出是一个 Python 字典，可以通过命令行工具以 JSON 格式查看。

JSON 模式的定义可在 tests/json_schema.json 中找到。

以下是示例输出：

whisper_timestamped AUDIO_FILE.wav --model tiny --language fr

{
  "text": "Bonjour! Est-ce que vous allez bien?",
  "segments": [
    {
      "id": 0,
      "seek": 0,
      "start": 0.5,
      "end": 1.2,
      "text": " Bonjour!",
      "tokens": [ 25431, 2298 ],
      "temperature": 0.0,
      "avg_logprob": -0.6674491882324218,
      "compression_ratio": 0.8181818181818182,
      "no_speech_prob": 0.10241222381591797,
      "confidence": 0.51,
      "words": [
        {
          "text": "Bonjour!",
          "start": 0.5,
          "end": 1.2,
          "confidence": 0.51
        }
      ]
    },
    {
      "id": 1,
      "seek": 200,
      "start": 2.02,
      "end": 4.48,
      "text": " Est-ce que vous allez bien?",
      "tokens": [ 50364, 4410, 12, 384, 631, 2630, 18146, 3610, 2506, 50464 ],
      "temperature": 0.0,
      "avg_logprob": -0.43492694334550336,
      "compression_ratio": 0.7714285714285715,
      "no_speech_prob": 0.06502953916788101,
      "confidence": 0.595,
      "words": [
        {
          "text": "Est-ce",
          "start": 2.02,
          "end": 3.78,
          "confidence": 0.441
        },
        {
          "text": "que",
          "start": 3.78,
          "end": 3.84,
          "confidence": 0.948
        },
        {
          "text": "vous",
          "start": 3.84,
          "end": 4.0,
          "confidence": 0.935
        },
        {
          "text": "allez",
          "start": 4.0,
          "end": 4.14,
          "confidence": 0.347
        },
        {
          "text": "bien?",
          "start": 4.14,
          "end": 4.48,
          "confidence": 0.998
        }
      ]
    }
  ],
  "language": "fr"
}

如果未指定语言（例如在命令行中没有 --language fr 选项），则会多出一个包含语言概率的键：

{
  ...
  "language": "fr",
  "language_probs": {
    "en": 0.027954353019595146,
    "zh": 0.02743500843644142,
    ...
    "fr": 0.9196318984031677,
    ...
    "su": 3.0119704064190955e-08,
    "yue": 2.2565967810805887e-05
  }
}

API 参考

主要转录功能

transcribe_timestamped(model, audio, **kwargs)

使用 Whisper 模型对音频进行转录，并计算词级别的时间戳。

参数：

• model: Whisper 模型实例 用于转录的 Whisper 模型。

• audio: Union[str, np.ndarray, torch.Tensor] 要转录的音频文件路径，或作为 NumPy 数组或 PyTorch 张量的音频波形。

• language: str, 可选（默认：None） 音频的语言。如果为 None，则会进行语言检测。

• task: str，默认为 "transcribe" 要执行的任务：可以是“transcribe”（语音识别）或“translate”（翻译成英语）。

• vad: Union[bool, str, List[Tuple[float, float]]], 可选（默认：False） 是否使用语音活动检测（VAD）来去除非语音段。可取值如下：

  • True/False：启用/禁用 VAD（默认使用 Silero VAD）
  • “silero”：使用 Silero VAD
  • “auditok”：使用 Auditok VAD
  • (开始, 结束) 时间戳列表：显式指定语音段

• detect_disfluencies: bool，默认为 False 是否在转录中检测并标记口吃、停顿词等不流畅现象。

• trust_whisper_timestamps: bool，默认为 True 是否依赖 Whisper 的时间戳来确定初始片段位置。

• compute_word_confidence: bool，默认为 True 是否计算单词的置信度分数。

• include_punctuation_in_confidence: bool，默认为 False 在计算单词置信度时，是否包含标点符号的概率。

• refine_whisper_precision: float，默认为 0.5 以秒为单位，调整 Whisper 片段位置的精度。必须是 0.02 的倍数。

• min_word_duration: float，默认为 0.02 单词的最小持续时间，以秒为单位。

• plot_word_alignment: bool 或 str，默认为 False 是否绘制每个片段的词对齐图。如果是字符串，则将图表保存到指定文件。

• word_alignement_most_top_layers: int，可选（默认：None） 用于词对齐的顶层数量。如果为 None，则使用所有层。

• remove_empty_words: bool，默认为 False 是否移除出现在片段末尾且持续时间为零的空单词。

• naive_approach: bool，默认为 False 强制采用朴素方法，即解码两次（一次用于转录，一次用于对齐）。

• use_backend_timestamps: bool，默认为 False 是否使用后端提供的词时间戳（openai-whisper 或 transformers），而不是由 whisper-timestamped 的复杂启发式算法计算的时间戳。

• temperature: Union[float, List[float]], 默认为 0.0 采样温度。可以是单个值，也可以是用于回退的温度列表。

• compression_ratio_threshold: float，默认为 2.4 如果 gzip 压缩比高于此值，则认为解码失败。

• logprob_threshold: float，默认为 -1.0 如果平均对数概率低于此值，则认为解码失败。

• no_speech_threshold: float，默认为 0.6 <|nospeech|> 令牌的概率阈值。

• condition_on_previous_text: bool，默认为 True 是否将前一个输出作为下一个窗口的提示。

• initial_prompt: str，可选（默认：None） 可选文本，用作第一个窗口的提示。

• suppress_tokens: str，默认为 "-1" 采样过程中要抑制的令牌 ID 列表，以逗号分隔。

• fp16: bool，可选（默认：None） 是否以 fp16 精度进行推理。

• verbose: bool 或 None，默认为 False 是否将正在解码的文本显示在控制台上。如果为 True，则显示所有详细信息；如果为 False，则显示最少信息；如果为 None，则不显示任何内容。

返回值：

一个包含以下内容的字典：

• text: str - 完整的转录文本
• segments: List[dict] - 片段字典列表，每个字典包含：
  • id: int - 片段 ID
  • seek: int - 音频文件中的起始位置（以样本为单位）
  • start: float - 片段的开始时间（以秒为单位）
  • end: float - 片段的结束时间（以秒为单位）
  • text: str - 片段的转录文本
  • tokens: List[int] - 片段的令牌 ID 列表
  • temperature: float - 该片段使用的温度
  • avg_logprob: float - 片段的平均对数概率
  • compression_ratio: float - 片段的压缩比
  • no_speech_prob: float - 片段中无语音的概率
  • confidence: float - 片段的置信度评分
  • words: List[dict] - 词字典列表，每个字典包含：
    • start: float - 词的开始时间（以秒为单位）
    • end: float - 词的结束时间（以秒为单位）
    • text: str - 词的内容
    • confidence: float - 词的置信度评分（如果已计算）
• language: str - 检测到的或指定的语言
• language_probs: dict - 语言检测概率（如果适用）

异常：

• RuntimeError: 如果 VAD 方法未正确安装或配置。
• ValueError: 如果 refine_whisper_precision 不是 0.02 的正整数倍。
• AssertionError: 如果音频时长短于预期，或片段数量存在不一致。

注意事项：

• 该函数使用 Whisper 模型对音频进行转录，然后进行额外处理以生成词级别的时间戳和置信度分数。
• VAD 功能可以通过去除非语音段来显著提高转录准确性，但需要额外的依赖项（例如，使用 Silero VAD 时需要 torchaudio 和 onnxruntime）。
• naive_approach 参数在调试或处理特定音频特征时可能有用，但其速度可能慢于默认方法。
• 当 use_efficient_by_default 为 True 时，一些参数如 best_of、beam_size 和 temperature_increment_on_fallback 默认设置为 None，以提高处理效率。
• 该函数支持 OpenAI Whisper 和 Transformers 后端，可在加载模型时指定。

工具函数

remove_non_speech(audio, **kwargs)

使用语音活动检测（VAD）从音频中移除非语音段。

参数：

• audio: torch.Tensor 音频数据，以 PyTorch 张量形式提供。

• use_sample: bool, 默认 False 如果为 True，则返回以样本为单位的开始和结束时间，而非秒。

• min_speech_duration: float, 默认 0.1 语音段的最小持续时间，单位为秒。

• min_silence_duration: float, 默认 1 静音段的最小持续时间，单位为秒。

• dilatation: float, 默认 0.5 VAD 检测到的每个语音段将被扩展多少秒。

• sample_rate: int, 默认 16000 音频的采样率。

• method: str 或 List[Tuple[float, float]], 默认 "silero" 要使用的 VAD 方法。可以是 "silero"、"auditok"，或一个时间戳列表。

• avoid_empty_speech: bool, 默认 False 如果为 True，则避免返回空的语音段。

• plot: Union[bool, str], 默认 False 如果为 True，则绘制 VAD 结果；如果为字符串，则将图表保存到指定文件。

返回值：

一个包含以下内容的元组：

1. torch.Tensor: 移除非语音段后的音频。
2. List[Tuple[float, float]]: 语音段的 (开始, 结束) 时间戳列表。
3. Callable: 将新音频中的时间戳转换为原始音频时间戳的函数。

异常：

• ImportError: 如果未安装所需的 VAD 库（例如 auditok）。
• ValueError: 如果指定了无效的 VAD 方法。

注释：

• 此函数特别适用于在处理音频之前移除静音和非语音部分，从而提高转录的准确性。
• VAD 方法的选择会影响移除非语音部分的准确性和速度。

load_model(name, device=None, backend="openai-whisper", download_root=None, in_memory=False)

从给定名称或路径加载 Whisper 模型。

参数：

• name: str 模型名称或路径。可以是：

  • OpenAI Whisper 标识符：“large-v3”、“medium.en”等。
  • HuggingFace 标识符：“openai/whisper-large-v3”、“distil-whisper/distil-large-v2”等。
  • 文件名：“path/to/model.pt”、“path/to/model.ckpt”、“path/to/model.bin”。
  • 文件夹名：“path/to/folder”。

• device: Union[str, torch.device], 可选（默认：None） 使用的设备。如果为 None，则优先使用 CUDA，否则使用 CPU。

• backend: str, 默认 “openai-whisper” 使用的后端。可以是 “transformers” 或 “openai-whisper”。

• download_root: str, 可选（默认：None） 下载模型的根目录。如果为 None，则使用默认下载根目录。

• in_memory: bool, 默认 False 是否将模型权重预加载到主机内存中。

返回值：

加载的 Whisper 模型。

异常：

• ValueError: 如果指定了无效的后端。
• ImportError: 如果使用 “transformers” 后端时未安装 transformers 库。
• RuntimeError: 如果无法从指定源找到或下载模型。
• OSError: 如果读取模型文件或访问指定路径时出现问题。

注释：

• 使用本地模型文件时，请确保文件格式与所选后端兼容。
• 对于 HuggingFace 模型，如果尚未缓存到本地，可能需要互联网连接来下载模型。
• 该函数支持加载 OpenAI Whisper 和 Transformers 模型，提供了灵活的模型选择方式。

get_alignment_heads(model, max_top_layer=3)

获取给定模型的对齐头。

参数：

• model: Whisper 模型实例 需要检索对齐头的 Whisper 模型。

• max_top_layer: int, 默认 3 考虑对齐头的最大顶层层数。

返回值：

表示对齐头的稀疏张量。

注释：

• 此函数在内部用于优化单词对齐过程。
• 对齐头是特定于模型的，用于提高单词级时间戳的准确性。

文件写入函数

以下函数可用于将转录文本写入各种文件格式：

write_csv(transcript, file, sep=",", text_first=True, format_timestamps=None, header=False)

将转录数据写入 CSV 文件。

参数：

• transcript: List[dict] 转录片段字典列表。

• file: 文件对象 用于写入 CSV 数据的文件。

• sep: str, 默认 "," CSV 文件中使用的分隔符。

• text_first: bool, 默认 True 如果为 True，则先写文本列，再写开始/结束时间。

• format_timestamps: Callable, 可选（默认：None） 用于格式化时间戳值的函数。

• header: Union[bool, List[str]], 默认 False 如果为 True，则写入默认标题；如果是列表，则使用自定义标题。

异常：

• IOError: 如果写入指定文件时出现问题。
• ValueError: 如果转录数据格式不符合预期。

注释：

• 该函数适用于将转录结果以表格形式导出，以便进一步分析或处理。
• format_timestamps 参数允许自定义时间戳格式，这在特定用例或数据分析需求中非常有用。

write_srt(transcript, file)

将转录数据写入 SRT（SubRip 字幕）文件。

参数：

• transcript: List[dict] 转录片段字典列表。

• file: 文件对象 用于写入 SRT 数据的文件。

异常：

• IOError: 如果写入指定文件时出现问题。
• ValueError: 如果转录数据格式不符合预期。

注释：

• SRT 是一种广泛支持的字幕格式，因此此函数非常适合根据转录内容为视频创建字幕。

write_vtt(transcript, file)

将转录数据写入 VTT（WebVTT）文件。

参数：

• transcript: List[dict] 转录片段字典列表。

• file: 文件对象 用于写入 VTT 数据的文件。

异常：

• IOError: 如果写入指定文件时出现问题。
• ValueError: 如果转录数据格式不符合预期。

注释：

• WebVTT 是 W3C 关于在 HTML5 中显示定时文本的标准，因此该函数对于基于 Web 的应用非常有用。

write_tsv(transcript, file)

将转录数据写入 TSV（制表符分隔值）文件。

参数：

• transcript: List[dict] 转录片段字典列表。

• file: 文件对象 用于写入 TSV 数据的文件。

异常：

• IOError: 如果写入指定文件时出现问题。
• ValueError: 如果转录数据格式不符合预期。

注释：

• TSV 文件便于将转录数据导入电子表格或其他数据分析工具中。

可能提升结果的选项

以下是一些默认未启用但可能提升结果的选项。

准确的 Whisper 转录

如前所述，为了提高效率，某些解码选项默认是禁用的。然而，这可能会影响转录的质量。为了使用最有可能提供高质量转录的选项，请使用以下设置。

• 在 Python 中：

results = whisper_timestamped.transcribe(model, audio, beam_size=5, best_of=5, temperature=(0.0, 0.2, 0.4, 0.6, 0.8, 1.0), ...)

• 在命令行中：

whisper_timestamped --accurate ...

在发送给 Whisper 之前运行语音活动检测 (VAD)

当 Whisper 模型接收到没有语音的部分时，可能会“幻觉”出文本内容。为了避免这种情况，可以在使用 Whisper 模型进行转录之前，先运行 VAD 并将语音片段拼接在一起。这可以通过 whisper-timestamped 实现。

• 在 Python 中：

results = whisper_timestamped.transcribe(model, audio, vad=True, ...)

• 在命令行中：

whisper_timestamped --vad True ...

默认情况下，使用的 VAD 方法是 silero。 但也可以选择其他方法，例如较早版本的 silero，或者 auditok。 引入这些方法的原因是，最新版本的 silero VAD 在某些音频上会产生大量误报（在静音中检测到语音）。

• 在 Python 中：

results = whisper_timestamped.transcribe(model, audio, vad="silero:v3.1", ...)
results = whisper_timestamped.transcribe(model, audio, vad="auditok", ...)

• 在命令行中：

whisper_timestamped --vad silero:v3.1 ...
whisper_timestamped --vad auditok ...

为了查看 VAD 的结果，可以使用 whisper_timestamped 命令行工具的 --plot 选项， 或者使用 whisper_timestamped.transcribe() Python 函数的 plot_word_alignment 选项。 它会以如下方式显示输入音频信号上的 VAD 结果（横轴为时间，单位：秒）：

vad="silero:v4.0"	vad="silero:v3.1"	vad="auditok"

检测口吃现象

Whisper 模型倾向于去除语音中的口吃现象（填充词、犹豫、重复等）。如果不采取预防措施，未被转录的口吃部分会影响后续单词的时间戳：该单词的起始时间实际上会是口吃部分的起始时间。whisper-timestamped 可以采用一些启发式方法来避免这种情况。

• 在 Python 中：

results = whisper_timestamped.transcribe(model, audio, detect_disfluencies=True, ...)

• 在命令行中：

whisper_timestamped --detect_disfluencies True ...

重要提示： 请注意，使用这些选项时，可能出现的口吃现象会在转录中以特殊的 "[*]" 单词形式出现。

致谢/支持

whisper-timestamped 主要由 Jérôme Louradour 编写。 它基于以下库：

• whisper：Whisper 语音识别（MIT 许可证）。
• dtw-python：动态时间规整（GPL v3 许可证）。

如果您愿意支持本库的开发，欢迎请我喝杯咖啡：

引用

如果您在研究中使用了本项目，请引用该仓库：

@misc{lintoai2023whispertimestamped,
  title={whisper-timestamped},
  author={Louradour, J{\'e}r{\^o}me},
  journal={GitHub repository},
  year={2023},
  publisher={GitHub},
  howpublished = {\url{https://github.com/linto-ai/whisper-timestamped}}
}

同时请引用 OpenAI 的 Whisper 论文：

@article{radford2022robust,
  title={Robust speech recognition via large-scale weak supervision},
  author={Radford, Alec and Kim, Jong Wook and Xu, Tao and Brockman, Greg and McLeavey, Christine and Sutskever, Ilya},
  journal={arXiv preprint arXiv:2212.04356},
  year={2022}
}

以及关于动态时间规整的论文：

@article{JSSv031i07,
  title={Computing and Visualizing Dynamic Time Warping Alignments in R: The dtw Package},
  author={Giorgino, Toni},
  journal={Journal of Statistical Software},
  year={2009},
  volume={31},
  number={7},
  doi={10.18637/jss.v031.i07}
}

whisper-timestamped 快速上手指南

whisper-timestamped 是 OpenAI Whisper 的扩展工具，专为多语言自动语音识别（ASR）设计。它在保留 Whisper 强大识别能力的同时，增加了单词级时间戳和置信度评分功能，特别适合需要精准字幕对齐的场景。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python 版本: Python 3.7+ (推荐 3.9 及以上)
• 核心依赖: ffmpeg (用于音频处理)
  • Ubuntu/Debian: sudo apt update && sudo apt install ffmpeg
  • macOS: brew install ffmpeg
  • Windows: 下载构建包并配置环境变量，或通过 conda install -c conda-forge ffmpeg 安装
• 可选依赖:
  • 若需绘制时间轴对齐图：matplotlib
  • 若需使用语音活动检测 (VAD) 以减少幻觉：onnxruntime, torchaudio

国内加速建议：安装 Python 包时，推荐使用清华或阿里镜像源以提升下载速度。 例如：pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple <包名>

安装步骤

1. 标准安装（推荐 GPU 用户）

直接使用 pip 安装最新版本：

pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple whisper-timestamped

或者从源码安装：

git clone https://github.com/linto-ai/whisper-timestamped
cd whisper-timestamped/
python3 setup.py install

2. 轻量级安装（仅 CPU 用户）

如果您没有 GPU 或不想使用 CUDA，请先安装 CPU 版本的 PyTorch，再安装本工具，以避免下载巨大的 CUDA 依赖包：

pip3 install torch==1.13.1+cpu torchaudio==0.13.1+cpu -f https://download.pytorch.org/whl/torch_stable.html
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple whisper-timestamped

3. 安装可选功能组件

根据需求安装额外功能包：

# 绘图支持
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple matplotlib

# VAD (语音活动检测) 支持
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple onnxruntime torchaudio

# HuggingFace 微调模型支持
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple transformers

基本使用

方式一：Python 脚本调用

这是最灵活的使用方式。只需将导入语句从 import whisper 改为 import whisper_timestamped as whisper，即可直接获得单词级时间戳。

import whisper_timestamped as whisper
import json

# 1. 加载音频文件
audio = whisper.load_audio("AUDIO.wav")

# 2. 加载模型 (支持 'tiny', 'base', 'small', 'medium', 'large' 或 HuggingFace 模型路径)
# device="cuda" 可启用显卡加速，若无显卡则使用 "cpu"
model = whisper.load_model("tiny", device="cpu")

# 3. 执行转录
# language 指定语言代码 (如 "zh", "en", "fr")，不指定则自动检测
result = whisper.transcribe(model, audio, language="zh")

# 4. 输出结果 (包含 words 字段，内含每个单词的 start, end 时间和 confidence 置信度)
print(json.dumps(result, indent=2, ensure_ascii=False))

关键特性说明：

• 输出结果中的 segments 列表下会新增 words 字段，包含每个单词的精确起止时间。
• 默认采用贪心解码（greedy decoding）以提高效率。若需更高精度（类似原生 Whisper 默认行为），可添加参数 beam_size=5, best_of=5。
• 支持直接加载 HuggingFace 上的微调模型，例如：whisper.load_model("NbAiLab/whisper-large-v2-nob")。

方式二：命令行工具 (CLI)

命令行用法与原生 whisper 命令高度兼容，但输出文件会包含更丰富的时间戳信息。

基础命令示例：

whisper_timestamped audio_file.mp3 --model tiny --language zh --output_dir .

常用参数说明：

• --model: 选择模型大小 (tiny, base, small, medium, large) 或 HuggingFace 模型 ID。
• --language: 指定源语言代码（如 zh 代表中文）。
• --output_dir: 输出文件夹路径。
• --accurate: 启用高精度模式（等价于 --beam_size 5 --best_of 5 等参数），牺牲速度换取更好效果。
• --compute_confidence: 开启/关闭单词置信度计算。

输出文件格式增强：

• JSON: 包含完整的单词级时间戳和置信度。
• SRT/VTT/TSV: 除了常规字幕文件外，还会生成带有单词级时间戳的额外文件。
• CSV: 新增 CSV 格式输出支持。