# GUI 說話人播放器使用指南（Face 整合版）

**更新日期**: 2026-04-02  
**功能**: 整合 Face 檢測 + ASRX 說話人分離 + 語音播放

---

## 🎯 功能特點

| 功能 | 說明 |
|------|------|
| **📁 音頻播放** | 提取並播放每個說話人的語音片段 |
| **📊 ASRX 整合** | 顯示說話人分離結果 |
| **👤 Face 整合** | 顯示人臉檢測對應（99.8% 匹配率） |
| **▶️ 播放控制** | 單個播放、全部播放、停止 |
| **⏱️ 進度顯示** | 實時播放進度條 |

---

## 🚀 啟動方式

### 方法 1: 命令行啟動

```bash
cd /Users/accusys/momentry_core_0.1/scripts/asrx_self
python3 speaker_player_gui_face.py
```

### 方法 2: 後台啟動

```bash
cd /Users/accusys/momentry_core_0.1/scripts/asrx_self
nohup python3 speaker_player_gui_face.py > /tmp/gui_player.log 2>&1 &
```

---

## 📋 使用步驟

### 步驟 1: 選擇文件

1. **選擇音頻** (.wav)
   - 點擊 "選擇音頻" 按鈕
   - 選擇 `/tmp/charade_audio.wav`

2. **選擇 ASRX 結果** (.json)
   - 點擊 "選擇結果" 按鈕
   - 選擇 `/tmp/asrx_charade_optimized.json`

3. **選擇 Face 結果** (.json) - 可選
   - 點擊 "選擇 Face" 按鈕
   - 選擇 `/tmp/face_long.json`
   - 點擊 "🔗 整合 Face" 按鈕

---

### 步驟 2: 查看說話人列表

**左側列表** 顯示所有說話人：
```
🔊 SPEAKER_0    |  654 段 | 29.4 分鐘 | 👥 654/654
🔊 SPEAKER_1    |  403 段 | 18.7 分鐘 | 👥 402/403
🔊 SPEAKER_2    |   49 段 |  1.1 分鐘 | 👥 49/49
...
```

**圖標說明**:
- 🔊 說話人
- 👥 有人臉對應
- 654/654 有人臉的片段數/總片段數

---

### 步驟 3: 查看語音片段

**右側列表** 顯示所選說話人的所有片段：
```
[   1] SPEAKER_0    |  374.80s -  375.90s ( 1.10s) 👥✅
[   2] SPEAKER_0    |  384.10s -  384.90s ( 0.80s) 👥✅
[   3] SPEAKER_0    |  387.30s -  388.40s ( 1.10s) 👥✅
...
```

**圖標說明**:
- 👥✅ 有人臉對應
- 👥❌ 無人臉對應

---

### 步驟 4: 播放語音

**播放方式**:
1. **雙擊片段** - 播放所選片段
2. **▶️ 播放所選** - 播放當前選中的片段
3. **▶️▶️ 播放全部** - 播放所選說話人的所有片段
4. **⏹️ 停止** - 停止播放

**播放進度**:
- 底部進度條顯示播放進度
- 狀態欄顯示當前播放的片段信息

---

## 📊 測試數據

### Charade 1963 (114.7 分鐘)

| 文件 | 路徑 |
|------|------|
| **音頻** | `/tmp/charade_audio.wav` |
| **ASRX** | `/tmp/asrx_charade_optimized.json` |
| **Face** | `/tmp/face_long.json` |
| **整合** | `/tmp/charade_integrated.json` |

### 說話人統計

| 說話人 | 片段數 | 時長 | 有人臉 | 匹配率 |
|--------|--------|------|--------|--------|
| SPEAKER_0 | 654 | 29.4min | 654 | 100.0% ✅ |
| SPEAKER_1 | 403 | 18.7min | 402 | 99.8% ✅ |
| SPEAKER_2 | 49 | 1.1min | 49 | 100.0% ✅ |
| ... | ... | ... | ... | ... |
| **總計** | 1118 | 51.6min | 1116 | **99.8%** ✅ |

---

## 🎬 使用場景

### 場景 1: 驗證說話人分離準確度

1. 載入 ASRX 結果
2. 逐一播放每個說話人的片段
3. 人工判斷是否正確

---

### 場景 2: 整合 Face 與說話人

1. 載入 ASRX + Face 結果
2. 點擊 "整合 Face"
3. 查看每個片段的 Face 對應（👥✅/👥❌）
4. 播放有人臉的片段

---

### 場景 3: 創建訓練數據

1. 播放特定說話人的所有片段
2. 錄製音頻作為訓練數據
3. 標記人臉與說話人對應

---

## ⚙️ 技術細節

### Face 整合邏輯

```python
# 時間閾值：3.0 秒
# 如果 Face 時間戳在 ASRX 片段前後 3 秒內，視為匹配

if start - 3.0 <= face_timestamp <= end + 3.0:
    匹配成功 👥✅
```

### 播放邏輯

```python
# 1. 使用 ffmpeg 提取音頻片段
ffmpeg -i audio.wav -ss START -t DURATION segment.wav

# 2. 使用 afplay (macOS) 播放
afplay segment.wav
```

---

## 📁 相關文件

```
scripts/asrx_self/
├── speaker_player_gui_face.py      # GUI 播放器（Face 整合版）⭐
├── speaker_player_gui.py           # GUI 播放器（舊版）
├── speaker_player_interactive.py   # 交互式播放器
├── speaker_audio_player.py         # 命令行播放器
├── integrate_face_asrx_speaker.py  # Face+ASRX 整合工具
└── GUI_FACE_PLAYER_USAGE.md        # 本使用指南
```

---

## ✅ 測試結果

**GUI 啟動**: ✅ 成功 (PID 10626)  
**Face 整合**: ✅ 成功 (99.8% 匹配率)  
**播放功能**: ✅ 正常  
**進度顯示**: ✅ 正常  

---

**指南完成**: 2026-04-02  
**狀態**: ✅ GUI 已啟動並運行中
