whisper-cli 是什么

whisper-cli 是 Whisper 语音识别模型的命令行工具版本，具体来说它是基于 C++ 重写的实现（源自 ggerganov/whisper.cpp 项目），不是 OpenAI 官方的 Python 版本。

1. Whisper 是什么

Whisper 是 OpenAI 在 2022 年开源的自动语音识别（ASR）系统，能把人类语音转换成文字。它的特点是：

  • 多语言支持：能识别 99 种语言
  • 鲁棒性强：对口音、背景噪音、专业术语的识别效果很好
  • 能翻译：可以把其他语言翻译成英语文字
  • 开源免费：模型权重和代码都公开

2. whisper-cli 与原版 Whisper 的区别

原版 Whisper whisper-cli (whisper.cpp)
开发方 OpenAI 官方 社区开源项目（ggerganov）
语言 Python C++
依赖 需要 Python、PyTorch、大量依赖库 几乎零依赖，单个可执行文件
性能 较重，适合服务器/工作站 极轻量，可在笔记本、甚至树莓派上运行
硬件支持 主要支持 CUDA (NVIDIA) 支持 CUDA、Metal (Mac)、OpenVINO、纯 CPU
模型格式 PyTorch 原生格式 转换为 GGML/GGUF 格式，体积更小、加载更快

简单说：原版 Whisper 是”重型卡车”，whisper-cli 是”轻便摩托车”——功能类似，但后者更轻、更快、更容易部署。

3. 它能做什么

功能 说明
语音转文字 把录音、视频中的语音转成文本
生成字幕 输出 SRT/VTT/LRC 等字幕文件，带时间戳
多语言识别 自动检测语言，支持中文、英语、日语等
翻译为英语 把任何支持的语言语音翻译成英文字幕
说话人分离 区分”谁说了什么”（立体声/轻量级 diarize）
VAD 语音检测 自动过滤掉静音段，只处理有语音的部分
卡拉OK效果 生成带逐词高亮的字幕脚本

4. 典型使用场景

  • 做视频字幕：把视频中的语音一键生成 SRT 字幕文件
  • 会议/课堂录音转写：把长录音转成可搜索的文字稿
  • 本地隐私保护：所有处理都在本地完成，语音数据不上传云端
  • 低配置设备：在老旧电脑或嵌入式设备上运行语音识别
  • 批量处理：配合脚本批量转写大量音频文件

5. 基本使用示例

# 最简单的用法（自动识别，输出到控制台）
whisper-cli -f 录音.mp3

# 指定中文、输出 SRT 字幕文件
whisper-cli -f 录音.mp3 -l zh -osrt

# 使用更大的模型提高准确率（但速度更慢）
whisper-cli -f 录音.mp3 -m models/ggml-large.bin

# 启用 GPU 加速（如果有 NVIDIA 显卡）
whisper-cli -f 录音.mp3 -fa

# 只处理前 60 秒
whisper-cli -f 录音.mp3 -d 60000

# 翻译成英语
whisper-cli -f 日语录音.mp3 -tr

6. 关于模型文件

whisper-cli 需要模型文件才能工作（帮助文档中默认路径是 models/ggml-base.en.bin）。常见模型有：

模型 大小 速度 准确率 适用场景
tiny ~39MB 最快 一般 实时、低配置设备
base ~74MB 快 中等 日常快速转写
small ~244MB 中等 较好 平衡速度与质量
medium ~769MB 较慢 好 高质量需求
large ~1.5GB 最慢 最好 追求最高准确率

模型需要提前下载好放到指定目录，whisper-cli 才能调用。

总结：whisper-cli 是一个轻量级、高性能、纯本地运行的语音识别命令行工具，适合需要把语音快速转成文字或字幕的用户，而且完全不需要联网、不依赖 Python 环境。

整体说明

这是一个语音转文字（语音识别）工具的命令行界面。当你运行 whisper-cli 但没有指定音频文件时，它就会显示这个帮助信息。

错误提示：error: no input files specified（未指定输入文件）

用法：whisper-cli [选项] 文件0 文件1 ...

支持的音频格式：flac, mp3, ogg, wav

选项分类翻译

基础选项

选项 说明
​-h, --help 显示帮助信息并退出
​--version 显示版本信息
​-t N, --threads N 计算时使用的线程数（默认4）
​-p N, --processors N 计算时使用的处理器数（默认1）

音频处理范围

选项 说明
​-ot N, --offset-t N 时间偏移量（毫秒，默认0）
​-on N, --offset-n N 分段索引偏移（默认0）
​-d N, --duration N 要处理的音频时长（毫秒，默认0=全部）

文本生成控制

选项 说明
​-mc N, --max-context N 最大文本上下文token数（默认-1=无限制）
​-ml N, --max-len N 每段最大字符数（默认0=无限制）
​-sow, --split-on-word 按单词分割（而非按token分割）

解码搜索参数

