Files

Warren 8f05a7c188 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

6.2 KiB

Raw Permalink Blame History

Face + ASR 整合使用指南

概述

由於 ASRX（說話人分離）目前存在 PyTorch 2.6 兼容性問題，我們使用 Face 檢測 + ASR 轉錄 的整合方案來識別「誰在什麼時候說話」。

工作流程

影片 → Face 檢測 → face_output.json
           ↓
           ├─→ 整合工具 → integrated_output.json
           ↓
影片 → ASR 轉錄 → asr_output.json

使用步驟

步驟 1：Face 檢測

# 標準模式（推薦）
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 轉錄

# 使用 small 模型（台灣腔調優化）
python3 scripts/asr_processor_small.py \
  video.mp4 \
  asr_output.json

步驟 3：整合結果

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 秒

輸出格式

{
  "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. 減少採樣間隔

# 從 15 改為 10
python3 scripts/face_processor_optimized.py \
  video.mp4 face_output.json \
  --sample-interval 10

效果：匹配率可提升至 70-75% 代價：處理時間增加 50%

2. 增加時間閾值

python3 scripts/integrate_face_asrx.py \
  face.json asr.json output.json \
  --threshold 2.0

效果：匹配率提升代價：可能配對錯誤的說話者

3. 使用多人臉追蹤（未來功能）

添加 face_id 追蹤
區分不同說話者
需要額外模型（MediaPipe 或 DeepFace）

使用場景

✅ 適合場景

單人鏡頭：採訪、演講
雙人對話：訪談、會議
紀錄片：旁白 + 訪談
教學影片：講師講解

⚠️ 限制場景

多人會議：無法區分多個說話者
快速切換：可能錯過說話者
側面/低頭：臉檢測失敗
遠距離：臉太小無法檢測

批次處理

#!/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%）怎麼辦？

減少採樣間隔（15 → 10）
增加時間閾值（1.0 → 2.0）
檢查影片品質（光線、解析度）

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

6.2 KiB Raw Permalink Blame History Unescape Escape