🎬 Subtitle Creator

自動字幕生成工具 - 從影片到多語言字幕

✨ 功能特色

• 🎤 多模型支援:
  • Qwen3-ASR-0.6B (推薦) - 支援 52 種語言，輕量高效
  • Qwen3-ASR-1.7B - 更高準確度
  • WhisperX - 基於 Whisper，支援 word-level timestamps
• ⏱️ 精準時間軸: 使用 ForcedAligner 獲得字/詞級別時間戳
• 🎌 強制語言指定: 可強制指定來源語言避免誤判
• 📹 長影片支援: 自動分段處理，支援任意長度影片
• 🐳 Docker 支援: 完整容器化，支援 GPU 加速

📊 測試結果

在 RTX 3060 Laptop (6GB VRAM) 上的測試結果：

配置	單次處理長度	處理速度
Qwen3-ASR-0.6B + ForcedAligner	3 分鐘	~20秒/3分鐘音訊
Qwen3-ASR-1.7B (無 Aligner)	2 分鐘	~78秒/分鐘音訊

🚀 快速開始

方法一：使用 Docker (推薦)

# 1. 建置 Docker 映像
docker build -t subtitle-creator:qwen .

# 2. 下載模型（在 Docker 內執行）
docker run --rm --gpus all \
  -v $(pwd)/models:/models \
  -e HF_HOME=/models/hf_cache \
  --entrypoint python \
  subtitle-creator:qwen -c "
from huggingface_hub import snapshot_download
snapshot_download('Qwen/Qwen3-ASR-0.6B', local_dir='/models/Qwen3-ASR-0.6B')
snapshot_download('Qwen/Qwen3-ForcedAligner-0.6B', local_dir='/models/Qwen3-ForcedAligner-0.6B')
"

# 3. 測試單一片段（3分鐘）
docker run --rm --gpus all \
  --entrypoint python \
  -v $(pwd):/app \
  -v $(pwd)/models:/models \
  -v $(pwd)/test/output:/data/output \
  -e HF_HOME=/models/hf_cache \
  subtitle-creator:qwen /app/test_qwen.py \
  --video /app/test/videos/YOUR_VIDEO.mkv \
  --start 60 --duration 180 \
  --model-dir /models \
  --language Japanese \
  --output /data/output/test.srt

# 4. 處理完整影片（自動分段）
docker run --rm --gpus all \
  --entrypoint python \
  -v $(pwd):/app \
  -v $(pwd)/models:/models \
  -v $(pwd)/test/output:/data/output \
  -e HF_HOME=/models/hf_cache \
  subtitle-creator:qwen /app/test_full_video.py \
  --video /app/test/videos/YOUR_VIDEO.mkv \
  --output /data/output/full.srt \
  --model-dir /models \
  --language Japanese

方法二：本地安裝

# 安裝依賴
pip install -e .
pip install qwen-asr

# 執行
python test_qwen.py --video ./videos/test.mkv --language Japanese

📋 系統需求

• Python 3.11+
• NVIDIA GPU (建議 6GB+ VRAM)
• CUDA 12.1+
• FFmpeg

🎯 支援語言

Qwen3-ASR 支援的語言 (52種)

• 主要語言: 中文、英文、日文、韓文、法文、德文、西班牙文、葡萄牙文等
• 亞洲語言: Japanese, Chinese, Korean, Thai, Vietnamese, Indonesian, Malay, Filipino
• 歐洲語言: English, French, German, Spanish, Portuguese, Italian, Dutch, Russian, Polish, Czech, etc.

語言代碼

使用 --language 參數時，請使用英文名稱：

• Japanese - 日文
• Chinese - 中文
• English - 英文
• French - 法文
• Korean - 韓文

📁 專案結構

subtitle-creator/
├── src/subtitle_creator/
│   ├── cli.py              # CLI 命令
│   ├── config.py           # 配置管理
│   └── core/
│       ├── extractor.py    # 音訊擷取 (FFmpeg)
│       ├── transcriber.py  # WhisperX 轉錄
│       ├── transcriber_qwen.py  # Qwen3-ASR 轉錄
│       ├── writer.py       # SRT 輸出
│       └── pipeline.py     # 整合管線
├── test_qwen.py            # Qwen3-ASR 單段測試
├── test_full_video.py      # 全長影片處理
├── models/                 # 本地模型目錄 (需自行下載)
├── Dockerfile
└── pyproject.toml

🔧 配置選項

test_qwen.py 參數

參數	說明	預設值
--video	影片路徑	必填
--start	起始時間（秒）	0
--duration	處理時長（秒）	60
--language	強制語言	None (自動偵測)
--model-dir	模型目錄	None
--output	輸出 SRT 路徑	/data/output/qwen_test.srt

test_full_video.py 參數

參數	說明	預設值
--video	影片路徑	必填
--output	輸出 SRT 路徑	必填
--model-dir	模型目錄	必填
--language	強制語言	Japanese
--segment-duration	每段時長（秒）	180
--start	起始時間（秒）	0
--end	結束時間（秒）	影片結尾

📝 開發筆記

目前狀態

• ✅ Qwen3-ASR-0.6B 整合完成
• ✅ ForcedAligner 時間戳支援
• ✅ 強制語言指定功能
• ✅ 長影片分段處理
• ✅ SRT 輸出
• ✅ WhisperX 整合 (已測試)
• ⚠️ CLI 命令 (基本實作)
• ⚠️ 翻譯功能 (基本實作，待完善)

已知問題與解決方案

1. PyTorch 2.6+ weights_only 限制

   • 問題: 載入舊模型時報錯
   • 解決: 在 __init__.py 中加入 monkey patch

2. GPU 記憶體限制 (6GB)

   • 問題: 長音訊導致 OOM
   • 解決: 使用 0.6B 模型 + 分段處理（每段 3 分鐘）

3. 語言誤判

   • 問題: 日文被誤判為中文
   • 解決: 使用 --language Japanese 強制指定

效能評估

GPU 記憶體	推薦配置	單次處理長度
6GB	0.6B + Aligner	3 分鐘
8GB	1.7B + Aligner	3-5 分鐘
12GB+	1.7B + Aligner	5-10 分鐘

📄 授權

MIT License