# 生音声から駆動までを1モデルにするE2E構成

## コンテストでの主張

この作品でいうフィジカルAIは、音声認識AIとモーター制御を別々に置いたものではない。

> **人の演奏を生の波形で知覚し、異なる身体を持つ笛ロボットの行動へ変換し、
> 自分の身体が実際に生んだ音を再び知覚して、同じモデルの内部状態を適応させる。**

モデルの外に音程列、楽譜、目標位置、機体パラメーターを作らないことが重要である。
「聞く」「身体を動かす」「結果を聞いて身体に慣れる」が1個の学習済みモデルの中で循環することを、
フィジカルAIとしての中心的なアピールにする。

```
人の口笛（異なる身体）
        ↓ 生波形
  1個の再帰モデル ←──────────────┐
        ↓ PWM・バルブ             │
  実物の笛・空気・機構            │
        ↓ 実際に鳴った生波形 ─────┘
```

単なる音声変換ではなく、摩擦、遅れ、バックラッシュ、管長、気温、吹奏圧など、
シミュレーターだけでは決め切れない身体性が閉ループに入る。笛を交換したときに一度崩れ、
吹くうちに同じ重みのまま再適応する様子を、再帰状態による身体獲得のデモとする。

## 決定

新しい本命経路は、口笛をYINで音程列へ変換して物理コントローラーへ渡す方式ではなく、
**1個のニューラルモデルが、生のお手本音声と演奏中の生音声からPWM・バルブ・終了を直接出す方式**とする。

```
録音したお手本 ──┐
                   ├─ E2EImitator ─→ PWM
直近の自己音声 ───┘                 ├→ バルブ
                                      └→ 終了確率
```

推論経路では、以下を使わない。

- YIN、PitchNetなどによる明示的な音程推定
- 10ms刻みの目標音程列
- 音域へのオクターブ移調規則
- 音符・休符・発音開始の判定
- 管長から目標位置を求める物理式
- PWMの推測航法と手書き観測器
- 固定のバルブ先読み規則

原点出し、PWMの上限、通信タイムアウトは、学習対象ではなく人と機械を守る安全機構なのでモデル外に残す。

## E2Eと呼ぶための実装条件

本番デモの推論経路は、次の条件をすべて満たすこと。

| 条件 | 確認方法 |
|---|---|
| 生のお手本音声が直接モデルへ入る | 実機スクリプトにYIN・音程列変換がない |
| 生の自己音声が直接同じモデルへ戻る | 最新のPCM波形を毎10ms入力する |
| 行動を直接出す | PWMとバルブがモデル出力である |
| モデル外の演奏プロファイルがない | 音程列、目標位置、PWM列を事前生成しない |
| 身体への適応がモデル内にある | 重みを変えず、再帰状態だけで演奏が改善する |
| 安全処理と知能処理を区別する | 原点出し・出力制限・非常停止だけをモデル外に置く |

学習時にはシミュレーターの真値を報酬・評価・教師生成に利用してよいが、推論時のモデル入力へは渡さない。
最終版では行動模倣だけで終わらせず、モデル自身の閉ループ演奏を評価する強化学習と実機データによる適応を行う。

## 1モデルの内部

実装は [flute_rl/yamabiko/e2e.py](../flute_rl/yamabiko/e2e.py)。チェックポイントは1個で、全パラメーターを一緒に学習する。

1. **共有音声エンコーダー**
   - 320サンプル（16kHzで20ms）の生波形を1D CNNで特徴にする
   - お手本と自己音に同じ重みを使う
   - 音程を中間出力として強制しない
2. **お手本メモリ**
   - 録音全体を双方向GRUで記憶する
   - 演奏中のGRUが注意機構で必要な場所を読む
3. **再帰制御器**
   - お手本の文脈、直近の自己音、前回の出力を入力にする
   - 隠れ状態は曲をまたいで保持し、機体の違いも同じ状態の中に覚える
