语音转文字（Speech-to-Text）

从任意 URL 下载音频，并使用 Faster-Whisper 将其转录为文本。

处理流程

一条命令完成全部操作：

python scripts/transcribe.py "https://example.com/audio-url"

• 通过 yt-dlp 下载音频（支持 1000+ 个网站）
• 转换为 16kHz 单声道 WAV 格式，确保最佳质量
• 使用 Faster-Whisper（基于 CTranslate2 加速）进行转录
• 输出纯文本

可选参数

使用示例

# 默认配置（base 模型，中文）
python scripts/transcribe.py "https://www.xiaoyuzhoufm.com/episode/xxx"

# 英文音频，使用 small 模型
python scripts/transcribe.py "https://youtube.com/watch?v=xxx" -l en -m small

# 仅下载音频（保存音频文件）
python scripts/transcribe.py "https://youtube.com/watch?v=xxx" --download-only -o "D:audio"

# 高质量转录（medium 模型，GPU 上使用 float16 量化）
python scripts/transcribe.py "https://example.com/podcast.mp3" -m medium -q float16

系统架构

URL → yt-dlp（下载） → ffmpeg（转为 16kHz 单声道 WAV） → Faster-Whisper（转录） → text

• 下载：使用 yt-dlp 提取直链音频地址并完成下载
• 预处理：使用 ffmpeg 将音频转换为 Whisper 所需格式（16kHz 单声道）
• 模型：Faster-Whisper（基于 CTranslate2）——速度比 openai-whisper 快 2–4 倍，可在 CPU 上运行
• VAD：语音活动检测（Voice Activity Detection），自动过滤非语音片段

依赖项

首次运行时将自动安装：

• faster-whisper — 转录引擎
• yt-dlp — 音频提取工具

如需手动预安装，请执行：

pip install faster-whisper yt-dlp

模型规格

首次运行时将从 HuggingFace（中国用户使用 HF 镜像站）下载对应模型。

运行环境

• 自动选择 GPU/CPU 后端（若 torch.cuda.is_available() 为真，则启用 cuda）
• HF 镜像地址：https://hf-mirror.com（已为中国用户预配置）
• 模型缓存路径：.models/（位于 scripts 目录下；若已存在 fast-whisper 技能缓存，则复用该缓存）
• ffmpeg 检查路径：系统 PATH 中的可执行文件，或固定路径 D:softffmpeg...binffmpeg.exe

离线环境 / 网络受限场景

若网络无法访问 HuggingFace，请参阅 references/install-offline.md，了解如何预先下载模型及在无互联网连接环境中部署使用。