# 整合播放器演示功能指南

## 🎬 自動演示模式

整合播放器支持自動演示功能，可以自動播放所有說話人的片段，展示各項功能。

---

## 快速開始

### 1. 快速演示（推薦初次使用）

```bash
./run_demo.sh --quick
```

- 每個說話人演示 1 個片段
- 3 倍速播放
- 適合快速了解功能

### 2. 標準演示

```bash
./run_demo.sh
```

- 每個說話人演示 3 個片段
- 2 倍速播放
- 完整展示所有功能

### 3. 自定義演示

```bash
./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` | 啟用自動演示模式 | false |
| `--demo-segments-per-speaker` | 每個說話人演示的片段數 | 3 |
| `--demo-speed` | 演示速度（倍速） | 2.0 |

---

## 演示流程

演示模式會自動執行以下步驟：

1. **載入數據**
   - ASRX 說話人分離結果
   - Face 人臉檢測結果（如果提供）
   - Pose 姿態估計結果（如果提供）

2. **列出說話人**
   ```
   📊 Speaker Statistics:
   ────────────────────────────────────────────────────────────────────────────────
   Speaker ID      Actor                Character              Segments   Duration
   ────────────────────────────────────────────────────────────────────────────────
   SPEAKER_0       Cary Grant           Peter Joshua                654    1764.4s
   SPEAKER_1       Audrey Hepburn       Regina Lampert              403    1119.4s
   SPEAKER_2       Walter Matthau       Hamilton Bartholomew         49      65.7s
   SPEAKER_4       James Coburn         Tex Panthollow                3      44.1s
   ────────────────────────────────────────────────────────────────────────────────
   ```

3. **逐一演示每個說話人**
   
   對每個說話人：
   - 顯示說話人信息（ID → 演員 → 角色）
   - 播放指定數量的片段
   - 顯示整合信息（文字、人臉、嘴部動作）
   - 暫停 2 秒後切換到下一個說話人

4. **演示示例輸出**

   ```
   ================================================================================
   🎭 Demo: SPEAKER_1 → Audrey Hepburn (Regina Lampert)
   ================================================================================
   
   [Segment 1/3]
   
   ================================================================================
   ⏱  Time: 299.50s - 303.10s
   🎤 Speaker: SPEAKER_1 → Audrey Hepburn (Regina Lampert)
   👤 Face: bbox=(1250,178) 147x206, confidence=0.88
   ================================================================================
   
   ⏳ Playing audio (1.8s)...
   ```

---

## 演示模式特點

### 1. 自動化播放
- 無需手動輸入命令
- 自動播放所有說話人
- 適合展示和測試

### 2. 速度控制
- 可調整播放速度
- 支持快速瀏覽（3x）
- 支持正常速度（1x）

### 3. 完整展示
- ASR 文字
- 人臉檢測
- 說話人識別
- 演員/角色映射
- 嘴部動作（如果有 Pose 數據）

---

## 使用場景

### 1. 功能演示
```bash
# 展示給團隊或客戶
./run_demo.sh
```

### 2. 快速測試
```bash
# 開發過程中的快速測試
./run_demo.sh --quick
```

### 3. 數據驗證
```bash
# 驗證 ASRX 結果的正確性
./target/debug/integrated_player \
  --video video.mp4 \
  --asrx asrx.json \
  --demo \
  --demo-speed 1.0  # 原速播放
```

### 4. 說話人分析
```bash
# 分析特定說話人的表現
./target/debug/integrated_player \
  --video video.mp4 \
  --asrx asrx.json \
  --demo \
  --demo-segments-per-speaker 10  # 更多片段
```

---

## 演示時間估算

以 Charade (114.7 分鐘) 為例：

| 模式 | 片段數/說話人 | 速度 | 總時間 |
|------|---------------|------|--------|
| 快速 | 1 | 3x | ~2 分鐘 |
| 標準 | 3 | 2x | ~5 分鐘 |
| 完整 | 5 | 1x | ~15 分鐘 |

計算公式：
```
總時間 = 說話人數 × 片段數 × 平均片段時長 / 速度
```

---

## 演示腳本詳解

### run_demo.sh