4. **直接出力**
   - `tanh`を通したプランジャーPWM
   - バルブの確率
   - 演奏終了の確率

お手本を一度すべて聞いてから演奏するため、お手本側は未来も含めて符号化できる。自己音側は、行動を決める時点までの波形だけを入れる因果窓にしている。

## 学習

最初の段階は [scripts/train_yamabiko_e2e.py](../scripts/train_yamabiko_e2e.py) の行動模倣で立ち上げる。
シミュレーターのOracleがPWMとバルブの教師を作るが、生徒モデルへの入力は2つの生波形だけである。
目標音程、真の位置、機体パラメーター、Oracleの内部状態はモデルに渡さない。

```bash
python scripts/train_yamabiko_e2e.py \
  --device cuda --steps 2000 --batch 8 --songs 3 \
  --out runs/yamabiko_e2e.pt
```

同じ機体・同じお手本を複数回続けた系列を学習単位にし、テイク間でGRU状態を消さない。行動模倣で安全に動く初期値を得た後、
[scripts/train_yamabiko_e2e_rl.py](../scripts/train_yamabiko_e2e_rl.py) の再帰PPOで閉ループ微調整する。
シミュレーターの真の音程は報酬と評価だけに使い、モデル入力には渡さない。自己音を遮断した同一条件も毎回評価する。

```bash
python scripts/train_yamabiko_e2e_rl.py \
  --init runs/yamabiko_e2e_bc.pt --iters 300 --takes 3 \
  --out runs/yamabiko_e2e_rl.pt
```

発音しない報酬ハックを防ぐため、鳴るべき区間の無音は最大音程誤差より必ず悪い報酬にする。初期方策は数半音以上外れるため、
音程報酬を300セントで打ち切らず1200セントまで区別する。後半テイクを強く重み付けし、1回目の探索より適応後の精度を優先する。

## 実機推論

```bash
# PC: PyTorchチェックポイントをUNO Q用の単一NumPyファイルへ変換
python scripts/export_yamabiko_e2e.py runs/yamabiko_e2e.pt

# PC: コードとモデルを転送
scripts/uno_q_push.sh runs/yamabiko_e2e.npz

# UNO Q Linux
python3 scripts/bench_yamabiko_e2e.py runs/yamabiko_e2e.npz
python scripts/yamabiko_e2e_play.py \
  --policy runs/yamabiko_e2e.npz --songs 3
```

このスクリプトは固定時間の生音声を録音し、意味的な前処理をせずモデルへ渡す。演奏中もマイクの最新320サンプルを直接モデルへ渡す。

### UNO Qでの役割分担

| 場所 | 処理 |
|---|---|
| STM32 MCU | ICS-43434から16kHz PCMを取得、Linuxへ転送、PWM・バルブ指令を期限どおり実行、出力上限と通信タイムアウト |
| UNO Q Linux | お手本のraw PCM保持、E2Eモデル推論、10msごとの行動送信、ログ保存 |
| 学習用PC | PyTorchによる学習、`.pt`からUNO Q用`.npz`への変換 |

既存ファームウェアは10msごとに160個の新しいサンプルをLinuxへ送り、`hw.Audio`が連続した16kHzストリームとして保持する。
モデルは各制御ステップの直前に最新320サンプル（20ms）を読む。学習時の合成音、お手本録音、自己音入力はすべて
`16kHz / mono / float32 [-1,1]`という同じ契約にそろえる。E2E経路ではYINを停止し、その計算時間をモデルに渡す。

UNO Q用の `e2e_numpy.py` はPyTorchをimportせず、CNN、GroupNorm、双方向GRU、注意機構、制御GRUをNumPyだけで実行する。
小型モデルは64,206パラメーター（約245KiB）。機能優先のPC基準モデルは812,822パラメーター（約2.94MiB）で、成功後に小型モデルへ蒸留する。PyTorch版とNumPy版の数値一致をテストする。構造、学習経緯、独立評価の図解は [e2e-training-report.html](e2e-training-report.html) を参照。
実機では `bench_yamabiko_e2e.py` のaction p99が10ms未満であることを必須条件とし、余裕がなければ音声幅・隠れ状態を縮小する。

