# 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`