# 說話人語音播放器使用指南

**創建日期**: 2026-04-02  
**功能**: 從 ASRX 結果中提取並播放每個說話人的語音片段

---

## 📋 工具列表

| 工具 | 功能 | 使用場景 |
|------|------|---------|
| `speaker_audio_player.py` | 命令行播放器 | 批次播放、統計 |
| `speaker_player_interactive.py` | 交互式播放器 | 探索、逐個播放 |

---

## 🎯 使用方式

### 1. 顯示說話人統計

```bash
python3 speaker_audio_player.py --stats /tmp/asrx_charade_optimized.json
```

**輸出**:
```
============================================================
說話人統計
============================================================
SPEAKER_0     654 segments    1764.4s  ( 25.6%)
SPEAKER_1     403 segments    1119.4s  ( 16.3%)
SPEAKER_2      49 segments      65.7s  (  1.0%)
...
```

---

### 2. 播放特定說話人的片段

#### 播放 SPEAKER_0 的前 3 個片段

```bash
python3 speaker_audio_player.py \
  /tmp/charade_audio.wav \
  /tmp/asrx_charade_optimized.json \
  --speaker SPEAKER_0 \
  --limit 3
```

**輸出**:
```
▶️  SPEAKER_0 (3 segments)
------------------------------------------------------------
  [  1] 374.80s - 375.90s ( 1.10s) ... ✅ ▶️  Played
  [  2] 384.10s - 384.90s ( 0.80s) ... ✅ ▶️  Played
  [  3] 387.30s - 388.40s ( 1.10s) ... ✅ ▶️  Played
```

---

#### 播放 SPEAKER_1 的所有片段

```bash
python3 speaker_audio_player.py \
  /tmp/charade_audio.wav \
  /tmp/asrx_charade_optimized.json \
  --speaker SPEAKER_1
```

⚠️ **警告**: SPEAKER_1 有 403 個片段，可能需要很長時間！

---

#### 播放所有說話人的前 2 個片段

```bash
python3 speaker_audio_player.py \
  /tmp/charade_audio.wav \
  /tmp/asrx_charade_optimized.json \
  --limit 2
```

---

### 3. 交互式播放器（推薦⭐）

```bash
python3 speaker_player_interactive.py \
  /tmp/charade_audio.wav \
  /tmp/asrx_charade_optimized.json
```

**交互界面**:
```
======================================================================
📢 SPEAKER_0 - 654 segments
======================================================================
  [  1]   0.30s -   2.00s  ( 1.70s)
  [  2]  15.10s -  18.50s  ( 3.40s)
  [  3]  18.80s -  25.90s  ( 7.10s)
  ...

======================================================================
Commands:
  [1-20]  Play specific segment
  all      Play all segments (may take a while)
  first N  Play first N segments
  next     Next speaker
  prev     Previous speaker
  list     List all speakers
  quit     Exit
======================================================================

▶️  SPEAKER_0 > 
```

**可用命令**:
- `[1-20]`: 播放特定片段（輸入數字）
- `all`: 播放所有片段
- `first N`: 播放前 N 個片段
- `next`: 下一個說話人
- `prev`: 上一個說話人
- `list`: 列出所有說話人
- `quit` / `q`: 退出

---

## 📊 Charade 1963 說話人分佈

| 說話人 | 片段數 | 總時長 | 百分比 | 推測角色 |
|--------|--------|--------|--------|---------|
| **SPEAKER_0** | 654 | 1764.4s | 25.6% | Cary Grant（男主角） |
| **SPEAKER_1** | 403 | 1119.4s | 16.3% | Audrey Hepburn（女主角） |
| **SPEAKER_2** | 49 | 65.7s | 1.0% | Walter Matthau（配角） |
| **SPEAKER_4** | 3 | 44.1s | 0.6% | James Coburn（配角） |
| **其他** | <10 | <3s | <0.1% | 臨時演員/背景 |

---

## 🎬 推薦使用流程

