knowledge バンドル
Bundle OKF 0.2 · 4 conceitos · tainakanchu/auto-audio-visualizer-
Open source Repository Open in the app JSON README (API)
About
# knowledge バンドル
調査・検証で判明した、再利用価値のある事実を [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) v0.2 で記録している。
1 コンセプト = 1 Markdown ファイル。書き方と運用ルールは `okf` スキル (`.claude/skills/okf/`) を参照。
タグ語彙は [tags.yml](tags.yml)、更新履歴は [log.md](log.md)。
# コンセプト
* [gpu-test-nix-environment](/gpu-test-nix-environment.md) - GPU テストは nix develop -c 経由で実行する
* [workers-builds-monitoring](/workers-builds-monitoring.md) - Cloudflare Workers Builds の結果は check-runs API で見る
* [3d-generator-design-principles](/3d-generator-design-principles.md) - 3D Generator は「埋めない系」hero object を優先する
* [deck-bank-recall-decision](/deck-bank-recall-decision.md) - deck の bank recall は live look を変えない
Details
- Kind
- OKF bundles
- Topic
- Cloud & DevOps
- Publisher
- tainakanchu
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Stars
- 1
- Forks
- 1
- Last push
- 2026-09-02T19:18:17Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-09-08 16:07:08
- Updated
- 2026-09-08 16:07:08
- Origin id
tainakanchu/auto-audio-visualizer-:knowledge/index.md
README
# VJ Overlay Tool
ブラウザだけで動く、音に反応するフルスクリーン・ビジュアルツールです。マイク / ライン入力 / ループバック（デスクトップ音声）を解析し、なめらかで音楽に反応するビジュアルを描画します。OBS のブラウザソースや、プロジェクター用のフルスクリーンブラウザに常駐させて使う前提で設計しています。
- **既定シーンは Semantic Synth**。seed から GLSL シェーダそのものを合成する生成シーンです（後述）
- **Canvas 2D を手書き**で描画（three.js / p5 などの外部描画ライブラリは不使用）
- さらに **WebGL2 による GPU シーン**（Fluid Ink / Smoke / Lava / Aurora）を追加。リッチで有機的なアンビエント映像（後述）
- 透過背景に対応。OBS のオーバーレイとしてそのまま重ねられます
- 11 のシーン（生成: Semantic Synth、2D: Bars / Waveform / Particles / Radial / Rings / Lissajous、GPU: Fluid Ink / Smoke / Lava / Aurora）
- **シード（look gacha）** によって全シーンの見た目が劇的に変化します（後述）
- 設定は localStorage に保存され、URL パラメータで上書き可能
## 技術スタック
- Vite + React 18 + TypeScript (strict)
- 描画・音声解析は素の TypeScript クラス（React は UI / 設定のみ）
- ランタイム依存は React のみ
## クイックスタート
```bash
pnpm install
pnpm dev
```
ブラウザで表示された URL（通常 `http://localhost:5173`）を開きます。初回はマイク（音声入力）の許可を求められます。**許可するとビジュアルが音に反応し始めます。**
- ブラウザの自動再生制限により、起動直後は音声が止まったままのことがあります。その場合はパネルの **「▶ Click to start audio」** ボタンを一度クリックしてください。
- 入力デバイスはパネルの **Input device** から選べます（許可後にデバイス名が表示されます）。
## キーボードショートカット
入力欄にフォーカスがあるときは無効になります。
| キー | 動作 |
| --- | --- |
| `1` – `9`, `0` | シーンを番号で選択（`1` = Semantic Synth、`0` = 10 番目のシーン） |
| `←` / `→` | 前 / 次のシーンへ |
| `H` | コントロールパネルの表示 / 非表示 |
| `F` | フルスクリーン切り替え |
| `A` | オートサイクル（自動シーン切替）の ON / OFF |
| `B` | 背景（黒 / 透過）の切り替え |
| `R` | シード（look gacha）を引き直す（ガチャ） |
| `D` | Semantic Synth の Generator 構成はそのまま、細部だけ引き直す（reroll details） |
| `S` | Scene Deck 窓を開く（`?deck=1`。BroadcastChannel、bridge 不要） |
| `T` | タップテンポ（手動 BPM 入力） |
パネルはマウスを止めると約 3 秒で自動的にフェードアウトし、カーソルも隠れます。マウスを動かすと再表示されます。
## シード（look gacha）
パネル上部の **Look** にシード文字列を入力すると、その文字列から**決定論的に**ビジュアル全体の「個性」が生成されます。色だけでなく、配色モード・要素数・サイズ・モーション速度・対称数・回転方向・ゆらぎ、そして各シーンの**レイアウト（variant）**まで一括で変化するので、シードを引き直すたびにガチャを引くように見た目が大きく変わります。
- パネルの **🎲 ボタン**（またはキーボードの `R`）を押すと、`neon-tiger-042` のような読みやすいランダムシードが生成され、即座に反映されます。
- 同じシード文字列からは**必ず同じ見た目**が再現されます（フレームをまたいでも安定）。気に入った見た目はシード文字列を控えておけば再現できます。
- シード入力欄は **Enter キー** または**フォーカスを外した（blur）**タイミングで適用されます（1 文字ごとには反映されません）。
- 各シーンは音への反応（bass / level / beat）を維持したまま、シードに応じた `variant`（0〜3 の離散レイアウト）で描画されます。たとえば Bars なら「下から」「中央ミラー」「上下対向」「左右から内側へ」、Particles なら「上昇」「周回」「雨」「スターフィールド」など。
## GPUシーン（WebGL）
2D の手書きシーンに加えて、**WebGL2 のフラグメントシェーダ**で描く 4 つの「リッチ」シーンを搭載しています。ノイズ（FBM）・メタボール・流体シミュレーションを GPU で評価して、有機的で立体感のある映像を生成します。
- **Fluid Ink（水面の墨流し / マーブリング）**: GPU 上で本物の流体シミュレーション（Stable Fluids ＋ 渦度強化）を毎フレーム解き、見えない「スターラー」がゆっくり水をかき混ぜながらインクを注ぎ込みます。低域が渦の力を、音量がインクの量を、中域が色相のドリフトをゆったり押し上げ、墨流しのように色が折り畳まれていきます。`variant` で「マーブリング」「縁からのジェット」「マンダラ（対称マーブル）」「リボン」の 4 レイアウトに変化します。浮動小数点レンダリング非対応の GPU では簡易マーブル表現（FBM ＋ ドメインワープ）に自動フォールバックします。
- **Smoke（煙 / 霧）**: 5 オクターブの FBM をドメインワープ（別の FBM で参照位置を歪める）してもやもやと立ち上る煙・霧を描きます。`variant` で「立ち上る筋」「横に流れる霧の帯」「中心を巡る渦」「細いお香の煙」の 4 レイアウトに切り替わります。
- **Lava（ラバランプ）**: CPU 側で 8〜18 個のメタボールを浮力でゆっくり昇降させ（壁でソフトバウンス、横ゆらぎ）、シェーダで smooth-min 場を評価して縁・内部グラデーション・リムライト・外周グローを付けます。`variant` で「クラシックなランプ」「横流れ」「中心周回」「左右ミラー」に変化します。
- **Aurora（オーロラ / 星雲）**: 縦方向に減衰する正弦波の帯を FBM でワープし、速度・色相の異なる複数レイヤーを視差合成します。`variant` で「上から垂れるカーテン」「地平線グロー」「星雲（雲状 FBM ＋ 星のきらめき）」「太い 1 本のリボン」に変化します。
### 音への反応（アンビエント設計）
ビートで爆発させるのではなく、**音楽にゆったり呑まれる**ように、各シーンが内部で秒スケール（時定数 0.5〜2 秒）に平滑化した状態を持ち、音をなめらかに吸収します。
- **低域（bass）**: 大きなうねり・ドリフト速度・渦の強さなど、大局的なモーションを揺らし、強めます。
- **中域（mid）**: 色温度（パレットのブレンド）をゆっくりシフトします。
- **高域（treble）**: 細かなシマー（さざ波・きらめき）を加えます。
- **全体音量（level）**: 密度・明るさを底上げします。
- ビートパルスは**ごく控えめ**（最大 15% 程度）にしか効きません。
- 音声が止まっていても、各シーンは時間だけで穏やかに動き続けます（アイドルドリフト）。
### パフォーマンスと対応環境
- **ノートPC の内蔵 GPU（iGPU）での 1080p 常用**を想定し、手描き Canvas シーンとは別レイヤーで描画します。
- GL キャンバスの **DPR（デバイスピクセル比）は最大 1.5 に制限**しています（高解像度ディスプレイでの過負荷を回避）。
- **WebGL2 が必須**です。非対応の環境では GPU シーンは**自動的に無効化**され（シーン選択でグレーアウト・`（WebGL2なし）` 表示）、2D シーンのみで動作します。コンテキストロスト時も自動復帰します。
- 透過は 2D シーンと同様に保たれるので、OBS の透過オーバーレイにそのまま使えます。
> シーンキーは **`1`〜`9`、`0`**（10 番目）です。シーンは 11 個あるので、末尾の 1 つ（Aurora）だけ数字キーの割り当てがありません。`←` / `→`・シーンピッカー・`?scene=aurora` から選べます。
## Semantic Synth（生成シンセシーン・既定）
固定の描画ロジックを持つ 10 シーンとは別に、**seed から GLSL シェーダそのものを合成するシーン**「Semantic Synth」を搭載しています。**これが既定のシーン**で、何も指定しなければ起動時に開きます（キー `1`、または `?scene=semantic-synth`）。
> 既に一度使ったブラウザでは、最後に選んだシーンが localStorage に残っているのでそちらが優先されます。明示的に開くには `?scene=semantic-synth` かキー `1` を使ってください。
> WebGL2 が使えない環境では自動的に Bars（2D）へフォールバックします。
- Source / Field / Modifier / Material の 4 カテゴリ・計 100 種類の Generator の中から、seed に基づいて決定的に組み合わせを選び、GLSL を組み立てて描画します。あらかじめ用意された固定シーンではなく、**都度合成される「実験的な」シーン**です。
- 選ばれる組み合わせは look gacha の **シードがそのまま効きます**。同じシードなら同じ Generator 構成・パラメータ・Look が常に再現されます。
- シードを引き直す（🎲 / `R`）と、他のシーンと同様に**ハード切替ではなくクロスフェード**で新しい Look へ滑らかに遷移します。
- **Generator の構成（どの operator を使うか）は変えずに、パラメータ・変調・配色・composition だけ変えたい**こともあります。その場合は 🎲 の隣の **🧬 ボタン**（またはキーボードの `D`）を使ってください。同じ Generator 構成のまま細部だけ新しいシードで引き直されます（`vj-tweak.mjs --reroll` でも同じことができます）。構成そのものは変わらないので、後述のオーディオ・リアクション（拍で起きるグリッチの種類）も変わりません。
- bass / mid / treble / level などの音声解析結果が Patch 内のパラメータを変調し、他の GPU シーンと同様に音楽にゆったり反応します。
#### 拍で起きることは Patch ごとに違います（オーディオ・リアクション）
Generator は 105 個中 8 個しか音の uniform を読まないので、**画面全体に効く音の反応は Patch 共通の層**が担っています。以前はここが「軽いズームイン＋明るさの持ち上げ」の 1 種類しか無く、どのシードを引いても拍で起きることは同じでした。今はこの層がカタログになっていて、**Patch ごとに座標系の反応 1〜2 種類＋色の反応 1 種類**が決定的に選ばれます。
| 座標に効く | 色に効く |
| --- | --- |
| `punchZoom` 拍の頭で画面が寄る | `rgbSplit` 拍で R/B が横にずれる（色収差グリッチ） |
| `sliceShift` 横帯ごとに水平にずれる（テープが飛ぶようなグリッチ） | `echoGhost` 拍で少し縮んだ残像が背後に重なる |
| `blockCrush` 拍でマクロブロックに潰れる | `hueSlam` 拍で色相が飛ぶ |
| `jitter` 拍で画が飛び、高域で細かく震える | `posterCrush` 拍で階調が段々に潰れる（ビットクラッシュ） |
| `spinKick` 拍で回転が蹴られる | `invertFlash` 強い拍だけ一瞬ネガになる |
| `waveTear` 走査線が横に裂けて流れる | `scanGlow` 走査バンドが流れ、拍で光る |
| `mirrorSnap` 拍で鏡像に畳まれる | `channelRoll` 強い拍で RGB が入れ替わる |
- どれが載るかは **Operator の構成（トポロジ）から決まります**。シードを引き直して構成が変われば、拍で起きることも変わります。
- 乱数のパターン（どの帯がずれるか等）はシードで変わるので、同じリアクションでも Patch ごとに違う崩れ方をします。
- `rgbSplit` / `echoGhost` は拍の瞬間だけシェーダを追加で評価します。重い Patch（heavy な Generator 入り、または厚いスタック）には載りません。
- **無音では完全に無効**です。リアクション層は音が止まると恒等変換に落ち、Patch 素の見た目に戻ります。
- 変調ルート（Patch 内パラメータへの結線）側も、「大きさ」に偏らないよう効き方ごとに重みを付けて選んでいます。歪み・輝き・動きにも同じくらい票が回ります。
#### 動きは音で駆動されます
固定 10 シーンの「アイドルドリフト」（音が無くても時間だけで動き続ける）とは違い、Semantic Synth の時間は**音の大きさで進む速さが変わります**。
- **無音のときはほぼ止まります**（通常速度の 5% 程度）。引きによって「音と関係なくギュインギュイン動く」Patch が出てしまうのを、Generator 側ではなく時間軸の側で止めています。
- 音が入ると素早く等速まで立ち上がり、止まったあとは 1 秒弱かけてゆっくり減速します（急停止するとカクついて見えるため）。
- BPM がロックしていれば全体の速さがテンポに追従し（0.7〜1.25 倍）、拍の頭で少しだけ前に押されます。ブレイク中はグリッドが自走していても**無音なら動きは増えません**。
- Patch ごとの動きの速さ（`composition.speed`）も効きます。上限は 1 倍なので、引きによって従来より速くなる Patch はありません。
#### 音で画が消えることはありません
大音量が続く環境（クラブなど）で画面が真っ暗になり続ける、という事故を構造的に防いでいます。
- 自動生成される変調ルートは**必ず unipolar かつ正の量**なので、音は常に「足す」方向にしか効きません。無音時の見た目が下限で、音が入るほど増えます。
- 変調先は「増える = 見える / 動く」パラメータの**許可リスト**に限定しています。`threshold` / `gate` / `dropout` のような、上げると絵が消えるパラメータは自動では選ばれません（手で組んだ Patch には制限はかかりません）。
- 全 Patch 共通で、拍に合わせた軽いズームイン（5%）と明るさの持ち上げ（15%）、音量に応じたズーム（6%）が main() に入ります。Generator 側が音の uniform を読まなくても最低限は音に反応します。
- その上に載るオーディオ・リアクションも、**暗くする方向の効果は拍のエンベロープにだけ**乗せています（音量では暗くしません）。走査線のような表現も明るくする側だけで作ってあるので、大音量が続いても減光は持続しません。
- 負荷が高い環境ではフレーム時間を監視し、**内部レンダリング解像度を自動的に段階的に下げて**フレームレートを維持します（余裕が戻れば解像度も自動的に戻ります）。
### Timeline パネル
画面右側の **Timeline パネル**では、数秒〜数小節先の演出イベント（シード変更やトランジションなど）をあらかじめ予約でき、演出の流れを JSON として記録・再生できます。詳細は Issue #3 の RFC を参照してください。
## Scene Deck（別窓ポン出し）
Resolume のシーン一覧のように、**別窓で 8 スロットのバリエーションをポン出し**できます。メイン窓（semantic-synth）のいまの Patch をベースに、同じ Generator 構成のままパラメータ違いを 8 面自動生成し、キーボードで即遷移させます。通信は同一オリジンの **BroadcastChannel**（`vj-deck-v1`）だけで、`pnpm bridge` も `?bridge=1` も不要です。
デッキ窓では AudioEngine / Renderer は起動しません（マイク許可プロンプトも、常時の GPU 負荷も無し）。メイン窓をプロジェクター出力、Deck を手元の操作卓にする運用を想定しています。
### 現場セットアップ
1. メイン窓を `?ui=hide` で開く（必要なら `?scene=semantic-synth&seed=…`）
2. メイン窓で **`F`** を押してフルスクリーンにする。Fullscreen は**メイン窓側のユーザー操作が必要**で、Deck からリモートでは入れない
3. メイン窓で **`S`** を押して Deck を開く
4. 以後の操作（seed ガチャ / シーン / hue / 背景 / タップテンポ / lock）は全部 Deck から
### 開き方
- コントロールパネルの **Scene Deck** ボタン
- メイン窓で **`S`**（`D` は reroll details。Issue #51 では `D` と書いてあったが、PR #49 で `D` が細部ガチャに使われているため `S`）
- URL に `?deck=1`（または `?deck=true`）。窓名 `vj-scene-deck` なので連打しても窓は増えない
### 使い方
1. メイン窓を semantic-synth にする
2. デッキ窓を開くと、現行 Patch から 8 面（BASE + V1…V7）が生成される。WebGL2 があればサムネイルが 1 枚ずつ埋まる（無ければ色チップのまま）。画像（サンプラー）を使う Patch はサムネイルを透明なダミーテクスチャで描くため、ほぼ空の絵になる（スロットはラベルと detail で判別できる）
3. `1`–`8` でポン出し。`Shift+数字` は選択中プリセットを無視して cut。`X` でトランジションを cut → default → slow と巡回（以前は `T`。`T` はタップテンポに変更）
4. `←` `→` `↑` `↓` で 4×2 のカーソル、`Enter` / `Space` でそのスロットを出す。`Shift+←` / `Shift+→` はメイン窓のシーン送り
5. `R` でライブ Patch を取り直して再生成、`G` で base を保ったまま bankSeed ガチャ
6. 自動送り: `A` で ON/OFF、`M` で秒 / 小節、`-` / `=` で間隔。順序はツールバーの seq / rnd（rnd はいまのスロット以外）
7. 小節モードはメイン窓が tempo LOCK のときだけ進む。外れたら警告して待つ。切断中は自動送りは止まる
8. 操作卓: `Q` seed ガチャ、`W` 細部 reroll、`B` 背景、`H` hue 固定トグル、`[` / `]` hue ∓15°、`T` タップテンポ、`,` / `.` テンポ ÷2 / ×2、`/` テンポ AUTO、`L` Timeline lock 30s トグル、`Shift+A` メイン窓オートサイクル
9. 手札は自動保存される。`A`〜`H` はクリックで呼出、`Shift+クリック` で保存。`Shift+S` は次の空きスロットへ。JSON copy / paste で持ち運び（詳細は「手札の保存」）
| キー | 動作 |
| --- | --- |
| `1`–`8` | スロットをポン出し |
| `Shift+数字` | cut でポン出し |
| `←` `→` `↑` `↓` | 4×2 カーソル |
| `Shift+←` / `Shift+→` | メイン窓のシーン送り |
| `Enter` / `Space` | カーソル位置を出す |
| `T` | タップテンポ（**変更**。以前はトランジション巡回） |
| `X` | トランジション巡回（`T` から**移動**） |
| `,` / `.` | テンポ ÷2 / ×2 |
| `/` | テンポ AUTO |
| `Q` | seed ガチャ（メイン窓 `R` 相当。Deck の `R` は bank 再生成） |
| `W` | 細部 reroll（メイン窓 `D` 相当） |
| `B` | 背景トグル |
| `H` | hue 固定トグル（fixed に入るとき現在 hue を固定） |
| `[` / `]` | hue 固定 ∓15° |
| `L` | Timeline lock 30s ⇄ 解除 |
| `Shift+A` | メイン窓のオートサイクル ON/OFF |
| `A` | Deck 側 auto 送り ON/OFF |
| `M` | auto の秒 / 小節 |
| `-` / `=` | auto 間隔 |
| `R` | ライブ Patch から bank 再生成 |
| `G` | bank ガチャ |
| `Shift+S` | いまの手札を次の空きスロット（無ければ `A`）へ保存 |
| `F` | **この窓**のフルスクリーン（メイン窓の出力全画面にはならない） |
手動でポン出した位置から自動送りが続きます（秒タイマーはリセット）。バンクはトリガーのたびに作り直さないので、「さっきの 3 番」が消えません。Claude Code / `vj-tweak` / seed ガチャでメインの画がバンクの外に出たら **BASE CHANGED** が出るので、`R` で取り直してください。
### MIDI
Scene Deck 窓だけで Web MIDI を受けます（メイン窓には載せません）。**Deck が背面・非フォーカスでも効きます**（Web MIDI はフォーカス不要）。
- **Chrome / Edge**: 標準対応
- **Firefox**: Web MIDI 用の site permission add-on が必要（108+）
- **Safari**: 非対応。Deck は落ちず「MIDI 非対応」と出ます
使い方:
1. Deck の MIDI パネルで **MIDI** を押す。権限は **2 段**（MIDI 本体と SysEx）。両方許可する
2. nanoPAD2 は SysEx の **Search Device**（Family ID `12 01`）で確定し、**Native KORG Mode** に入る。`native` バッジが出る。入れなければ Current Scene Data Dump でパッドの Note# からマップを自動生成する
3. **learn** を ON にし、割り当てたい action を選んでパッド / CC を叩く（nanoPAD2 以外、または Native を使わない場合）。同じトリガーが既にあれば上書き（警告）。`Esc` で learn 終了。learn 中もキーボードのパッドは使える
4. マッピングは `localStorage` キー `vj-deck-midi-v1`（`{ activeMapping, nanopad: { preferNative, swapRows } }`）。JSON 書き出し / 読み込みで別 PC へ持てる
**Native mode の in / out**: 接続時に Native In、Deck 窓を閉じる（またはリロードする）ときに Native Out を送る。送らないと nanoPAD2 が Native のまま残り、他アプリで普段のノートが出なくなる。戻らなければ **USB を抜くか電源再投入**。
**Scene LED**（Native mode のみ）:
| LED | 意味 |
| --- | --- |
| Scene 1 | host 接続中（conn live） |
| Scene 2 | Deck auto ON |
| Scene 3 | tempo LOCK |
| Scene 4 | learn 中。エラー時は 500ms 点滅 |
**既定マップ**（Native。上下が逆ならパネルの「上下入替」）: 下段 8 パッド（Note 72–79 / ch 2）で slot 1–8、上段（Note 64–71）で cut、Scene ボタン（CC 57 / ch 16）でタップテンポ、X-Y タッチ（CC 11）でカーソル発火。X/Y 軸は未割り当て（learn で hue / interval などに）。Touch Scale の `92/82/B2` は無視。
ベロシティ cut は MIDI パネルの `cut ≥`（1–127）。空欄でオフ。強く叩いたら cut、弱ければ選択中 preset。
### 手札の保存
バンク（BASE + V1…V7）は **base Patch と bankSeed** だけを保存します。8 面そのものは持たず、同じ入力なら `buildSceneBank` が同じ手札を再生成します。
- **自動保存**: バンク / seed / トランジション / auto / カーソルが変わるたびに 500ms debounce で `localStorage` キー `vj-deck-banks-v1` の `current` を更新する（クラッシュ耐性）。Deck 起動時に `current` があれば **メイン窓の currentPatch を待たずに** 復元する。未保存なら従来どおり live から生成する
- **A〜H**: ツールバーの小ボタン。クリックで呼び出し、`Shift+クリック` で保存（上書き確認なし）。空は薄く表示。右クリック / 長押しで名前を編集。呼び出しはバンクを差し替えるだけで **pad は自動では叩かない**し **`seed:set` も送らない**（live の画は pad 1 などを押すまで変わらない）。menu の **seed を採用** を押すと `seed:set` が送られ、Settings.seed とメインの画の両方が作り直される
- **JSON**: `JSON copy` でいまのスナップショットをクリップボードへ。`menu` 内のテキストエリアに貼って `JSON paste`。別 PC・別ブラウザへ持てる
- **別 PC では画像が欠ける**: Patch は画像の hash 参照だけを持ち、ピクセルは同一オリジンの IndexedDB `vj-images` にある。別マシンへ JSON だけ持っていくとサンプラーは透明ダミーになる（スロットはラベルと detail で判別できる）
- **STALE**: 復元した base が現行 catalog で invalid（generatorVersion の更新など）。バンクはフォールバック（バリエーションが全部 BASE 相当）で出すので落ちない。`R` で live から取り直す
- **クリア**: menu 内の `clear current` → `confirm clear current`（2 段）。次回起動は live から生成する。A〜H は消さない
## テンポ同期（BPM 検出）
入力音声からリアルタイムに BPM を推定し、ビートグリッドを生成して各シーンのパルスやオートサイクルを音楽の拍に合わせます。パネルの **Tempo** セクションに現在の BPM とステータスチップ、拍位置を示す 4 つのドット（1 拍目＝ダウンビートを強調）が表示されます。
- **自動検出**: 低域（バス）のオンセットから自己相関で BPM を推定します。**四つ打ち（キックが規則的な曲）に強く**、ロックまでは**数秒**かかります。検出が安定すると `LOCK`、探索中は `SEARCH…` と表示されます。
- **フリーホイール**: 一度ロックすればビートグリッドは自走するので、**ブレイク中（無音区間）でも拍を刻み続けます**。曲が戻ると位相を緩やかに再同期します。
- **TAP / ×2 / ÷2 / AUTO ボタン**:
- **TAP**: ボタン（またはキーボードの `T`）を曲に合わせて 2 回以上叩くと、その間隔から手動で BPM を設定します（`TAP` 表示）。音声が止まっていても手動テンポでグリッドが回ります。
- **×2 / ÷2**: テンポを倍 / 半分にします（0.25〜4 倍の範囲）。ハーフタイム / ダブルタイムの曲に合わせるときに便利です。
- **AUTO**: 自動検出に戻します（倍率も 1× にリセット）。
- **小節単位オートサイクル**: Auto-cycle の **Sec / Bars** トグルを **Bars** にすると、秒ではなく**小節（4 拍 = 1 小節）単位**でシーンを自動切替します（1〜256 小節）。BPM がロック / タップされている間だけ進みます。
- **N バーごと自動ガチャ**: **🎲 Auto-gacha** を On にすると、指定した小節数ごとに look gacha のシードを自動で引き直します（1〜512 小節）。曲の展開に合わせて見た目が周期的に変わります。
> 検出は低域のオンセットを手がかりにするため、キックのはっきりした 4 つ打ち系で最も安定します。ビートが取りづらいジャンルでは **TAP** で手動設定するのが確実です。
## URL パラメータ
`?key=value` 形式で起動時の設定を上書きできます（localStorage より優先）。
| パラメータ | 例 | 説明 |
| --- | --- | --- |
| `scene` | `scene=aurora` | 起動時のシーン id（既定 `semantic-synth` / 2D: `bars` `waveform` `particles` `radial` `rings` `lissajous` / GPU: `fluid` `smoke` `lava` `aurora`） |
| `bg` | `bg=transparent` | 背景（`black` / `transparent`） |
| `ui` | `ui=hide` | コントロールパネルを最初から非表示にする（OBS 用） |
| `gain` | `gain=2` | 入力ゲイン（0.5 – 4） |
| `cycle` | `cycle=20` | オートサイクルの間隔（秒） |
| `autocycle` | `autocycle=1` | オートサイクルを ON にする（`1` / `true`） |
| `cyclemode` | `cyclemode=bars` | オートサイクルの単位（`seconds` / `bars`） |
| `cyclebars` | `cyclebars=16` | 小節単位オートサイクルの間隔（1 – 256 小節） |
| `autogacha` | `autogacha=1` | N バーごとの自動ガチャを ON にする（`1` / `true`） |
| `gachabars` | `gachabars=32` | 自動ガチャの間隔（1 – 512 小節） |
| `hue` | `hue=200` | 色相を固定（0 – 360、指定すると hue 固定モードになる） |
| `seed` | `seed=neon-tiger-042` | look gacha のシード（見た目の個性を決める文字列。最大 64 文字） |
| `device` | `device=<deviceId>` | 入力デバイス id を指定 |
| `overlay` | `overlay=rings` | シーンを2層合成する（下＝`scene`、上＝`overlay`）。未指定/`none`/`off`/`0` で無効 |
| `blend` | `blend=screen` | オーバーレイ合成モード（`normal` / `screen` / `multiply` / `overlay` / `difference` / `exclusion` / `color-dodge` / `hard-light` / `lighten` / `darken`）。オーバーレイ有効時のみ。未指定は `normal`（従来どおり） |
| `mirror` | `mirror=1` | 中継に表示専用（mirror）として接続する。`room` または `bridge` と併用。応答は返さず同じコマンドを映像に反映するだけ |
| `deck` | `deck=1` | Scene Deck 窓として開く（`1` / `true`）。Audio / Renderer は起動しない |
例: 透過背景・パネル非表示・パーティクルシーンで起動
```
http://localhost:5173/?scene=particles&bg=transparent&ui=hide&gain=2
```
複数台の端末に同じ映像を出したいときは、1 台を通常の synth（`room` / `bridge` のみ）として接続し、残りを `mirror=1` 付きで開きます。mirror は表示専用で何台でも接続でき、中継からのコマンドを映像に反映するだけで応答は返しません。
### シーンオーバーレイ（2層合成）
`overlay` パラメータを指定すると、下のレイヤーの `scene`（既定 `semantic-synth`）の上に、もう1つのシーンを重ねて合成描画できます。両レイヤーとも同じ音声解析結果（gain / hue / variation）を共有するので、見た目の一貫性は保たれたまま2つのビジュアルが重なります。
```
http://localhost:5173/?scene=semantic-synth&overlay=rings
```
ブレンドモードを付ける例:
```
http://localhost:5173/?scene=semantic-synth&overlay=rings&blend=screen
```
- **URL 指定のみ**: `scene` などと違い `overlay` は localStorage に保存されません。一度 `?overlay=rings` を開いただけでオーバーレイが固定されてしまわないようにするための仕様です。
- **不正な値は警告のうえ無視**: 未知のシーン id や、ベースシーンと同じ id を指定した場合はオーバーレイを無効化し、コンソールに警告を出します（画面は通常描画のまま）。無効化は `none` / `off` / `0`（大小文字不問）でも明示できます。
- **ベースシーンの切り替えは独立**: `1`–`9` / `[` `]` / シーンピッカーでベースシーンを切り替えても、オーバーレイは指定したまま維持されます。切り替え先がオーバーレイと同じシーンになった場合は、その間だけオーバーレイが一時的に抑制されます。
- **パフォーマンス**: 2層分の描画コストがかかるため、GPU シーン同士を重ねるなど負荷の高い組み合わせでは fps に注意してください。
- **`blend`（合成モード）**: 上レイヤー（オーバーレイ）に対して効きます。キャンバスが分かれている組み合わせ（2D ベース + GL オーバーレイ / GL ベース + 2D オーバーレイ）では CSS `mix-blend-mode` を上側キャンバスに適用します。2D+2D（同一キャンバス）ではオーバーレイ描画パスだけ `globalCompositeOperation` を切り替えます。GL+GL は共有コンテキストのため CSS が使えず、非 `normal` 指定時はコンソールに警告を出し既存の GL ブレンドのまま描画します。`blend` も URL 専用で localStorage には保存されません。不正値は警告のうえ `normal` にフォールバックします。オーバーレイが無いときはブレンドは適用されません。Bridge 接続時は CLI からも切り替えできます: `node scripts/vj-ctl.mjs blend screen`（`state` の `blendMode` で確認）。
## OBS ブラウザソースとして使う
1. OBS で **ソース → 追加 → ブラウザ** を選びます。
2. **URL** に上記の URL パラメータ付きアドレスを入力します。オーバーレイ用途では透過＋パネル非表示が便利です:
```
http://localhost:5173/?bg=transparent&ui=hide&scene=radial
```
（`pnpm build` 後に `pnpm preview` やホスティング先の URL を使ってもかまいません。）
3. **幅 / 高さ** を出力解像度に合わせます（例: 1920 × 1080）。
4. `bg=transparent` を付けておけばキャンバスは透過のままなので、他のソースの上に重ねられます。
### デスクトップ音声（曲）に反応させたい場合
ブラウザの「マイク入力」はマイクの音しか拾いません。BGM や DAW の音に反応させるには、**ループバック（仮想オーディオ）デバイス**を入力に選びます。
- **Windows**: [VB-CABLE](https://vb-audio.com/Cable/) などの仮想オーディオデバイスを入れ、再生先を CABLE Input に、本ツールの Input device を **CABLE Output** に設定します。
- **macOS**: [BlackHole](https://existential.audio/blackhole/) や Loopback を使い、同様に仮想デバイスを入力に選びます。
- **Linux (PulseAudio / PipeWire)**: 出力デバイスの **Monitor**（例: `Monitor of ...`）を Input device に選ぶとデスクトップ音声を取り込めます。
> OBS のブラウザソース自体は、ページ内で `getUserMedia` を使う本ツールでは「ページの音声を OBS で制御」設定とは無関係です。音声解析はあくまでページ側（ブラウザ）で行われます。OBS のブラウザソース内で `getUserMedia` を使う場合、OBS / OS 側でマイク（仮想デバイス）アクセスが許可されている必要があります。
## ビルド
```bash
pnpm build # tsc -b && vite build（型チェック込み）
pnpm preview # ビルド成果物をローカルで確認
```
`dist/` に静的ファイルが出力されるので、任意の静的ホスティングに配置できます。
## 開発ツール
Semantic Synth の VisualPatch（JSON）を送信前にローカルで検証する CLI を同梱しています。CLI から操縦・自動化する経路もあります: `scripts/vj-ctl.mjs` は 1 コマンドずつ叩く低レベル CLI、`scripts/vj-set.mjs` は本番用のセット（複数シーン）を Timeline に "cue" として仕込み、演奏中に手で進める高レベル CLI です。使い方の全体は `.claude/skills/vj-director/SKILL.md` を参照してください。
### vj:validate
```bash
pnpm vj:validate patch.json
```
`src/synth/validate.ts` / `src/synth/cost.ts` を Vite の SSR モジュールローダーで直接実行するので、検証ルールの複製はありません。
### オフライン Patch プレビュー（`vj:preview`）
LLM / 人間のディレクターが GLSL を読んで見た目を**推測**する代わりに、Patch をローカル GPU で描いて PNG にする CLI です。bridge や本番シーンには繋ぎません（`measure:coverage` と同じヘッドレス Chromium 経路）。
```bash
# カタログ全 Generator のコンタクトシート（いちばん使う）
pnpm vj:preview --contact-sheet artifacts/contact-sheet.png
# seed から derive した Patch のフィルムストリップ（複数時刻）
pnpm vj:preview --seed take-1 artifacts/seed.png
# 手書き / 生成した VisualPatch JSON
pnpm vj:preview path/to/patch.json artifacts/patch.png
# 1 パラメータを min..max で横並びスイープ
pnpm vj:preview --sweep gamma.curve artifacts/sweep.png
```
- ヘッドレス Chromium が必要です。`nix develop` に入ると `CHROMIUM_BIN` が通ります（Playwright は単体では `CHROMIUM_BIN` を読まないので、ハーネス側が `launch()` に渡しています）。
- source 以外のソロ描画は coverage 測定と同じく基準 source `grid` の上に載せます（`mod_coord` だけ source より前）。パラメータはカタログの default です。
- 用途の中心は**コンタクトシートでカタログを目で見てから** Patch を組むこと。GLSL を先に読まない。
### recipe（`vj-recipe.mjs`）— ムード + seed + tweaks を JSON で持ち回る
`src/synth/validate.ts` は `VisualOperator` の `generatorVersion` が catalog の現行 version と厳密に一致することを要求し、catalog は各 generator の最新版しか保持しません。そのため生の Patch JSON をそのままリポジトリに置くと、generator の version が上がった瞬間に静かに壊れてしまいます。**recipe**（`recipes/*.json`）はこの問題を避けるため、Patch そのものではなく「ムード語 + seed（`vj-gen.mjs` へ渡す）+ 差分トークン列（`vj-tweak.mjs` 形式）」という作り直し可能な指示書だけを保存します。小さくて diff しやすく、catalog がどれだけ変わっても現行 catalog に対して作り直せます。
- `recipes/*.json` … 個々の recipe（`{ name, mood, seed, tweaks, notes }`）
- `recipes/setlists/*.json` … 複数の recipe を時間軸に並べたセットリスト（データのみ。実行 CLI は別途）
```bash
# 一覧表示（通信なし）
node scripts/vj-recipe.mjs list
# 中身を見る（通信なし）
node scripts/vj-recipe.mjs show humid-qilou-night
# mood+seed から作り直し、tweaks を重ねた draft を確認する（送信しない）
node scripts/vj-recipe.mjs apply humid-qilou-night --url wss://example.workers.dev/room/xxxx --dry-run
# 検証を通ったら送る
node scripts/vj-recipe.mjs apply humid-qilou-night --url wss://example.workers.dev/room/xxxx
```