momentry_core/docs_v1.0/IMPLEMENTATION/DEMO_GUIDE.md

整合播放器演示功能指南

🎬 自動演示模式

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

---

快速開始

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

./run_demo.sh --quick

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

2. 標準演示

./run_demo.sh

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

3. 自定義演示

./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. 功能演示

# 展示給團隊或客戶
./run_demo.sh

2. 快速測試

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

3. 數據驗證

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

4. 說話人分析

# 分析特定說話人的表現
./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

#!/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. 演示特定說話人

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

2. 演示整合 Face 數據

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

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

./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: 找不到測試數據

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

問題 2: 播放失敗

# 檢查 ffplay
which ffplay

# 安裝 ffmpeg
brew install ffmpeg

問題 3: 演示太快/太慢

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

---

性能優化

減少片段數

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

提高速度

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

演示主要說話人

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

---

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

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

---

相關命令

# 查看幫助
./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