名称： faster-whisper
描述： "使用 faster-whisper 进行本地语音转文本。速度比 OpenAI Whisper 快 4-6 倍，精度相同；GPU 加速可实现约 20 倍实时转录速度。支持 SRT/VTT/TTML/CSV 字幕、说话人分离、URL/YouTube 输入、带 ETA 的批处理、转录本搜索、章节检测、按文件语言映射。"
版本： 1.5.1
作者： ThePlasmak
主页： https://github.com/ThePlasmak/faster-whisper
标签：
[
"audio",
"transcription",
"whisper",
"speech-to-text",
"ml",
"cuda",
"gpu",
"subtitles",
"diarization",
"podcast",
"chapters",
"search",
"csv",
"ttml",
"batch",
]
platforms: ["linux", "macos", "wsl2"]
元数据：
{
"openclaw":
{
"emoji": "🗣️",
"requires":
{
"bins": ["python3"],
"optionalBins": ["ffmpeg", "yt-dlp"],
"optionalPaths": ["~/.cache/huggingface/token"],
},
},
}

Faster Whisper

使用 faster-whisper 进行本地语音转文本——这是 OpenAI Whisper 的 CTranslate2 重新实现，在保持相同精度的前提下，运行速度快 4-6 倍。借助 GPU 加速，可实现约 20 倍实时的转录速度（约 30 秒转录 10 分钟音频文件）。

使用场景

当你需要以下功能时，请使用此技能：

• 转录音频/视频文件 —— 会议、访谈、播客、讲座、YouTube 视频
• 生成字幕 —— SRT、VTT、ASS、LRC 或 TTML 广播标准字幕
• 识别说话人 —— 分离标记谁说了什么 (--diarize)
• 从 URL 转录 —— YouTube 链接和直接音频 URL（通过 yt-dlp 自动下载）
• 转录播客源 —— --rss <feed-url> 获取并转录剧集
• 批处理文件 —— 支持通配符模式、目录、跳过已存在文件；自动显示 ETA
• 本地语音转文本 —— 无 API 成本，可离线工作（模型下载后）
• 翻译成英文 —— 使用 --translate 将任何语言翻译成英文
• 多语言转录 —— 支持 99+ 种语言，自动检测
• 批量转录不同语言的文件 —— --language-map 为每个文件分配不同语言
• 转录多语言音频 —— --multilingual 用于混合语言音频
• 转录包含特定术语的音频 —— 使用 --initial-prompt 处理专业术语或需要留意的任何其他术语
• 预处理嘈杂音频（转录前） —— 转录前使用 --normalize 和 --denoise
• 流式输出 —— --stream 实时显示转录片段
• 剪辑时间范围 —— --clip-timestamps 转录特定部分
• 搜索转录本 —— --search "term" 查找单词/短语出现的所有时间戳
• 检测章节 —— --detect-chapters 从静默间隙查找章节断点
• 导出说话人音频 —— --export-speakers DIR 将每个说话人的发言保存为单独的 WAV 文件
• 电子表格输出 —— --format csv 生成带时间戳且正确引用的 CSV

触发短语：
"transcribe this audio", "convert speech to text", "what did they say", "make a transcript",
"audio to text", "subtitle this video", "who's speaking", "translate this audio", "translate to English",
"find where X is mentioned", "search transcript for", "when did they say", "at what timestamp",
"add chapters", "detect chapters", "find breaks in the audio", "table of contents for this recording",
"TTML subtitles", "DFXP subtitles", "broadcast format subtitles", "Netflix format",
"ASS subtitles", "aegisub format", "advanced substation alpha", "mpv subtitles",
"LRC subtitles", "timed lyrics", "karaoke subtitles", "music player lyrics",
"HTML transcript", "confidence-colored transcript", "color-coded transcript",
"separate audio per speaker", "export speaker audio", "split by speaker",
"transcript as CSV", "spreadsheet output", "transcribe podcast", "podcast RSS feed",
"different languages in batch", "per-file language",
"transcribe in multiple formats", "srt and txt at the same time", "output both srt and text",
"remove filler words", "clean up ums and uhs", "strip hesitation sounds", "remove you know and I mean",
"transcribe left channel", "transcribe right channel", "stereo channel", "left track only",
"wrap subtitle lines", "character limit per line", "max chars per subtitle",
"detect paragraphs", "paragraph breaks", "group into paragraphs", "add paragraph spacing"

