高精度 SRT 字幕生成工具

一個基於 Whisper 和 Gemini 的高精度 SRT 字幕生成工具，支援本地和雲端 API，具備 VAD 語音檢測和智能重新斷句功能。

✨ 特色功能

• 🎯 高精度時間戳：使用 Silero VAD 進行精確語音檢測
• 🤖 多種 ASR 選擇：支援本地 Whisper 和 OpenAI Whisper API
• 🧠 智能重新斷句：可選 Gemini AI 重新分段優化
• ⚡ GPU 加速：自動檢測並使用 GPU 加速
• 🔧 時間軸補償：支援累積漂移補償
• 📝 標準 SRT 格式：完全符合 SRT 標準，支援 UTF-8 BOM

🚀 快速開始

環境需求

• Python 3.10+
• FFmpeg
• CUDA（可選，用於 GPU 加速）

安裝步驟

1. 克隆專案

git clone <repository-url>
cd ai_learning_vid_generating

2. 建立虛擬環境

python -m venv whisper_srt_env
# Windows
.\whisper_srt_env\Scripts\Activate.ps1
# Linux/Mac
source whisper_srt_env/bin/activate

3. 安裝依賴

pip install -r requirements.txt

4. 設定環境變數（可選）

# 建立 .env 檔案
OPENAI_API_KEY=your_openai_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here

基本用法

# 基本使用（本地 Whisper）
python whisper_srt.py -i video.mp4

# 使用 OpenAI API
python whisper_srt.py -i audio.wav --api openai

# 使用 Gemini 重新斷句
python whisper_srt.py -i video.mp4 --resegment gemini

# 完整參數範例
python whisper_srt.py -i video.mp4 \
    --api local \
    --model large-v3 \
    --resegment gemini \
    --language zh \
    --compensate-rate 0.5/10 \
    --output-dir ./output \
    --verbose

📋 命令行參數

必要參數

• -i, --input: 輸入音訊或影片檔案路徑

輸出設定

• -o, --output-dir: 輸出目錄（預設：./output）

API 設定

• --api: Whisper API 類型（local/openai，預設：local）
• --model: Whisper 模型名稱（預設：large-v3）

重新斷句

• --resegment: 重新斷句方式（gemini/none，預設：none）
• --gemini-key: Gemini API 金鑰（可選）

VAD 設定

• --vad-threshold: VAD 閾值（預設：0.5）
• --vad-min-silence: VAD 最小靜默時間（預設：0.2）

其他選項

• --compensate-rate: 時間軸補償比率（格式：秒數/分鐘數）
• --language: 語言代碼（預設：auto）
• --gpu: GPU 設備編號（預設：0）
• --fp16: 啟用 FP16 精度
• --verbose: 詳細輸出

🔧 配置說明

支援的檔案格式

• 音訊：mp3, wav, m4a, flac, aac, m4b
• 影片：mp4, mov, avi, mkv, webm

精度要求

• 字幕臨界點誤差：≤ ±200ms
• 整檔累積漂移：≤ ±1s/60min
• 每段字幕最大時長：6 秒
• 每行最大字元數：42 字元

API 金鑰設定

1. OpenAI API：

   • 註冊 OpenAI 帳號並取得 API 金鑰
   • 設定環境變數 OPENAI_API_KEY

2. Gemini API：

   • 前往 Google AI Studio 取得 API 金鑰
   • 設定環境變數 GEMINI_API_KEY

📁 專案結構

ai_learning_vid_generating/
├── whisper_srt.py          # 主程式
├── src/                    # 核心模組
│   ├── config.py          # 配置管理
│   ├── utils.py           # 工具函數
│   ├── audio_processor.py # 音訊處理
│   ├── vad.py             # VAD 語音檢測
│   ├── asr.py             # 語音識別
│   ├── resegment.py       # Gemini 重新斷句
│   └── srt_processor.py   # SRT 處理
├── tests/                  # 測試檔案
├── logs/                   # 日誌檔案
├── output/                 # 輸出目錄
├── temp/                   # 臨時檔案
├── requirements.txt        # 依賴列表
└── README.md              # 說明文件

🧪 測試

# 執行測試
pytest tests/

# 執行測試並顯示覆蓋率
pytest tests/ --cov=src

⚠️ 常見問題

1. FFmpeg 未找到

問題：未找到 FFmpeg，請確保已安裝並在 PATH 中

解決方案：

• Windows：下載 FFmpeg 並添加到 PATH
• Linux：sudo apt install ffmpeg
• Mac：brew install ffmpeg

2. CUDA 記憶體不足

問題：GPU 記憶體不足

解決方案：

• 使用較小的 Whisper 模型（如 base 或 small）
• 添加 --fp16 參數減少記憶體使用
• 使用 CPU 模式：確保沒有可用的 CUDA

3. API 金鑰錯誤

問題：API 金鑰無效或未設定

解決方案：

• 檢查 .env 檔案中的金鑰設定
• 確認金鑰有效且有足夠額度
• 使用 --gemini-key 或環境變數直接指定

4. 字幕時間不準確

問題：字幕與語音不同步

解決方案：

• 調整 VAD 參數：--vad-threshold 和 --vad-min-silence
• 使用時間軸補償：--compensate-rate 0.5/10
• 嘗試不同的 Whisper 模型

📊 效能優化

GPU 使用

• 確保安裝了 CUDA 和 PyTorch GPU 版本
• 使用 --fp16 參數啟用半精度浮點數
• 監控 GPU 記憶體使用情況

處理速度

• 本地 Whisper：GPU > CPU，large-v3 > base
• OpenAI API：網路速度影響較大
• VAD 預處理可顯著提升整體效率

🤝 貢獻指南

1. Fork 專案
2. 建立功能分支：git checkout -b feature/new-feature
3. 提交變更：git commit -am 'Add new feature'
4. 推送分支：git push origin feature/new-feature
5. 建立 Pull Request

📄 授權條款

本專案採用 MIT 授權條款。詳見 LICENSE 檔案。

🙏 致謝

• OpenAI Whisper - 語音識別模型
• Silero VAD - 語音活動檢測
• Google Gemini - 智能重新斷句
• FFmpeg - 音訊處理

---

如有問題或建議，請建立 Issue 或聯繫維護者。