haoyiyin/easy-subtitle

使用时机

当用户需要以下操作时使用本技能：

• 从音频或视频文件生成SRT字幕（离线，无需API调用）
• 自动检测媒体文件中的口语语言
• 通过提供的原始口播文本纠正Whisper转写错误
• 批量处理媒体文件生成字幕

不要在以下场景使用：

• 实时/在线转录（faster-whisper仅支持离线/批处理）
• 需要非SRT格式输出（仅支持SRT）
• 基于云的转录（本技能纯本地运行）

操作步骤

1. 安装依赖：pip install faster-whisper。根据操作系统安装ffmpeg：
   • macOS：brew install ffmpeg
   • Linux：sudo apt install ffmpeg（Debian/Ubuntu）或 sudo dnf install ffmpeg（Fedora）
   • Windows：choco install ffmpeg（Chocolatey）或 scoop install ffmpeg（Scoop），或从 https://ffmpeg.org 下载
2. 确保 easy-subtitle 包已安装：在项目根目录下运行 pip install -e .。
3. 基本转录：运行 easy-subtitle -i video.mp4 生成 video.srt，会自动检测语言。
4. 指定语言：如果已知语言，运行 easy-subtitle -i audio.wav -l zh（比自动检测更快更准确）。
5. 使用原始文本纠正：运行 easy-subtitle -i video.mp4 --original-text script.txt，通过提供的脚本来对齐并纠正转写结果。
6. 调整模型大小：使用 -m small 提高速度，或 -m large-v3 提高准确率。默认为 medium。
7. 调整VAD：使用 --vad-min-silence 1000 进行更积极的静音分割（适用于更安静的内容）。使用 --no-vad 禁用VAD。

常见陷阱

• 首次运行需要下载模型（medium约1.5GB）—请预留额外时间和磁盘空间。
• Whisper自动语言检测对非常短的片段（<5秒）不可靠—请手动使用 -l 指定语言。
• 原始文本对齐在脚本与音频完全一致时效果最佳。即兴内容、停顿和即兴发挥将保留为Whisper的输出。
• faster-whisper在CPU上默认使用INT8量化—速度快，但比GPU上的FP16稍不准确。
• ffmpeg必须单独安装（不是Python包）。
  • macOS：brew install ffmpeg
  • Linux：sudo apt install ffmpeg
  • Windows：choco install ffmpeg 或从 https://ffmpeg.org 下载

验证

1. 运行 easy-subtitle --version 确认安装成功。
2. 测试基本转录：easy-subtitle -i test_audio.mp3 -m tiny 应快速生成一个.srt文件。
3. 验证SRT输出：在视频播放器中打开，或检查是否包含带 HH:MM:SS,mmm --> HH:MM:SS,mmm 时间戳的编号块。
4. 测试原始文本对齐：提供一个与音频匹配的脚本—输出应包含确切的脚本文本，而不是Whisper的转写结果。