选项 说明
​-bo N, --best-of N 保留的最佳候选数（默认5）
​-bs N, --beam-size N 束搜索的束宽（默认5）
​-ac N, --audio-ctx N 音频上下文大小（默认0=全部）

阈值控制（决定识别质量/灵敏度）

选项 说明
​-wt N, --word-thold N 单词时间戳概率阈值（默认0.01）
​-et N, --entropy-thold N 解码器失败的熵阈值（默认2.40）
​-lpt N, --logprob-thold N 解码器失败的对数概率阈值（默认-1.00）
​-nth N, --no-speech-thold N 无语音阈值（默认0.60）

采样温度（控制输出随机性）

选项 说明
​-tp, --temperature N 采样温度，0-1之间（默认0.00=确定性输出）
​-tpi, --temperature-inc N 温度增量（默认0.20）

功能模式

选项 说明
​-debug, --debug-mode 调试模式（如导出log_mel）
​-tr, --translate 将源语言翻译为英语
​-di, --diarize 立体声音频说话人分离（区分谁说了什么）
​-tdrz, --tinydiarize 启用轻量级说话人分离（需要tdrz模型）
​-nf, --no-fallback 解码时不使用温度回退策略

输出格式

选项 说明
​-otxt, --output-txt 输出为文本文件
​-ovtt, --output-vtt 输出为VTT字幕文件
​-osrt, --output-srt 输出为SRT字幕文件
​-olrc, --output-lrc 输出为LRC歌词文件
​-owts, --output-words 输出卡拉OK视频脚本
​-fp, --font-path 卡拉OK视频的等宽字体路径
​-ocsv, --output-csv 输出为CSV文件
​-oj, --output-json 输出为JSON文件
​-ojf, --output-json-full 输出包含更多信息的完整JSON
​-of FNAME, --output-file FNAME 指定输出文件路径（不含扩展名）

打印控制

选项 说明
​-np, --no-prints 只打印结果，不打印其他信息
​-ps, --print-special 打印特殊token
​-pc, --print-colors 打印彩色输出
​--print-confidence 打印置信度
​-pp, --print-progress 打印进度
​-nt, --no-timestamps 不打印时间戳

语言设置

选项 说明
​-l LANG, --language LANG spoken language（默认en=英语，auto=自动检测）
​-dl, --detect-language 自动检测语言后退出

提示与模型

选项 说明
​--prompt PROMPT 初始提示（最多n_text_ctx/2个token）
​--carry-initial-prompt 始终前置初始提示
​-m FNAME, --model FNAME 模型路径（默认models/ggml-base.en.bin）
​-f FNAME, --file FNAME 输入音频文件路径

硬件加速

选项 说明
​-oved D, --ov-e-device DNAME OpenVINO编码推理设备（默认CPU）
​-dtw MODEL 计算token级时间戳
​-ls, --log-score 记录最佳解码器token分数
​-ng, --no-gpu 禁用GPU
​-dev N, --device N GPU设备ID（默认0）
​-fa, --flash-attn 启用Flash Attention（默认true）
​-nfa, --no-flash-attn 禁用Flash Attention

其他高级选项

选项 说明
​-sns, --suppress-nst 抑制非语音token
​--suppress-regex REGEX 正则表达式匹配要抑制的token
​--grammar GRAMMAR 使用GBNF语法引导解码
​--grammar-rule RULE 顶层GBNF语法规则名
​--grammar-penalty N 非语法token的logits缩放惩罚（默认100.0）

VAD（语音活动检测）选项

选项 说明
​--vad 启用语音活动检测
​-vm FNAME, --vad-model FNAME VAD模型路径
​-vt N, --vad-threshold N VAD阈值（默认0.50）
​-vspd N, --vad-min-speech-duration-ms N 最小语音持续时间（毫秒，默认250）
​-vsd N, --vad-min-silence-duration-ms N 最小静音持续时间（用于分割段落，默认100）
​-vmsd N, --vad-max-speech-duration-s N 最大语音持续时间（自动分割更长段落，默认无限制）
​-vp N, --vad-speech-pad-ms N 语音填充（扩展段落，默认30）
​-vo N, --vad-samples-overlap N VAD样本重叠（段落间秒数，默认0.10）

通俗解释

Whisper 是 OpenAI 开发的开源语音识别模型，这个 whisper-cli 是它在命令行下的使用工具。

简单来说，它的工作流程是：

  1. 你给它一个音频文件（mp3/wav等）
  2. 它用AI模型把语音转成文字
  3. 可以输出成各种格式（纯文本、字幕文件、JSON等）

最常用的命令示例：

# 基本用法：识别音频并输出文字
whisper-cli -f audio.mp3

# 指定中文、输出SRT字幕
whisper-cli -f audio.mp3 -l zh -osrt

# 使用更好的模型
whisper-cli -f audio.mp3 -m models/ggml-large.bin

# 启用GPU加速
whisper-cli -f audio.mp3 -fa

‍