注意事項:

- **十分に学習・シミュレーター評価したチェックポイントなしで実機を動かさない**
- UNO QではPyTorchチェックポイントを直接使わず、PCで書き出したNumPy `.npz`を使う
- 入力のフレーム分割と振幅の安定化は行うが、音程・無音・音符などの意味判断はネットワーク内部で学習する

## 完了していること／残っていること

完了:

- 1モデルのraw音声→PWM・バルブ・終了の推論経路
- お手本と自己音で重みを共有する音声エンコーダー
- 曲をまたぐ適応状態
- Oracle行動模倣の学習スクリプト
- 同じ機体・お手本を複数回吹く再帰PPOと、自己音遮断アブレーション
- 実機用raw音声推論ループ
- 出力範囲、因果性、マスク、勾配、状態持ち越しの単体テスト

未完了:

- 実機データを含む本番規模の学習（シミュレーターの未学習256条件評価までは完了）
- 実録音を混ぜたドメイン適応
- UNO Q実機でのp99推論時間の測定（ベンチマーク自体は実装済み）
- 必要になった場合のint8量子化（float32版は約245KiBなので、まず実測で判断する）

## 現在の独立評価

ニューラル耳の事前学習、整合teacher forcing、自己回帰微調整、物理同定補助学習、時間整合ベースライン付き再帰PPOを実施した。クリーン条件だけのPPOは改善せず棄却した。その後、物理rigに加えてマイク利得・帯域・反射・ファン雑音・飽和・短い欠落を乱数化し、内部ニューラル耳の訓練時補助教師と再帰PPOを組み合わせた。下表はこのsim-to-real耐性モデルである。
学習にもモデル選択にも使っていない4 seed、それぞれ64条件、合計256条件（厳しいシミュレーター、同じお手本を3回）のseed均等平均は次の通り。

| 入力 | 1回目 | 2回目 | 3回目 | 発音率 |
|---|---:|---:|---:|---:|
| お手本＋自己音（音響乱数化） | **271.6** | **277.0** | **307.6** | 0.99 |
| 自己音を遮断 | 294.3 | 326.4 | 379.3 | 0.99 |
| お手本＋自己音（従来クリーン条件） | 258.5 | 268.7 | 268.2 | 0.99 |

単位は、実際に鳴った区間の平均音程誤差（セント）。音響乱数化条件では自己音ありが各回23～72セント良く、平均48セントのraw自己音フィードバック利得を複数seedで再現した。旧モデルは同条件で平均387.9セント、新モデルは285.4セントである。
一方、乱数化条件の3回目は1回目より36.0セント悪く、独立分布での「演奏ごとの単調な上達」はまだ達成していない。
したがってこれはE2E構造と閉ループ利用のシミュレーター到達点であり、コンテスト用の最終精度とは扱わない。詳細はHTMLレポートに記載する。

## 審査で示す比較実験

E2Eであることを構成図だけでなく動作で証明する。

| 実験 | 見せること |
|---|---|
| 自己音を遮断する | 自分の音を聞く閉ループが精度に効いている |
| 曲ごとに再帰状態を消す | 身体への慣れが内部記憶にある |
| 同じモデルで未知の口笛を吹く | 曲の丸暗記ではない |
| 笛を途中で交換する | 身体が変わったことを音から検出し、再適応する |
| 1回目から数回目を重ねて表示する | 知覚と行動の循環で上達する |
| 旧YIN＋物理制御と比較する | E2E化の効果と失敗も定量的に示す |

画面表示は、内部の推定音程ではなく、お手本波形・自己音波形、PWM・バルブ、演奏回数、
音声間の評価値、再帰状態の変化を中心にする。「裏では音程列に直している」と誤解されない見せ方にする。