```bash
#!/bin/bash
# 主要邏輯：

# 1. 檢查編譯
if [ ! -f ./target/debug/integrated_player ]; then
    cargo build --bin integrated_player
fi

# 2. 檢查數據
if [ ! -f "$VIDEO" ]; then
    python3 scripts/asrx_self/test_long_movie.py
fi

# 3. 運行演示
if [ "$1" = "--quick" ]; then
    # 快速模式
    ./target/debug/integrated_player \
        --demo \
        --demo-segments-per-speaker 1 \
        --demo-speed 3.0
else
    # 標準模式
    ./target/debug/integrated_player \
        --demo \
        --demo-segments-per-speaker 3 \
        --demo-speed 2.0
fi
```

---

## 高級用法

### 1. 演示特定說話人

```bash
# 只演示主要說話人
./target/debug/integrated_player \
  --video video.mp4 \
  --asrx asrx.json \
  --auto-play-speaker \
  --speaker-name SPEAKER_0
```

### 2. 演示整合 Face 數據

```bash
./target/debug/integrated_player \
  --video video.mp4 \
  --asrx asrx.json \
  --face face.json \
  --demo \
  --demo-segments-per-speaker 3
```

### 3. 完整演示（所有數據）

```bash
./target/debug/integrated_player \
  --video video.mp4 \
  --asr asr.json \
  --face face.json \
  --asrx asrx.json \
  --pose pose.json \
  --demo \
  --demo-segments-per-speaker 5 \
  --demo-speed 1.5
```

---

## 輸出說明

### 演示輸出結構

```
🎬 Auto Demo Mode
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Segments per speaker: 3
Demo speed: 2.0x

================================================================================
🎭 Demo: SPEAKER_0 → Cary Grant (Peter Joshua)
================================================================================

[Segment 1/3]

================================================================================
⏱  Time: 14.20s - 21.50s
🎤 Speaker: SPEAKER_0 → Cary Grant (Peter Joshua)
👤 Face: bbox=(1250,178) 147x206, confidence=0.88
================================================================================

⏳ Playing audio (3.6s)...

[Segment 2/3]
...

⏸️  Pausing 2 seconds before next speaker...

================================================================================
🎭 Demo: SPEAKER_1 → Audrey Hepburn (Regina Lampert)
================================================================================
...

================================================================================
✅ Demo completed!
================================================================================
```

### 信息解讀

- **🎭 Demo**: 說話人演示標題
- **⏱ Time**: 片段時間範圍
- **🎤 Speaker**: 說話人 → 演員 → 角色
- **👤 Face**: 人臉位置和置信度
- **👄 Mouth**: 嘴部關鍵點（如果有）
- **⏳ Playing**: 正在播放音頻
- **⏸️ Pausing**: 說話人切換暫停

---

## 故障排查

### 問題 1: 找不到測試數據

```bash
# 解決方案：生成測試數據
cd scripts/asrx_self
python3 test_long_movie.py
cd ../..
```

### 問題 2: 播放失敗

```bash
# 檢查 ffplay
which ffplay

# 安裝 ffmpeg
brew install ffmpeg
```

### 問題 3: 演示太快/太慢

```bash
# 調整速度參數
--demo-speed 1.0  # 原速
--demo-speed 2.0  # 2 倍速（默認）
--demo-speed 3.0  # 3 倍速
```

---

## 性能優化

### 減少片段數

```bash
--demo-segments-per-speaker 1  # 每個說話人只演示 1 個片段
```

### 提高速度

```bash
--demo-speed 4.0  # 4 倍速快速瀏覽
```

### 演示主要說話人

```bash
# 只演示片段數最多的說話人
--auto-play-speaker --speaker-name SPEAKER_0
```

---

## 比較：演示模式 vs 交互模式

| 特性 | 演示模式 | 交互模式 |
|------|----------|----------|
| 自動化 | ✅ 全自動 | ❌ 需手動輸入 |
| 速度控制 | ✅ 可調整 | ❌ 固定速度 |
| 說話人選擇 | ❌ 按順序 | ✅ 自由選擇 |
| 時間跳轉 | ❌ 不支持 | ✅ 支持 |
| 適用場景 | 展示、測試 | 分析、開發 |

---

## 相關命令

```bash
# 查看幫助
./target/debug/integrated_player --help

# 快速測試
./run_demo.sh --quick

# 標準演示
./run_demo.sh

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

---

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