ESP32 Tiny MIDI Synthesizer

English | 日本語

ESP32 が MIDI を読み取り、GM 音色で PCM 合成して Bluetooth Classic A2DP へ送信する MIDI プレイヤーです。ブラウザは操作と MIDI-derived visualization を担当し、音声処理は ESP32 で行います。

現行仕様

• ESP-IDF 5.5.4 / ESP32 Classic Bluetooth A2DP source。
• 標準音色形式は GM128 G.711 μ-law + attack loops + pair cache。
• 既定の最大同時発音数は 32 voices。
• SBC、joint stereo、44.1 kHz 要求（接続先との交渉後は 44.1/32/16 kHz）。
• A2DP 接続後は 3 秒安定待ちして自動再生。
• 元の MIDI は ESP32 の song パーティションとブラウザの IndexedDB に保存。
• ブラウザの表示は元 MIDI を解析したもの。音声レベルや音声波形の解析ではありません。
• ログは UART と同じバイト列を 4 KiB RAM ring と 64 KiB Flash ring に保存し、/api/log で取得できます。
• Wi-Fi の SSID とキーは NVS に保存され、設定ダイアログから SSID 検索と変更ができます。
• NVS の SSID が未登録・空・プレースホルダーの場合、BOOT（標準 GPIO0）を起動後に 2 秒長押しした場合、または起動時の STA 接続が約 15 秒以内に完了しない場合は、設定 AP（SSID ESP32-Tiny-MIDI-Setup / キー 12345678 / 192.168.4.1）へフォールバックします。この状態では Bluetooth/音声を起動せず、APに接続したままSTA側でSSID検索ができます。設定保存後に再起動します。
• mDNS で http://esp32-tiny-midi.local/ と _http._tcp サービスを告知します。

まず使う

1. Config.example.h を Config.h にコピーし、Wi-Fi 設定を入力してから ESP32 を USB 接続します。Config.h は公開対象にしません。
2. ESP-IDF の環境で build_idf_esp32_pcm_synth.bat を実行してビルドします。このバッチに引数はありません。生成物は .idf-build\mulaw に置かれます。
3. upload_idf_esp32_pcm_synth.bat mulaw COM10 で転送します。第 1 引数がビルド variant、第 2 引数が COM ポートです。転送 baud の引数はありません。
4. ルーターまたはシリアルログで確認した ESP32 の IP をブラウザで開きます（例: http://<ESP32のIP>/）。
5. MIDI を選び、転送後に Bluetooth 機器を検索・接続して「再生」を押します。

初回の Wi-Fi 設定では、設定 AP に接続すると Wi-Fi 専用の初期設定画面が自動で開きます。SSID 検索・パスワード入力・保存だけを行う画面で、MIDI と Bluetooth の操作は表示しません。設定APはAPSTAで動作するため、AP接続を維持したまま周囲のSSIDを検索できます。接続先は http://esp32-tiny-midi.local/（解決できない場合は http://192.168.4.1/）です。通常 STA 接続中も同じダイアログから変更できます。新しい SSID へ接続できなかった場合は、変更前の資格情報へ自動的に戻します。

標準シリアルログは 115200 bps です。COM ポートを省略した場合、転送バッチは COM10 を使用します。ESP-IDF の環境変数が未設定の場合は、先に ESP-IDF の export.bat を実行してください。

UI の要点

• 画面タイトルは ESP32 Tiny MIDI Synthesizer。読み込み曲、再生時間、操作ボタンはヘッダー内で A2DP 接続状態の左側に表示します。
• 元 MIDI はブラウザにも保存されます。削除ボタンはブラウザ内のコピーだけを消します。
• トラック/行を選ぶと表示を絞り込めます。音声はミュートされません。
• 表示オフセットは -500～1500 ms、20 ms 刻み。正の値は表示を遅らせ、BT 機器ごとに保存されます。
• 「Tone Preview」の音色プルダウンと、選択音色を全 Note On に使うチェックボックスがあります。
• 「デバイス設定」では、通常の STA 接続中でも SSID 検索、SSID/キーの保存、再接続を行えます。パスワードは API から返しません。
• 同期中は「処理中」と表示します。RTT は内部推定に使いますが通常 UI には表示しません。

主要 API

経路	用途
GET /api/status	接続・再生・voice・曲・underrun 状態
GET /api/sync	ESP32 の再生位置と同期情報
GET /api/log	Flash 履歴と RAM suffix のログ
GET /api/midi/file	ESP32 に保存された元 MIDI
GET /api/bt-devices	発見済み Bluetooth 機器
GET /api/bt-scan/start	Bluetooth inquiry 開始
GET /api/bt-connect?address=...	指定機器へ接続
GET /api/wifi-config	Wi-Fi 接続・IP・設定 AP 状態
GET /api/wifi-scan/start	STA（通常モードまたは設定APのAPSTAモード）で SSID 検索を開始
GET /api/wifi-scan	SSID 検索の進捗・結果
POST /api/wifi-config	ssid=...&password=... で再接続。新 SSID への接続成功後に NVS へ確定保存し、失敗時は変更前へロールバック
POST /api/midi/upload	raw Standard MIDI File を保存
POST /api/transport?action=play|stop	再生/停止

全経路とレスポンス項目は ARCHITECTURE.md の API 表を参照してください。

文書の読み分け

• ARCHITECTURE.md: 現在の構成・メモリ・BT・ログ・API の正本。
• DEVELOPMENT_ENVIRONMENT.md: Windows でのビルド、生成、転送手順。
• 英語版: README_EN.md、ARCHITECTURE_EN.md、DEVELOPMENT_ENVIRONMENT_EN.md。