⚠️ 智能体指导原则 —— 保持调用简洁：

核心规则：默认命令 (./scripts/transcribe audio.mp3) 是最快路径 —— 仅在用户明确要求某项功能时才添加对应标志。

转录：

• 仅当用户询问“谁说了什么”/“识别说话人”/“标记说话人”时，才添加 --diarize
• 仅当用户要求特定格式的字幕/字幕时，才添加 --format srt/vtt/ass/lrc/ttml
• 仅当用户要求 CSV 或电子表格输出时，才添加 --format csv
• 仅当用户需要词级时间戳时，才添加 --word-timestamps
• 仅当有特定领域术语需要引导时，才添加 --initial-prompt
• 仅当用户希望将非英语音频翻译成英语时，才添加 --translate
• 仅当用户提及音频质量差或噪音时，才添加 --normalize/--denoise
• 仅当用户希望对长文件进行实时/渐进式输出时，才添加 --stream
• 仅当用户需要特定时间范围时，才添加 --clip-timestamps
• 仅当模型在音乐/静默上产生幻觉时，才添加 --temperature 0.0
• 仅当 VAD 过度切割语音或包含噪音时，才添加 --vad-threshold
• 仅当你知道说话人数量时，才添加 --min-speakers/--max-speakers
• 仅当令牌未缓存在 ~/.cache/huggingface/token 时，才添加 --hf-token
• 仅当需要提高长片段字幕的可读性时，才添加 --max-words-per-line
• 仅当转录本包含明显伪影（音乐标记、重复）时，才添加 --filter-hallucinations
• 仅当用户要求句子级字幕提示时，才添加 --merge-sentences
• 仅当用户要求移除填充词（um、uh、you know、I mean、犹豫音）时，才添加 --clean-filler
• 仅当用户提及立体声轨道、双声道录音或要求特定声道时，才添加 --channel left|right
• 仅当用户指定每行字幕的字符限制（例如，“Netflix 格式”、“每行 42 个字符”）时，才添加 --max-chars-per-line N；优先级高于 --max-words-per-line
• 仅当用户要求段落分隔或结构化文本输出时，才添加 --detect-paragraphs；--paragraph-gap（默认 3.0 秒）仅在他们想要自定义间隔时使用
• 仅当用户提供真实姓名来替换 SPEAKER_1/2 时，才添加 --speaker-names "Alice,Bob" —— 始终需要 --diarize
• 仅当用户指定了 --initial-prompt 无法很好处理的特定罕见术语时，才添加 --hotwords WORDS；对于一般领域术语，优先使用 --initial-prompt
• 仅当用户确切知道音频开头的单词时，才添加 --prefix TEXT
• 仅当用户只想识别语言而不转录时，才添加 --detect-language-only
• 仅当用户要求性能统计、RTF 或基准信息时，才添加 --stats-file PATH
• 仅用于大型 CPU 批处理作业时，才添加 --parallel N；GPU 本身能高效处理单个文件 —— 不要为单个文件或小批量添加
• 仅当输入不可靠（URL、网络文件）且预期会出现瞬时故障时，才添加 --retries N
• 仅当用户明确要求将字幕嵌入/烧录到视频中时，才添加 --burn-in OUTPUT；需要 ffmpeg 和视频文件输入
• 仅当用户可能重新处理同一 URL 以避免重新下载时，才添加 --keep-temp
• 仅当用户在批处理模式下指定自定义命名模式时，才添加 --output-template
• 多格式输出 (--format srt,text)：仅当用户明确希望一次生成多种格式时使用；始终与 -o <dir> 配对使用
• 任何词级功能都会自动运行 wav2vec2 对齐（约 5-10 秒开销）
• --diarize 在此基础上增加约 20-30 秒

搜索：

• 仅当用户要求在音频中查找/定位/搜索特定单词或短语时，才添加 --search "term"
• --search 替换正常的转录本输出 —— 它只打印带时间戳的匹配片段
• 仅当用户提及近似/部分匹配或拼写错误时，才添加 --search-fuzzy
• 要将搜索结果保存到文件，请使用 -o results.txt

