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 的轉錄結果。