feat: backup architecture docs, source code, and scripts

2026-04-25 17:15:45 +08:00
parent 59809dae1f
commit 1f84e5469f
368 changed files with 146329 additions and 261 deletions
--- a/docs_v1.0/IMPLEMENTATION/DEMO_GUIDE.md
+++ b/docs_v1.0/IMPLEMENTATION/DEMO_GUIDE.md
@@ -0,0 +1,397 @@
+# 整合播放器演示功能指南
+
+## 🎬 自動演示模式
+
+整合播放器支持自動演示功能，可以自動播放所有說話人的片段，展示各項功能。
+
+---
+
+## 快速開始
+
+### 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