# Integrated Player 使用指南

## 功能

整合播放器可以同時顯示：
- **ASR**: 文字字幕
- **Face**: 人臉檢測框和截圖
- **Self ASRX**: 說話人 ID + 演員名 + 角色名
- **Pose**: 嘴部關鍵點動作

## 編譯

```bash
cargo build --bin integrated_player
```

## 使用方式

### 🎬 自動演示模式（新功能）

最簡單的方式，自動播放所有說話人的片段：

```bash
# 快速演示（推薦）
./run_demo.sh --quick

# 標準演示
./run_demo.sh

# 自定義演示
./target/debug/integrated_player \
  --video /tmp/charade_audio.wav \
  --asrx /tmp/asrx_charade_optimized.json \
  --demo \
  --demo-segments-per-speaker 5 \
  --demo-speed 1.5
```

**演示參數**：
- `--demo`: 啟用自動演示模式
- `--demo-segments-per-speaker`: 每個說話人演示的片段數（默認 3）
- `--demo-speed`: 演示速度倍數（默認 2.0）

**演示特點**：
- ✅ 自動播放所有說話人
- ✅ 顯示演員名和角色名
- ✅ 可調整播放速度
- ✅ 適合展示和測試

### 基本用法

```bash
./target/debug/integrated_player \
  --video /path/to/video.mp4 \
  --asr /path/to/asr.json \
  --face /path/to/face.json \
  --asrx /path/to/asrx.json \
  --pose /path/to/pose.json
```

### 短參數

```bash
./target/debug/integrated_player \
  -v video.mp4 \
  -r asr.json \
  -f face.json \
  -x asrx.json \
  -p pose.json
```

### 自動播放特定說話人

```bash
./target/debug/integrated_player \
  --video /tmp/charade_audio.wav \
  --asrx /tmp/asrx_charade_optimized.json \
  --auto-play-speaker \
  --speaker-name SPEAKER_0
```

## 交互命令

進入交互模式後，可以使用以下命令：

- `<時間>`: 跳轉到指定時間（秒）
  - 示例: `300.5` 跳轉到 5分30秒

- `s` 或 `show`: 顯示當前時間的整合信息
  - 顯示文字、說話人、人臉、嘴部動作

- `l` 或 `list`: 列出所有說話人統計
  - 顯示說話人 ID、演員名、角色名、片段數、總時長

- `p <說話人ID>`: 播放該說話人的片段
  - 示例: `p SPEAKER_1` 播放 SPEAKER_1 的片段

- `q` 或 `quit` 或 `exit`: 退出播放器

## 數據格式

### ASR 格式

```json
{
  "language": "en",
  "segments": [
    {
      "start": 60.0,
      "end": 62.0,
      "text": "You"
    }
  ]
}
```

### Face 格式

```json
{
  "results": {
    "detections": [
      {
        "frame": 554,
        "timestamp": 23.08,
        "x": 78,
        "y": 88,
        "width": 74,
        "height": 74,
        "confidence": 1.0
      }
    ]
  }
}
```

### ASRX 格式

```json
{
  "segments": [
    {
      "index": 0,
      "start": 1.8,
      "end": 2.6,
      "duration": 0.8,
      "speaker": "SPEAKER_5"
    }
  ],
  "speaker_stats": {
    "SPEAKER_0": {
      "count": 654,
      "duration": 1766.5
    }
  }
}
```

### Pose 格式

```json
{
  "frames": [
    {
      "frame": 12,
      "timestamp": 0.545,
      "persons": [
        {
          "keypoints": [
            {
              "name": "mouth",
              "x": 100.5,
              "y": 50.2,
              "confidence": 0.85
            }
          ],
          "bbox": {
            "x": 90,
            "y": 40,
            "width": 20,
            "height": 30
          }
        }
      ]
    }
  ]
}
```

## 測試案例

### Charade 1963 (114.7 分鐘)

```bash
# 準備數據
export VIDEO=/tmp/charade_audio.wav
export ASRX=/tmp/asrx_charade_optimized.json
export FACE=/tmp/face_long.json
export INTEGRATED=/tmp/charade_integrated.json

# 播放 SPEAKER_0 (Cary Grant)
./target/debug/integrated_player \
  --video $VIDEO \
  --asrx $ASRX \
  --face $FACE \
  --auto-play-speaker \
  --speaker-name SPEAKER_0

# 交互模式
./target/debug/integrated_player \
  --video $VIDEO \
  --asrx $ASRX

# 進入後輸入:
# l - 列出說話人
# p SPEAKER_1 - 播放 Audrey Hepburn
# s - 顯示當前片段信息
# q - 退出
```