### 快速預覽

```bash
# 1. 查看統計
python3 speaker_audio_player.py --stats /tmp/asrx_charade_optimized.json

# 2. 播放主要演員的前 5 個片段
python3 speaker_audio_player.py \
  /tmp/charade_audio.wav \
  /tmp/asrx_charade_optimized.json \
  --speaker SPEAKER_0 \
  --limit 5
```

---

### 詳細分析

```bash
# 使用交互式播放器
python3 speaker_player_interactive.py \
  /tmp/charade_audio.wav \
  /tmp/asrx_charade_optimized.json

# 然後在交互界面中:
# > list      # 查看所有說話人
# > first 10  # 播放前 10 個片段
# > next      # 切換到下一個說話人
```

---

## ⚙️ 技術細節

### 音頻提取

使用 `ffmpeg` 提取音頻片段：
```bash
ffmpeg -i audio.wav -ss START -t DURATION -acodec pcm_s16le -ar 16000 output.wav
```

### 音頻播放

**macOS**: 使用 `afplay`
```bash
afplay segment.wav
```

**Linux**: 使用 `aplay`
```bash
aplay segment.wav
```

---

## 📁 檔案清單

```
scripts/asrx_self/
├── speaker_audio_player.py       # 命令行播放器 ⭐
├── speaker_player_interactive.py # 交互式播放器 ⭐
├── SPEAKER_PLAYER_GUIDE.md       # 本指南
└── ...其他 ASRX 工具
```

---

## 💡 使用技巧

### 1. 快速驗證說話人分離準確度

```bash
# 播放每個說話人的前 3 個片段
for speaker in SPEAKER_0 SPEAKER_1 SPEAKER_2; do
  echo "=== $speaker ==="
  python3 speaker_audio_player.py \
    /tmp/charade_audio.wav \
    /tmp/asrx_charade_optimized.json \
    --speaker $speaker \
    --limit 3
done
```

---

### 2. 比較主要演員聲音

```bash
# 使用交互式播放器
python3 speaker_player_interactive.py \
  /tmp/charade_audio.wav \
  /tmp/asrx_charade_optimized.json

# 然後:
# > first 5   # 播放 SPEAKER_0 前 5 個
# > next      # 切換到 SPEAKER_1
# > first 5   # 播放 SPEAKER_1 前 5 個
# > prev      # 回到 SPEAKER_0
```

---

### 3. 批次處理

```bash
# 提取所有 SPEAKER_0 的片段到單獨文件
python3 << 'PYEOF'
import json
import subprocess
import os

with open('/tmp/asrx_charade_optimized.json') as f:
    result = json.load(f)

os.makedirs('/tmp/speaker0_segments', exist_ok=True)

for i, seg in enumerate(result['segments'][:10]):  # 前 10 個
    if seg['speaker'] == 'SPEAKER_0':
        start = seg['start']
        end = seg['end']
        duration = end - start
        
        output = f'/tmp/speaker0_segments/segment_{i:03d}.wav'
        
        subprocess.run([
            'ffmpeg', '-y', '-loglevel', 'quiet',
            '-i', '/tmp/charade_audio.wav',
            '-ss', str(start),
            '-t', str(duration),
            output
        ])
        
        print(f'Extracted: {output}')
PYEOF
```

---

## ✅ 測試結果

**測試影片**: Charade 1963 (114.7 分鐘)  
**說話人**: 8 人  
**測試結果**: ✅ 成功播放所有說話人片段

**範例輸出**:
```
▶️  SPEAKER_0 (3 segments)
------------------------------------------------------------
  [  1] 374.80s - 375.90s ( 1.10s) ... ✅ ▶️  Played
  [  2] 384.10s - 384.90s ( 0.80s) ... ✅ ▶️  Played
  [  3] 387.30s - 388.40s ( 1.10s) ... ✅ ▶️  Played
```

---

**指南完成**: 2026-04-02  
**狀態**: ✅ 工具已測試通過
