# live_session セットアップ手順

HOLLYLAND ワイヤレスピンマイク(2ch)→ whisper-cpp によるリアルタイム文字起こし。

---

## 0. 前提インストール

```bash
brew install whisper-cpp ffmpeg
```

> どちらも本セッション開始時にバックグラウンドで走らせている。完了確認:
> ```bash
> command -v ffmpeg && (command -v whisper-cli || command -v whisper-cpp)
> ```

## 1. 日本語モデルのダウンロード

medium(初期推奨・バランス):
```bash
whisper-cpp-download-ggml-model medium
```

精度を上げたい場合(VRAM・時間に余裕があれば):
```bash
whisper-cpp-download-ggml-model large-v3
# 切替: MODEL=large-v3 ./transcribe.sh
```

軽くしたい(古いMac等):
```bash
whisper-cpp-download-ggml-model small
# MODEL=small ./transcribe.sh
```

DL後の実体パスは `transcribe.sh` が自動探索する。下記いずれかにあれば見つかる:
- `$(brew --prefix)/share/whisper-cpp/ggml-<MODEL>.bin`
- `/opt/homebrew/share/whisper-cpp/ggml-<MODEL>.bin`
- `~/.cache/whisper/ggml-<MODEL>.bin`
- `./models/ggml-<MODEL>.bin`(ローカル)

## 2. HOLLYLAND が ffmpeg から見えてるか確認

```bash
ffmpeg -f avfoundation -list_devices true -i "" 2>&1 | grep -A1 -i "audio"
```

出力例:
```
[AVFoundation indev @ 0x...] AVFoundation audio devices:
[AVFoundation indev @ 0x...] [0] Wireless Microphone
[AVFoundation indev @ 0x...] [1] MacBook Air Microphone
```

→ `[0] Wireless Microphone` のように **デバイス番号** と **名前** を控える。

## 3. 録音テスト(5秒)

名前で:
```bash
ffmpeg -f avfoundation -ac 2 -ar 48000 -i ":Wireless Microphone" -t 5 test.wav
```

番号で(名前指定でコケた時の代替):
```bash
ffmpeg -f avfoundation -ac 2 -ar 48000 -i ":0" -t 5 test.wav
```

左右ch分離して再生確認:
```bash
ffmpeg -i test.wav -filter_complex "[0:a]channelsplit=channel_layout=stereo[L][R]" \
  -map "[L]" test_L.wav -map "[R]" test_R.wav
afplay test_L.wav   # 左ch(りつは想定)
afplay test_R.wav   # 右ch(暦想定)
```

## 4. 起動

```bash
./transcribe.sh
```

停止: `Ctrl+C`。出力は `transcript.md` に追記される。

### 環境変数で挙動カスタム
| 変数 | 既定 | 説明 |
|---|---|---|
| `DEVICE_NAME` | `Wireless Microphone` | avfoundation入力指定。番号なら `':0'` |
| `CHUNK_SEC` | `30` | 1チャンク秒数。短いほど低遅延だが精度下がる |
| `MODEL` | `medium` | `tiny`/`base`/`small`/`medium`/`large-v3` |
| `LANG_CODE` | `ja` | whisper言語 |
| `LEFT_NAME` | `りつは` | 左ch話者名 |
| `RIGHT_NAME` | `暦` | 右ch話者名 |
| `THREADS` | `4` | whisperスレッド数(M系Macなら6〜8試す) |

例:
```bash
MODEL=large-v3 CHUNK_SEC=20 ./transcribe.sh
```

---

## 5. 左右ch逆だった時の修正

`transcript.md` を見て名前が逆だったら、起動時に環境変数で入れ替えるだけでOK:
```bash
LEFT_NAME=暦 RIGHT_NAME=りつは ./transcribe.sh
```

恒久的に直したい場合は `transcribe.sh` の以下を入れ替え:
```bash
LEFT_NAME="${LEFT_NAME:-りつは}"     # ← この既定値
RIGHT_NAME="${RIGHT_NAME:-暦}"        # ← と
```

---

## 6. トラブルシューティング

### ffmpeg が「Input/output error」
- マイク権限: システム設定 → プライバシーとセキュリティ → マイク → ターミナル(or iTerm/VSCode)を許可
- デバイス名で失敗 → 番号で再試行: `DEVICE_NAME=':0' ./transcribe.sh`

### whisper-cli が見つからない
- `brew install whisper-cpp` の完了待ち
- 古いビルドだと `whisper-cpp` バイナリ名。スクリプトは両対応

### モデルが見つからない
- `whisper-cpp-download-ggml-model medium` で取得
- 取得先パスが上記探索一覧にない場合: `cp /取得先 ./models/ggml-medium.bin`

### transcript.md が更新されない
- `.session.log` を見る: `tail -f .session.log`
- チャンクは「次のチャンクが書き始まってから」処理される(=最初は最低60秒待ち)

### 静寂しか拾わない・「ご視聴ありがとうございました」だけ出る
- whisperの空入力ハルシネ。スクリプトで除去済みだが、頻発するなら録音レベル確認:
  ```bash
  ffmpeg -f avfoundation -ac 2 -ar 48000 -i ":Wireless Microphone" -t 10 -af "volumedetect" -f null - 2>&1 | grep -E "mean|max"
  ```
  `mean_volume` が -50dB より小さいとほぼ無音扱い。受信機の出力ゲイン上げる

### CPU 負荷が高い・遅延がたまる
- `MODEL=small` に下げる
- `CHUNK_SEC=60` に伸ばす(処理回数減)
- `THREADS=6` 等に増やす(M系)

---

## 7. ファイル構成

```
live_session/
├── transcribe.sh        # 本体スクリプト
├── SETUP.md             # この手順書
├── transcript.md        # 文字起こし出力(追記される)
├── chunks/              # 録音中のwavチャンク(処理後削除)
├── .processed/          # 処理済みwav退避(デバッグ用・適宜削除)
├── .session.log         # ffmpeg/whisperログ
└── .transcript.lock     # 追記排他ロック
```