ezstt — 本地批量音视频字幕生成工具

基于 Qwen3-ASR 的离线批量转录工具。输入一个文件或目录，输出 SRT 字幕或 TXT 纯文本。全部在本地运行，无需网络。

特性

• 极速：Apple Silicon M5 Pro 上 8.6 分钟视频仅需 8.8 秒（58 倍实时）
• 跨平台：Apple Silicon (MLX) + 全平台 (sherpa-onnx)
• 标准输出：SRT 字幕格式，可直接用于 FFmpeg 软/硬字幕
• 断点续传：已处理文件自动跳过
• 多模型：支持 6 种 Qwen3-ASR 量化版本

快速开始

需要 Python 3.10+ 和 FFmpeg。

git clone https://github.com/chaoshou-coder/ezstt.git
cd ezstt

Apple Silicon Mac (推荐，最快)

uv sync --extra mlx
uv run ezstt path/to/video.mp4

其他平台 (Linux/Windows/Intel Mac)

uv sync --extra sherpa
# 下载 sherpa-onnx 模型到 third_party/models/
uv run ezstt path/to/video.mp4 --backend sherpa-onnx

CLI 参数

ezstt [--version] [--lang LANG] [--format FORMAT]
      [--timestamp-in-txt] [--output-dir OUTPUT_DIR]
      [--no-skip-existing] [--backend BACKEND]
      [--model-size MODEL_SIZE] [--dry-run] [--interactive]
      [input_path]

参数	说明	默认值
input_path	输入文件或目录	（交互输入）
--lang	语言代码 (zh/en/ja/...) 或 auto	auto
--format	输出格式: srt 或 srt,txt	srt
--timestamp-in-txt	TXT 输出包含时间戳	False
--output-dir	输出目录	与源文件同级
--no-skip-existing	不跳过已有输出	False
--backend	STT 后端: mlx 或 sherpa-onnx	mlx
--model-size	模型大小 (仅 mlx)	0.6B-4bit
--dry-run	仅预览不执行	False
--interactive, -i	交互模式	False

后端对比

后端	平台	速度 (M5 Pro)	状态
mlx (Qwen3-ASR)	Apple Silicon	58x 实时	✅ 默认
sherpa-onnx (Qwen3-ASR)	全平台	~2x 实时	✅

项目结构

ezstt/
├── cli/main.py          # CLI 入口（交互 + 命令行）
├── core/
│   ├── protocol.py      # SttRunner Protocol 接口
│   └── orchestrator.py  # 批量编排器
├── runners/
│   ├── mlx_qwen3.py     # Qwen3 ASR (MLX) — Apple Silicon
│   └── sherpa_onnx.py   # Qwen3 ASR (ONNX) — 跨平台
├── media/extract.py     # ffmpeg 音频提取
├── output/
│   ├── writer.py        # SRT/TXT 原子写入
│   └── paths.py         # 文件扫描 + 路径计算
└── hardware/detect.py   # CPU/CUDA/Metal 设备检测

开发

# 运行测试
uv run pytest tests/ -v

# 性能基准测试
uv run python benchmark.py

License

MIT