## 輸出示例

### 說話人統計

```
📊 Speaker Statistics:
────────────────────────────────────────────────────────────────────────────────
Speaker ID      Actor                Character            Segments   Duration
────────────────────────────────────────────────────────────────────────────────
SPEAKER_0       Cary Grant           Peter Joshua              654     1766.5s
SPEAKER_1       Audrey Hepburn       Regina Lampert            403     1121.8s
SPEAKER_2       Walter Matthau       Hamilton Bartholomew       49       65.7s
SPEAKER_4       James Coburn         Tex Panthollow              3       42.0s
────────────────────────────────────────────────────────────────────────────────
```

### 片段信息

```
================================================================================
⏱  Time: 299.50s - 303.10s
📝 Text: You know, I think I'm beginning to like this painting.
🎤 Speaker: SPEAKER_1 → Audrey Hepburn (Regina Lampert)
👤 Face: bbox=(1250,178) 147x206, confidence=0.88
👄 Mouth landmarks: 3 points
   • mouth_left: (100.5, 50.2) conf=0.85
   • mouth_right: (110.3, 49.8) conf=0.87
   • nose: (105.0, 45.0) conf=0.90
================================================================================
```

## 功能特點

### 1. 自動說話人識別

- 自動檢測影片中的說話人
- 顯示演員名和角色名
- 統計每個說話人的片段數和時長

### 2. 人臉檢測整合

- 顯示人臉位置和大小
- 顯示檢測置信度
- 時間同步顯示

### 3. 嘴部動作追蹤

- 提取嘴部關鍵點
- 顯示嘴部座標和置信度
- 過濾顯示相關關鍵點

### 4. 字幕同步

- 自動載入 ASR 文字
- 時間同步顯示
- 支持多語言

## 技術實現

### 核心組件

1. **IntegratedSegment**: 整合數據結構
   - start/end: 時間範圍
   - text: ASR 文字
   - speaker: 說話人 ID
   - face: 人臉檢測信息
   - mouth_landmarks: 嘴部關鍵點

2. **IntegratedPlayer**: 播放器核心
   - 載入各種數據格式
   - 時間同步查詢
   - 信息整合顯示

3. **播放控制**:
   - ffplay 音頻播放
   - 時間跳轉
   - 片段播放

## 未來擴展

### 待實現功能

1. **視頻播放**: 整合 SDL2 顯示視頻畫面
2. **字幕疊加**: 在視頻上疊加 ASR 文字
3. **人臉標註**: 在視頻上畫出人臉框
4. **說話人切換**: 自動跳轉到說話人片段
5. **關鍵詞搜索**: 搜索特定文字並跳轉
6. **導出功能**: 導出整合結果為字幕文件

### GUI 擴展

可考慮使用以下框架實現圖形界面：
- **egui**: 即時模式 GUI
- **slint**: 聲明式 UI
- **iced**: Elm 架構 GUI

## 性能優化

### 當前實現

- 使用 HashMap 存儲說話人映射
- 使用迭代器進行時間查詢
- 使用線程進行播放控制

### 優化建議

1. **索引結構**: 為時間查詢建立索引
2. **預加載**: 預先載入下一個片段
3. **快取**: 快取常用片段信息
4. **並行**: 並行載入多個數據源

## 相關文檔

- `FINAL_TEST_REPORT.md`: 測試報告
- `LONG_MOVIE_TEST_SUMMARY.md`: 長影片測試
- `GUI_FACE_PLAYER_USAGE.md`: GUI 播放器使用

## 問題排查

### 常見問題

1. **找不到數據文件**
   - 確認文件路徑正確
   - 檢查文件格式是否正確

2. **播放失敗**
   - 確認 ffplay 已安裝
   - 檢查視頻文件是否存在

3. **無法識別說話人**
   - 確認 ASRX 數據格式正確
   - 檢查 speaker_stats 是否存在

### 調試模式

```bash
RUST_LOG=debug ./target/debug/integrated_player ...
```

---

**創建日期**: 2026-04-02
**版本**: 1.0.0
**作者**: Momentry Team
