feat: update Python processors and add utility scripts

- Update ASR, face, OCR, pose processors - Add release pre-flight check script - Add synonym generation, chunk processing scripts - Add face recognition, stamp search utilities
2026-04-30 15:07:49 +08:00
parent f4697396e4
commit 8f05a7c188
256 changed files with 60505 additions and 299 deletions
--- a/scripts/FACE_ASR_INTEGRATION_GUIDE.md
+++ b/scripts/FACE_ASR_INTEGRATION_GUIDE.md
@@ -0,0 +1,294 @@
+# Face + ASR 整合使用指南
+
+## 概述
+
+由於 ASRX（說話人分離）目前存在 PyTorch 2.6 兼容性問題，我們使用 **Face 檢測 + ASR 轉錄** 的整合方案來識別「誰在什麼時候說話」。
+
+---
+
+## 工作流程
+
+```
+影片 → Face 檢測 → face_output.json
+           ↓
+           ├─→ 整合工具 → integrated_output.json
+           ↓
+影片 → ASR 轉錄 → asr_output.json
+```
+
+---
+
+## 使用步驟
+
+### 步驟 1：Face 檢測
+
+```bash
+# 標準模式（推薦）
+python3 scripts/face_processor_optimized.py \
+  video.mp4 \
+  face_output.json \
+  --sample-interval 15
+
+# 快速模式
+python3 scripts/face_processor.py \
+  video.mp4 \
+  face_output.json
+
+# 精細模式
+python3 scripts/face_processor_optimized.py \
+  video.mp4 \
+  face_output.json \
+  --sample-interval 10
+```
+
+**參數說明**：
+- `--sample-interval 15`：每 15 幀檢測一次（推薦）
+- `--sample-interval 10`：每 10 幀檢測一次（更準確但更慢）
+- `--sample-interval 30`：每 30 幀檢測一次（快速）
+
+---
+
+### 步驟 2：ASR 轉錄
+
+```bash
+# 使用 small 模型（台灣腔調優化）
+python3 scripts/asr_processor_small.py \
+  video.mp4 \
+  asr_output.json
+```
+
+---
+
+### 步驟 3：整合結果
+
+```bash
+python3 scripts/integrate_face_asrx.py \
+  face_output.json \
+  asr_output.json \
+  integrated_output.json \
+  --threshold 1.0
+```
+
+**參數說明**：
+- `--threshold 1.0`：時間戳配對閾值（秒）
+  - 較小值（0.5）：更嚴格，匹配較少
+  - 較大值（2.0）：更寬鬆，匹配較多
+  - 推薦：1.0 秒
+
+---
+
+## 輸出格式
+
+```json
+{
+  "integration_time": "2026-04-02T00:00:00",
+  "face_source": "face_output.json",
+  "asrx_source": "asr_output.json",
+  "time_threshold": 1.0,
+  "integrated_segments": [
+    {
+      "start": 0.0,
+      "end": 2.0,
+      "text": "正常來講就是剪輯師用完之後",
+      "speaker_id": null,
+      "face_detected": true,
+      "face": {
+        "x": 233,
+        "y": 84,
+        "width": 77,
+        "height": 77,
+        "confidence": 0.8
+      },
+      "time_diff": 0.5
+    }
+  ],
+  "stats": {
+    "total_segments": 83,
+    "segments_with_face": 55,
+    "segments_without_face": 28,
+    "face_match_rate": 0.66,
+    "total_faces_detected": 153
+  }
+}
+```
+
+---
+
+## 測試結果
+
+### ExaSAN 短影片（2.6 分鐘）
+
+| 指標 | 結果 |
+|------|------|
+| **ASR 片段** | 83 段 |
+| **Face 檢測** | 153 幀 |
+| **匹配成功** | 55 段 |
+| **匹配率** | 66.3% |
+| **無臉片段** | 28 段 |
+
+### 分析
+
+**66.3% 匹配率**：
+- ✅ 約 2/3 的說話內容可檢測到人臉
+- ⚠️ 1/3 的內容無人臉（可能是：
+  - 說話者不在鏡頭內
+  - 採樣間隔錯過
+  - 側面/低頭無法檢測
+  - 多人場景
+
+---
+
+## 優化建議
+
+### 提高匹配率
+
+**1. 減少採樣間隔**
+```bash
+# 從 15 改為 10
+python3 scripts/face_processor_optimized.py \
+  video.mp4 face_output.json \
+  --sample-interval 10
+```
+**效果**：匹配率可提升至 70-75%
+**代價**：處理時間增加 50%
+
+**2. 增加時間閾值**
+```bash
+python3 scripts/integrate_face_asrx.py \
+  face.json asr.json output.json \
+  --threshold 2.0
+```
+**效果**：匹配率提升
+**代價**：可能配對錯誤的說話者
+
+**3. 使用多人臉追蹤**（未來功能）
+- 添加 face_id 追蹤
+- 區分不同說話者
+- 需要額外模型（MediaPipe 或 DeepFace）
+
+---
+
+## 使用場景
+
+### ✅ 適合場景
+
+- **單人鏡頭**：採訪、演講
+- **雙人對話**：訪談、會議
+- **紀錄片**：旁白 + 訪談
+- **教學影片**：講師講解
+
+### ⚠️ 限制場景
+
+- **多人會議**：無法區分多個說話者
+- **快速切換**：可能錯過說話者
+- **側面/低頭**：臉檢測失敗
+- **遠距離**：臉太小無法檢測
+
+---
+
+## 批次處理
+
+```bash
+#!/bin/bash
+# batch_integrate.sh
+
+VIDEO_DIR="/path/to/videos"
+OUTPUT_DIR="/path/to/output"
+
+for video in "$VIDEO_DIR"/*.mp4; do
+    basename=$(basename "$video" .mp4)
+    
+    echo "Processing $basename..."
+    
+    # Face detection
+    python3 scripts/face_processor_optimized.py \
+      "$video" \
+      "$OUTPUT_DIR/${basename}_face.json"
+    
+    # ASR transcription
+    python3 scripts/asr_processor_small.py \
+      "$video" \
+      "$OUTPUT_DIR/${basename}_asr.json"
+    
+    # Integration
+    python3 scripts/integrate_face_asrx.py \
+      "$OUTPUT_DIR/${basename}_face.json" \
+      "$OUTPUT_DIR/${basename}_asr.json" \
+      "$OUTPUT_DIR/${basename}_integrated.json"
+    
+    echo "Done: $basename"
+done
+```
+
+---
+
+## 效能基準
+
+### 短影片（2-3 分鐘）
+
+| 步驟 | 時間 | 備註 |
+|------|------|------|
+| Face 檢測 | ~65s | 採樣間隔 15 |
+| ASR 轉錄 | ~50s | small 模型 |
+| 整合 | ~1s | 純 JSON 處理 |
+| **總計** | **~116s** | 可並行處理 |
+
+### 長影片（114 分鐘）
+
+| 步驟 | 時間 | 備註 |
+|------|------|------|
+| Face 檢測 | ~25min | 採樣間隔 15 |
+| ASR 轉錄 | ~15min | small 模型 |
+| 整合 | ~5s | 純 JSON 處理 |
+| **總計** | **~40min** | 7.3x 實時 |
+
+---
+
+## 常見問題
+
+### Q1: 匹配率太低（<50%）怎麼辦？
+
+**A**: 
+1. 減少採樣間隔（15 → 10）
+2. 增加時間閾值（1.0 → 2.0）
+3. 檢查影片品質（光線、解析度）
+
+### Q2: 為什麼沒有 speaker_id？
+
+**A**: 
+目前 ASRX（說話人分離）有 PyTorch 2.6 兼容性問題。
+解決方案：
+- 使用 Face 檢測替代（目前方案）
+- 降級 PyTorch 到 2.5
+- 等待 whisperx 更新
+
+### Q3: 如何區分多個說話者？
+
+**A**:
+目前限制：
+- 無法自動區分多個說話者
+- 需要人臉追蹤功能（未來）
+- 可手動標記或使用其他工具
+
+---
+
+## 檔案清單
+
+```
+scripts/
+├── face_processor.py                    # Face 檢測（原版）
+├── face_processor_optimized.py          # Face 檢測（優化版）⭐
+├── asr_processor_small.py               # ASR 轉錄（small 模型）⭐
+├── integrate_face_asrx.py               # 整合工具 ⭐
+├── FACE_ASR_INTEGRATION_GUIDE.md        # 本文件
+└── FACE_ASRX_CHALLENGE_REPORT.md        # 技術挑戰報告
+```
+
+---
+
+## 聯絡與反饋
+
+如有問題或建議，請參考：
+- 整合工具說明：`python3 scripts/integrate_face_asrx.py --help`
+- Face 優化說明：`python3 scripts/face_processor_optimized.py --help`
+- ASR 使用指南：`scripts/ASR_USAGE.md`