章节检测：

• 仅当用户要求章节、部分、目录或“话题在哪里改变”时，才添加 --detect-chapters
• 默认 --chapter-gap 8（8 秒静默 = 新章节）适用于大多数播客/讲座；对于密集内容可调低
• --chapter-format youtube（默认）输出 YouTube 就绪的时间戳；使用 json 用于编程用途
• 当章节与转录本输出结合时，始终使用 --chapters-file PATH —— 避免将章节标记混入转录本文本
• 如果用户只想要章节（不要转录本），请使用 -o /dev/null 将标准输出重定向到文件，并使用 --chapters-file
• 批处理模式限制： --chapters-file 接受单个路径 —— 在批处理模式下，每个文件的章节会覆盖前一个。对于批量章节检测，请省略 --chapters-file（章节在 === CHAPTERS (N) === 下打印到标准输出），或为每个文件单独运行

说话人音频导出：

• 仅当用户明确要求将每个说话人的音频单独保存时，才添加 --export-speakers DIR
• 始终与 --diarize 配对使用 —— 如果没有说话人标签，它会静默跳过
• 需要 ffmpeg；输出 SPEAKER_1.wav、SPEAKER_2.wav 等（如果设置了 --speaker-names，则使用真实姓名）

语言映射：

• 仅当用户在批处理模式下确认文件间语言不同时，才添加 --language-map
• 内联格式："interview*.mp3=en,lecture*.mp3=fr" —— 对文件名使用 fnmatch 通配符
• JSON 文件格式：@/path/to/map.json，其中文件内容为 {"pattern": "lang_code"}

RSS / 播客：

• 仅当用户提供播客 RSS 源 URL 时，才添加 --rss URL
• 默认获取最新的 5 个剧集；--rss-latest 0 获取所有；--skip-existing 安全恢复
• 始终与 -o <dir> 一起使用 --rss —— 没有它，所有剧集转录本会连接打印到标准输出，难以使用；设置 -o <dir> 后，每个剧集都有自己的文件

智能体中继的输出格式：

• 搜索结果 (--search) → 直接打印给用户；输出是人类可读的
• 章节输出 → 如果没有 --chapters-file，章节会出现在转录本后的 === CHAPTERS (N) === 标题下的标准输出中；使用 --format json 时，章节也嵌入在 JSON 的 "chapters" 键下
• 字幕格式 (SRT, VTT, ASS, LRC, TTML) → 始终写入 -o 文件；告诉用户输出路径，切勿粘贴原始字幕内容
• 数据格式 (CSV, HTML, TTML, JSON) → 始终写入 -o 文件；告诉用户输出路径，不要粘贴原始 XML/CSV/HTML
• ASS 格式 → 用于 Aegisub、VLC、mpv；写入文件并告诉用户可以在 Aegisub 中打开或在 VLC/mpv 中播放
• LRC 格式 → 用于音乐播放器（Foobar2000、AIMP、VLC）的定时歌词；写入文件
• 多格式 (--format srt,text) → 需要 -o <dir>；每种格式写入单独的文件；告诉用户所有写入的路径
• JSON 格式 → 适用于编程后处理；不适合完整粘贴给用户
• 文本/转录本 → 对于短文件可直接安全显示给用户；对于长文件进行总结
• 统计输出 (--stats-file) → 为用户总结关键字段（时长、处理时间、RTF），而不是粘贴原始 JSON
• 语言检测 (--detect-language-only) → 直接打印结果；它是单行
• ETA 在批处理作业中自动打印到 stderr；无需额外操作

何时不使用：

• 没有本地计算能力的纯云端环境
• 小于 10 秒的文件，API 调用延迟无关紧要

faster-whisper 与 whisperx：
此技能涵盖了 whisperx 的所有功能 —— 说话人分离 (--diarize)、词级时间戳 (--word-timestamps)、SRT/VTT 字幕 —— 因此不需要 whisperx。仅当你特别需要其 pyannote 管道或此处未涵盖的批处理 GPU 功能时，才使用 whisperx。

快速参考