@onjmin/dtm 0.1.32 → 0.1.34

package/dist/index.d.mts

@@ -407,6 +407,18 @@ type AddNoteOptions = {
     noteLengthSteps: number;
     velocity?: number;
 };
+/** パッチ送受信用ノートデータ（ローカルIDを持たない）。 */
+type NoteData = {
+    startStep: number;
+    pitch: number;
+    durationSteps: number;
+    velocity?: number;
+};
+/** パッチ削除指定（startStep + pitch で音符を特定）。 */
+type NoteRemove = {
+    startStep: number;
+    pitch: number;
+};
 type PianoRollOptions = {
     mountTarget: HTMLElement;
     width?: number;
@@ -563,6 +575,20 @@ type DawOptions = {
      * 利用側が選択状態を永続化する用途に使う。
      */
     onViewStateChange?: (state: DawViewState) => void;
+    /**
+     * ユーザー操作によってノートが追加・削除されたときに呼ばれる（差分パッチ）。
+     * リアルタイム同期のための送信フックとして使う。
+     * `applyPatch` による適用時には呼ばれない（エコーループ防止）。
+     */
+    onNotesPatch?: (trackId: string, added: NoteData[], removed: NoteRemove[]) => void;
+    /**
+     * 編集をロックするトラックIDの配列。
+     * 指定されたトラックへのユーザー操作（音符追加・削除）は無視される。
+     * 協力DAWで他人のトラックを誤編集しないために使う。
+     */
+    lockedTracks?: string[];
+    /** 初期アクティブトラックID（未指定なら最初のトラック）。協力DAWで自分のトラックを初期選択するために使う。 */
+    initialActiveTrack?: string;
     parseMidi?: ParseMidiFn;
     /**
      * 動作モード（{@link DawMode}）。
@@ -611,6 +637,22 @@ type DawInstance = {
     getCurrentPlayStep: () => number;
     forcePauseAt: (step: number) => void;
     setLoading?: (loading: boolean) => void;
+    /**
+     * リモートから受信したパッチをローカルに適用する。
+     * `onNotesPatch` は発火しない（エコーループ防止）。
+     * 音符の識別は (startStep, pitch) ペアで行う（ローカルIDに依存しない）。
+     */
+    applyPatch: (trackId: string, added: NoteData[], removed: NoteRemove[]) => void;
+    /**
+     * 指定トラックの音符をキャンバス上で表示・非表示にする（目ミュート）。
+     * 非表示にしても内部データは保持される。
+     */
+    setTrackVisible: (trackId: string, visible: boolean) => void;
+    /**
+     * 指定トラックの発音を有効・無効にする（音ミュート）。
+     * false にすると onPlayNote が呼ばれなくなる。
+     */
+    setTrackAudible: (trackId: string, audible: boolean) => void;
     destroy: () => void;
 };
 type LoopPoint = {
@@ -651,6 +693,158 @@ declare const TRACKS_ADVANCED: TrackConfig[];
  */
 declare const mountDAW: (target: HTMLElement, options?: DawOptions) => DawInstance;
 
+/**
+ * playMML — DOM非依存（ヘッドレス）の MML 再生関数。
+ *
+ * mountMmlPlayer が「絵文字・プレイヘッド付きの再生ビュー」なのに対し、こちらは
+ * 画面を一切持たず音だけを鳴らす。ゲームの BGM のように「文字列を渡して鳴らし、
+ * 止めたいときに止める」用途を想定している。
+ *
+ * 設計の要点:
+ *   - 発音そのものは Web Audio のオーディオスレッド上で行われる（未来時刻に予約するため
+ *     メインスレッドの負荷と独立して鳴る）。スケジューラは createSequencer の先読み方式。
+ *   - `loop: true` で曲末停止せずシームレスにループ（BGM用）。
+ *   - AudioContext を外から注入でき、出力先ノード（ゲームのマスターGain/ミキサー）へ繋げる。
+ *   - タブが非アクティブになったら一時停止する挙動を、ctx の所有権に応じて自動で行う:
+ *       内部生成 ctx … 既定で suspend/resume する（自分の ctx なので止めてよい）。
+ *       注入 ctx     … 既定では触らない（SE 等と共有している可能性があるため）。
+ *                      代わりに返り値の suspend()/resume() を呼び出し側から叩ける。
+ *
+ * 歌声合成（@@n 歌詞トラック）はこのヘッドレス関数では未対応（楽器・ドラムのみ）。
+ * 歌声が必要なら mountMmlPlayer / createDtmStudio を使う。
+ */
+
+type PlayMmlOptions = {
+    /** ループ設定（true=全体ループ、LoopConfig=特定範囲ループ、false/省略=ループなし） */
+    loop?: boolean | LoopConfig;
+    /** 再生中にイベントを発火させるタイミング */
+    cues?: PlaybackCue[];
+    /** キューポイント通過時のコールバック */
+    onCue?: (cueId: string) => void;
+    /**
+     * 使用する AudioContext。省略時は内部生成し、destroy()/stop() で閉じる。
+     * onPlayNote で自前シンセを鳴らす場合は、時計をそろえるため自分の ctx を渡すこと。
+     */
+    audioContext?: AudioContext;
+    /** 出力先ノード（省略時は ctx.destination）。ゲームのマスターGain 等へ繋ぐ。 */
+    destination?: AudioNode;
+    /** 0-100 のマスタ音量。既定は MML の #volume → このオプション → 100 の順で解決。 */
+    volume?: number;
+    /** BPM未検出時のフォールバック。既定120 */
+    defaultBpm?: number;
+    /** ドラムパターン辞書。`#drum=<キー>` の解決に使う。既定 DRUM_PATTERNS */
+    drumPatterns?: Record<string, DrumPattern>;
+    /** 内蔵 square synth を使うか。既定は onPlayNote 未指定なら true */
+    synth?: boolean;
+    /** メロディックノートの発音要求（自前シンセに繋ぐ）。 */
+    onPlayNote?: (e: PlayNoteEvent) => void;
+    /** ドラムノートの発音要求。 */
+    onPlayDrum?: (e: PlayDrumEvent) => void;
+    /** 再生開始時に呼ばれる（追加の resume 処理等に使う）。 */
+    onResumeAudio?: () => void | Promise<void>;
+    /**
+     * タブ非アクティブ時に自動で suspend/resume するか。
+     * 既定は「内部生成 ctx のとき true / 注入 ctx のとき false」。
+     * 注入 ctx で true にすると、共有 ctx ごと suspend する点に注意。
+     */
+    pauseWhenHidden?: boolean;
+    /** ループ無効時に曲末（または stop()）で呼ばれる。 */
+    onStop?: () => void;
+};
+type MmlPlayback = {
+    /** 再生を止める（ループ中でも停止）。 */
+    stop: () => void;
+    isPlaying: () => boolean;
+    /** マスタ音量を 0-100 で変更する（再生中も即時反映）。 */
+    setVolume: (volume: number) => void;
+    /** AudioContext を suspend（注入 ctx の場合、共有先も止まる点に注意）。 */
+    suspend: () => Promise<void>;
+    /** suspend からの復帰。 */
+    resume: () => Promise<void>;
+    /** 停止し、内部生成 ctx なら閉じてリスナも解除する。 */
+    destroy: () => void;
+};
+/**
+ * MML 文字列を画面なしで再生する。呼び出した時点で再生を開始する。
+ * ブラウザの自動再生ポリシー上、初回はユーザー操作のコールスタック内で呼ぶこと。
+ */
+declare const playMML: (mml: string, options?: PlayMmlOptions) => MmlPlayback;
+
+/**
+ * playSingingMML — 歌声付き（@@n 歌詞トラック）のヘッドレス MML 再生。【未実装スタブ】
+ *
+ * 楽器・ドラムのみの {@link playMML} とは別関数として切り出す。歌声は重い WORLD 再合成・
+ * worker のホスティング・非同期プリロードを伴うため、軽量な playMML に混ぜず分離する方針。
+ * 中身は実質「mountMmlPlayer の音響経路（sequencer + 内蔵synth + 歌声ストリーム配線）から
+ * DOM を抜いたもの」になる予定。
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * 実装メモ / 懸念事項（実装する人へ）
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * ■ 全体の構成（実装方針）
+ *   1. parseMML(mml, { collectLyrics: true }) で placements / lyrics / meta を取る。
+ *   2. 楽器トラックは playMML と同じく seqTracks 化 → createSequencer + createSynth で再生。
+ *   3. 歌声は createSingingVoices(ctx, destination, { voiceWorkerUrl }) を生成し、
+ *      mml-player.ts の buildStreamTracks 相当で StreamVoiceTrack[] を構築。
+ *   4. loadModels → warm を await（ここがローディング相当）。完了後に
+ *      seq.start(0) と voices.startStream(tracks, seq.getStartTime()) を「同じアンカー」で開始。
+ *      ※ 既存の正準実装は mml-player.ts の startWhenReady()。ほぼそのまま流用できる。
+ *
+ * ■ 非同期プリロードがあるため、この関数は Promise を返す（fire-and-forget にしない）。
+ *   loadModels/warm の完了を待ってから resolve する。待機中に stop された場合は起動しない
+ *   ガードが要る（mml-player.ts の `if (!playing || activePlayer !== instance) return;` 相当）。
+ *
+ * ■ worker URL は利用側がホストする（必須）。createSingingVoices の voiceWorkerUrl に渡す。
+ *   省略時はメインスレッド合成にフォールバックするが、BGM 用途では worker 必須を推奨。
+ *   あるいは既存の singingVoices インスタンスを注入できるようにする（createDtmStudio と同様）。
+ *
+ * ■【最大の懸念】シームレスループと歌声ストリームが噛み合わない
+ *   - 今回 sequencer に入れたループは「先読みタイムラインを永久に再アーム」する方式
+ *     （sequencer.ts の loopBase += loopLengthSec）。楽器はこれで継ぎ目なくループする。
+ *   - 一方 startStream は【1セッション制】。startStream を呼び直すと streamSession が増えて
+ *     前のループが中断される（lyrics.ts:1402 / 1421）。よって「次周を裏で先行スケジュール」は
+ *     前周をキャンセルしてしまうため不可。
+ *   - さらに先読みは STREAM_LOOKAHEAD_SEC = 1.5 秒（lyrics.ts:1276）。曲末ぎりぎりで
+ *     startStream を再発行すると、まだ合成待ちだった末尾〜1.5秒の歌が毎周ドロップする。
+ *   → 「境界で呼び直す」方式は継ぎ目が汚れる/歌が欠ける。採用しないこと。
+ *
+ * ■【推奨する解】startStream 自体をループ対応にする（lyrics.ts の小改修）
+ *   sequencer.ts と同じ要領で、startStream({ loopLengthSec }) を受け取り、runTrack の
+ *   items を一巡したら i=0 に戻して内部オフセットへ loopLengthSec を加算する。
+ *   1セッションのまま先読みが途切れず、継ぎ目もドロップも出ない。loopLengthSec は楽器側
+ *   （sequencer の loopLengthSec）と同一値を共有すれば、伴奏と歌が同周期で永久に揃う。
+ *   ※ この改修が入るまでは loop:true を歌入りで使うとズレる。下のガード参照。
+ *
+ * ■ AudioContext / visibility は playMML と同じ方針（ctx 所有権で suspend 権限を分ける）。
+ *   ただし注入 ctx + 注入 destination を createSingingVoices にもそのまま渡すこと
+ *   （歌声と楽器を同じミキサーへ流す）。
+ *
+ * ■ stop/destroy では seq.stop() に加えて voices.stopStream()（+ 内部生成なら ctx.close）
+ *   とモデルの後始末（reset）を忘れない。
+ *
+ * 関連: {@link playMML}（楽器のみ）, mml-player.ts（DOM版の正準実装）, lyrics.ts（歌声合成）。
+ */
+
+type PlaySingingMmlOptions = PlayMmlOptions & {
+    /**
+     * 歌声合成 Worker（`voice-worker.js`）のURL。利用側がホストして渡す。
+     * 省略時はメインスレッド合成へフォールバック（BGM用途では worker 推奨）。
+     */
+    voiceWorkerUrl?: string;
+    /**
+     * 既存の歌唱合成ヘルパを注入する（createDtmStudio と同様の配線を流用したい場合）。
+     * 指定時は voiceWorkerUrl より優先し、内部で createSingingVoices しない。
+     */
+    singingVoices?: SingingVoices;
+};
+/**
+ * 歌声付き MML を画面なしで再生する。【未実装】
+ *
+ * @throws 現状は常に未実装エラーを投げる。実装方針は本ファイル冒頭の実装メモを参照。
+ */
+declare const playSingingMML: (_mml: string, _options?: PlaySingingMmlOptions) => Promise<MmlPlayback>;
+
 /**
  * インラインSVGアイコン。外部アイコンフォント(MDI等)への依存を避けるため、
  * 必要最小限のパスをライブラリ内に同梱する。
@@ -908,184 +1102,6 @@ type ExportMidiOptions = {
  */
 declare const exportMIDI: (options: ExportMidiOptions) => Blob;
 
-/**
- * playMML — DOM非依存（ヘッドレス）の MML 再生関数。
- *
- * mountMmlPlayer が「絵文字・プレイヘッド付きの再生ビュー」なのに対し、こちらは
- * 画面を一切持たず音だけを鳴らす。ゲームの BGM のように「文字列を渡して鳴らし、
- * 止めたいときに止める」用途を想定している。
- *
- * 設計の要点:
- *   - 発音そのものは Web Audio のオーディオスレッド上で行われる（未来時刻に予約するため
- *     メインスレッドの負荷と独立して鳴る）。スケジューラは createSequencer の先読み方式。
- *   - `loop: true` で曲末停止せずシームレスにループ（BGM用）。
- *   - AudioContext を外から注入でき、出力先ノード（ゲームのマスターGain/ミキサー）へ繋げる。
- *   - タブが非アクティブになったら一時停止する挙動を、ctx の所有権に応じて自動で行う:
- *       内部生成 ctx … 既定で suspend/resume する（自分の ctx なので止めてよい）。
- *       注入 ctx     … 既定では触らない（SE 等と共有している可能性があるため）。
- *                      代わりに返り値の suspend()/resume() を呼び出し側から叩ける。
- *
- * 歌声合成（@@n 歌詞トラック）はこのヘッドレス関数では未対応（楽器・ドラムのみ）。
- * 歌声が必要なら mountMmlPlayer / createDtmStudio を使う。
- */
-
-type PlayMmlOptions = {
-    /** ループ設定（true=全体ループ、LoopConfig=特定範囲ループ、false/省略=ループなし） */
-    loop?: boolean | LoopConfig;
-    /** 再生中にイベントを発火させるタイミング */
-    cues?: PlaybackCue[];
-    /** キューポイント通過時のコールバック */
-    onCue?: (cueId: string) => void;
-    /**
-     * 使用する AudioContext。省略時は内部生成し、destroy()/stop() で閉じる。
-     * onPlayNote で自前シンセを鳴らす場合は、時計をそろえるため自分の ctx を渡すこと。
-     */
-    audioContext?: AudioContext;
-    /** 出力先ノード（省略時は ctx.destination）。ゲームのマスターGain 等へ繋ぐ。 */
-    destination?: AudioNode;
-    /** 0-100 のマスタ音量。既定は MML の #volume → このオプション → 100 の順で解決。 */
-    volume?: number;
-    /** BPM未検出時のフォールバック。既定120 */
-    defaultBpm?: number;
-    /** ドラムパターン辞書。`#drum=<キー>` の解決に使う。既定 DRUM_PATTERNS */
-    drumPatterns?: Record<string, DrumPattern>;
-    /** 内蔵 square synth を使うか。既定は onPlayNote 未指定なら true */
-    synth?: boolean;
-    /** メロディックノートの発音要求（自前シンセに繋ぐ）。 */
-    onPlayNote?: (e: PlayNoteEvent) => void;
-    /** ドラムノートの発音要求。 */
-    onPlayDrum?: (e: PlayDrumEvent) => void;
-    /** 再生開始時に呼ばれる（追加の resume 処理等に使う）。 */
-    onResumeAudio?: () => void | Promise<void>;
-    /**
-     * タブ非アクティブ時に自動で suspend/resume するか。
-     * 既定は「内部生成 ctx のとき true / 注入 ctx のとき false」。
-     * 注入 ctx で true にすると、共有 ctx ごと suspend する点に注意。
-     */
-    pauseWhenHidden?: boolean;
-    /** ループ無効時に曲末（または stop()）で呼ばれる。 */
-    onStop?: () => void;
-};
-type MmlPlayback = {
-    /** 再生を止める（ループ中でも停止）。 */
-    stop: () => void;
-    isPlaying: () => boolean;
-    /** マスタ音量を 0-100 で変更する（再生中も即時反映）。 */
-    setVolume: (volume: number) => void;
-    /** AudioContext を suspend（注入 ctx の場合、共有先も止まる点に注意）。 */
-    suspend: () => Promise<void>;
-    /** suspend からの復帰。 */
-    resume: () => Promise<void>;
-    /** 停止し、内部生成 ctx なら閉じてリスナも解除する。 */
-    destroy: () => void;
-};
-/**
- * MML 文字列を画面なしで再生する。呼び出した時点で再生を開始する。
- * ブラウザの自動再生ポリシー上、初回はユーザー操作のコールスタック内で呼ぶこと。
- */
-declare const playMML: (mml: string, options?: PlayMmlOptions) => MmlPlayback;
-
-/**
- * playSingingMML — 歌声付き（@@n 歌詞トラック）のヘッドレス MML 再生。【未実装スタブ】
- *
- * 楽器・ドラムのみの {@link playMML} とは別関数として切り出す。歌声は重い WORLD 再合成・
- * worker のホスティング・非同期プリロードを伴うため、軽量な playMML に混ぜず分離する方針。
- * 中身は実質「mountMmlPlayer の音響経路（sequencer + 内蔵synth + 歌声ストリーム配線）から
- * DOM を抜いたもの」になる予定。
- *
- * ─────────────────────────────────────────────────────────────────────────
- * 実装メモ / 懸念事項（実装する人へ）
- * ─────────────────────────────────────────────────────────────────────────
- *
- * ■ 全体の構成（実装方針）
- *   1. parseMML(mml, { collectLyrics: true }) で placements / lyrics / meta を取る。
- *   2. 楽器トラックは playMML と同じく seqTracks 化 → createSequencer + createSynth で再生。
- *   3. 歌声は createSingingVoices(ctx, destination, { voiceWorkerUrl }) を生成し、
- *      mml-player.ts の buildStreamTracks 相当で StreamVoiceTrack[] を構築。
- *   4. loadModels → warm を await（ここがローディング相当）。完了後に
- *      seq.start(0) と voices.startStream(tracks, seq.getStartTime()) を「同じアンカー」で開始。
- *      ※ 既存の正準実装は mml-player.ts の startWhenReady()。ほぼそのまま流用できる。
- *
- * ■ 非同期プリロードがあるため、この関数は Promise を返す（fire-and-forget にしない）。
- *   loadModels/warm の完了を待ってから resolve する。待機中に stop された場合は起動しない
- *   ガードが要る（mml-player.ts の `if (!playing || activePlayer !== instance) return;` 相当）。
- *
- * ■ worker URL は利用側がホストする（必須）。createSingingVoices の voiceWorkerUrl に渡す。
- *   省略時はメインスレッド合成にフォールバックするが、BGM 用途では worker 必須を推奨。
- *   あるいは既存の singingVoices インスタンスを注入できるようにする（createDtmStudio と同様）。
- *
- * ■【最大の懸念】シームレスループと歌声ストリームが噛み合わない
- *   - 今回 sequencer に入れたループは「先読みタイムラインを永久に再アーム」する方式
- *     （sequencer.ts の loopBase += loopLengthSec）。楽器はこれで継ぎ目なくループする。
- *   - 一方 startStream は【1セッション制】。startStream を呼び直すと streamSession が増えて
- *     前のループが中断される（lyrics.ts:1402 / 1421）。よって「次周を裏で先行スケジュール」は
- *     前周をキャンセルしてしまうため不可。
- *   - さらに先読みは STREAM_LOOKAHEAD_SEC = 1.5 秒（lyrics.ts:1276）。曲末ぎりぎりで
- *     startStream を再発行すると、まだ合成待ちだった末尾〜1.5秒の歌が毎周ドロップする。
- *   → 「境界で呼び直す」方式は継ぎ目が汚れる/歌が欠ける。採用しないこと。
- *
- * ■【推奨する解】startStream 自体をループ対応にする（lyrics.ts の小改修）
- *   sequencer.ts と同じ要領で、startStream({ loopLengthSec }) を受け取り、runTrack の
- *   items を一巡したら i=0 に戻して内部オフセットへ loopLengthSec を加算する。
- *   1セッションのまま先読みが途切れず、継ぎ目もドロップも出ない。loopLengthSec は楽器側
- *   （sequencer の loopLengthSec）と同一値を共有すれば、伴奏と歌が同周期で永久に揃う。
- *   ※ この改修が入るまでは loop:true を歌入りで使うとズレる。下のガード参照。
- *
- * ■ AudioContext / visibility は playMML と同じ方針（ctx 所有権で suspend 権限を分ける）。
- *   ただし注入 ctx + 注入 destination を createSingingVoices にもそのまま渡すこと
- *   （歌声と楽器を同じミキサーへ流す）。
- *
- * ■ stop/destroy では seq.stop() に加えて voices.stopStream()（+ 内部生成なら ctx.close）
- *   とモデルの後始末（reset）を忘れない。
- *
- * 関連: {@link playMML}（楽器のみ）, mml-player.ts（DOM版の正準実装）, lyrics.ts（歌声合成）。
- */
-
-type PlaySingingMmlOptions = PlayMmlOptions & {
-    /**
-     * 歌声合成 Worker（`voice-worker.js`）のURL。利用側がホストして渡す。
-     * 省略時はメインスレッド合成へフォールバック（BGM用途では worker 推奨）。
-     */
-    voiceWorkerUrl?: string;
-    /**
-     * 既存の歌唱合成ヘルパを注入する（createDtmStudio と同様の配線を流用したい場合）。
-     * 指定時は voiceWorkerUrl より優先し、内部で createSingingVoices しない。
-     */
-    singingVoices?: SingingVoices;
-};
-/**
- * 歌声付き MML を画面なしで再生する。【未実装】
- *
- * @throws 現状は常に未実装エラーを投げる。実装方針は本ファイル冒頭の実装メモを参照。
- */
-declare const playSingingMML: (_mml: string, _options?: PlaySingingMmlOptions) => Promise<MmlPlayback>;
-
-/**
- * 内蔵の簡易square-wave synth + ノイズ系ドラム音。
- *
- * もともと mml-player.ts の中にインラインで持っていたものを、DOM非依存の発音器として
- * 切り出したもの。これにより mountMmlPlayer（DOMビュー）と playMML（ヘッドレス）の双方が
- * 同じ発音ロジックを共有できる。
- *
- * 設計上、AudioContext と出力先ノードは「外から渡す」。これは利用側が自前のマスターGain /
- * ミキサーへルーティングしたり、SE と AudioContext を共有したりできるようにするため。
- */
-
-/** MIDIピッチ番号 → 周波数(Hz)。A4(69)=440Hz 基準。 */
-declare const freqFromPitch: (pitch: number) => number;
-type Synth = {
-    /** メロディックノートを発音する（PlayNoteEvent.when は ctx.currentTime からの相対秒） */
-    playNote: (e: PlayNoteEvent) => void;
-    /** ドラムノートを発音する（General MIDI のドラムキー番号で音色を分岐） */
-    playDrum: (e: PlayDrumEvent) => void;
-};
-/**
- * AudioContext と出力先ノードを束ねた発音器を作る。
- * @param ctx 発音に使う AudioContext
- * @param destination 接続先（省略時は ctx.destination）。ゲーム側ミキサーへ繋ぐ用途。
- */
-declare const createSynth: (ctx: AudioContext, destination?: AudioNode) => Synth;
-
 /**
  * MML文字列を解析し、トラックごとのノート配置へ復元するローダ。
  *
@@ -1219,6 +1235,13 @@ type MmlPlayerOptions = {
     embedUrl?: string;
     /** 利用規約への同意画面の表示をスキップするかどうか */
     skipConsent?: boolean;
+    /**
+     * 「MMLを表示」「MMLコピー」押下時に呼ばれる MML 取得コールバック。
+     * 省略時は mountMmlPlayer に渡した mml をそのまま使う。
+     * DAW と連携する場合は `() => daw.getMML().full` を渡すと
+     * 常に最新の full フォーマット（メタ行・#end; 込み）を返せる。
+     */
+    getMml?: () => string;
 };
 type MmlPlayerInstance = {
     play: () => void;
@@ -1435,12 +1458,6 @@ type DtmStudioEngines = {
     SoundFont_list?: SoundFontListEngine;
     parseMidi?: DawOptions["parseMidi"];
 };
-/** 既定の取得元URL（rpgen3 / jsDelivr）。options.cdn で個別に上書きできる。 */
-declare const DEFAULT_CDN: {
-    readonly soundFont: "https://rpgen3.github.io/soundfont/mjs/surikov/SoundFont.mjs";
-    readonly soundFontDrum: "https://rpgen3.github.io/soundfont/mjs/surikov/SoundFont_drum.mjs";
-    readonly soundFontList: "https://rpgen3.github.io/soundfont/mjs/surikov/SoundFont_list.mjs";
-};
 type DtmStudioOptions = {
     /** 既存の AudioContext を使う（未指定なら内部生成）。 */
     audioContext?: AudioContext;
@@ -1456,10 +1473,20 @@ type DtmStudioOptions = {
     voiceWorkerUrl?: string | null;
     /** 初期の楽器プリセットキー（INSTRUMENT_PRESETS）。既定 "retro_game"。 */
     defaultPreset?: string;
-    /** 外部エンジンの注入（指定したものは CDN 取得をスキップ）。 */
+    /** 外部エンジンの注入（指定したものは組み込み実装をスキップ）。 */
     engines?: DtmStudioEngines;
-    /** CDN URL の上書き。 */
-    cdn?: Partial<typeof DEFAULT_CDN>;
+    /**
+     * koe音源（.koe）のベースURL。
+     * Discord Activity など CSP 制限下で `/.proxy/koe` を渡すと
+     * worker 内の fetch も同オリジン経由になり CSP を通過できる。
+     */
+    koeBaseUrl?: string;
+    /**
+     * worldline.js（WORLDボコーダ）のURL。
+     * Discord Activity など CSP 制限下で `/.proxy/koe-lib/demo/world/worldline.js`
+     * を渡すと worker 内の importScripts も同オリジン経由になり CSP を通過できる。
+     */
+    worldlineScriptUrl?: string;
     /** 有効化する機能。既定はすべて true。 */
     features?: {
         /** MIDIファイル読み込み。 */
@@ -1614,6 +1641,32 @@ declare const DAW_CSS = "\n@font-face {\n  font-family: 'k8x12';\n  src: url('ht
  */
 declare const injectStyles: (doc?: Document) => void;
 
+/**
+ * 内蔵の簡易square-wave synth + ノイズ系ドラム音。
+ *
+ * もともと mml-player.ts の中にインラインで持っていたものを、DOM非依存の発音器として
+ * 切り出したもの。これにより mountMmlPlayer（DOMビュー）と playMML（ヘッドレス）の双方が
+ * 同じ発音ロジックを共有できる。
+ *
+ * 設計上、AudioContext と出力先ノードは「外から渡す」。これは利用側が自前のマスターGain /
+ * ミキサーへルーティングしたり、SE と AudioContext を共有したりできるようにするため。
+ */
+
+/** MIDIピッチ番号 → 周波数(Hz)。A4(69)=440Hz 基準。 */
+declare const freqFromPitch: (pitch: number) => number;
+type Synth = {
+    /** メロディックノートを発音する（PlayNoteEvent.when は ctx.currentTime からの相対秒） */
+    playNote: (e: PlayNoteEvent) => void;
+    /** ドラムノートを発音する（General MIDI のドラムキー番号で音色を分岐） */
+    playDrum: (e: PlayDrumEvent) => void;
+};
+/**
+ * AudioContext と出力先ノードを束ねた発音器を作る。
+ * @param ctx 発音に使う AudioContext
+ * @param destination 接続先（省略時は ctx.destination）。ゲーム側ミキサーへ繋ぐ用途。
+ */
+declare const createSynth: (ctx: AudioContext, destination?: AudioNode) => Synth;
+
 declare const VOICE_IMAGES: Record<string, string>;
 
-export { type AddNoteOptions, type ApplyChordOptions, type ChordPatternType, type ChordPlacement, type ConsumedSyllable, type CoreEventHandlers, DAW_CSS, DEFAULT_BPM, DEFAULT_GATE, DEFAULT_PAN, DEFAULT_PLAYBACK_VELOCITY, DEFAULT_STEPS_PER_BAR, DEFAULT_VELOCITY, DEFAULT_VOCAL_VOLUME, DRUM_FONT, DRUM_KEYS, DRUM_PATTERNS, type DawInstance, type DawMode, type DawOptions, type DawViewState, type DrumPattern, type DtmStudio, type DtmStudioEngines, type DtmStudioOptions, type ExportMidiOptions, INSTRUMENT_PRESETS, type InstrumentPreset, KOE_BASE_URL, KOE_VOICEBANKS, KOE_VOICEBANK_LABELS, KOE_VOICEBANK_TERMS, type KoeVoiceOptions, LinkedList, type LoopConfig, type LoopPoint, type LyricSyllable, type LyricTrack, type LyricsConductor, MAX_VOCAL_VOLUME, MMLCore, type MMLDisplayToken, type MMLNotePlacement, MML_END_MARKER, type MidiExtraction, type MidiNotePlacement, type MidiTrackAnalysis, type MmlMeta, type MmlPlayback, type MmlPlayerInstance, type MmlPlayerOptions, type ModeSwitchInstance, type ModeSwitchOptions, type MountEditorOptions, type MountPlayerOptions, type Note, PITCH_MAP, PREWARM_NOTES, type ParseMMLOptions, type ParseMidiFn, type ParsedMML, type PianoRollInstance, type PianoRollOptions, type PitchToken, type PlayDrumEvent, type PlayMmlOptions, type PlayNoteEvent, type PlaySingingMmlOptions, type PlaybackCue, type PlaybackState, type PresetSelectInstance, type PresetSelectOptions, type PreviewSoundCallback, type RenderConfig, type Sequencer, type SequencerOptions, type SequencerTrack, type SingingVoices, type SingingVoicesOptions, type StreamPlaybackOptions, type StreamVoiceNote, type StreamVoiceTrack, type Synth, TRACKS_ADVANCED, TRACKS_SIMPLE, type ToolMode, type TrackConfig, VOICE_IMAGES, VOICE_IMAGE_KEY, type VoiceModel, type VoiceRegistry, analyzeMidiTracks, applyHarmonicFilter, applyMonophonic, buildChordPlacements, buildNameToKeyMapping, collectPitchTokens, createAudioContext, createDtmStudio, createKlattVoice, createKoeVoice, createLyricsConductor, createPianoRoll, createSequencer, createSingingVoices, createSynth, createVoiceRegistry, decodeMml, decomposeToMonophonic, drawGrid, drawHeader, drawKeyboard, drawNotes, drawSelectedNotes, drawSelectionRect, encodeMml, exportMIDI, extractMidiPlacements, extractMidiPlacementsByTrack, fetchSoundFontList, formatMmlMeta, freqFromPitch, generateRandomPattern, getDrawOffset, getGridCanvas, getGridContext, getGridPosition, getHeaderCanvas, getMidiBPM, getRenderConfig, getXY, icon, init, injectStyles, isChordHeavyTrack, koeUrl, mountDAW, mountMmlPlayer, normalizeLyrics, onClick, panToStereo, parseLyrics, parseMML, parseMmlMeta, playMML, playSingingMML, setDrawOffset, shiftNotes, stripLyrics, stripMmlMeta, vocalVolumeToGain };
+export { type AddNoteOptions, type ApplyChordOptions, type ChordPatternType, type ChordPlacement, type ConsumedSyllable, type CoreEventHandlers, DAW_CSS, DEFAULT_BPM, DEFAULT_GATE, DEFAULT_PAN, DEFAULT_PLAYBACK_VELOCITY, DEFAULT_STEPS_PER_BAR, DEFAULT_VELOCITY, DEFAULT_VOCAL_VOLUME, DRUM_FONT, DRUM_KEYS, DRUM_PATTERNS, type DawInstance, type DawMode, type DawOptions, type DawViewState, type DrumPattern, type DtmStudio, type DtmStudioEngines, type DtmStudioOptions, type ExportMidiOptions, INSTRUMENT_PRESETS, type InstrumentPreset, KOE_BASE_URL, KOE_VOICEBANKS, KOE_VOICEBANK_LABELS, KOE_VOICEBANK_TERMS, type KoeVoiceOptions, LinkedList, type LoopConfig, type LoopPoint, type LyricSyllable, type LyricTrack, type LyricsConductor, MAX_VOCAL_VOLUME, MMLCore, type MMLDisplayToken, type MMLNotePlacement, MML_END_MARKER, type MidiExtraction, type MidiNotePlacement, type MidiTrackAnalysis, type MmlMeta, type MmlPlayback, type MmlPlayerInstance, type MmlPlayerOptions, type ModeSwitchInstance, type ModeSwitchOptions, type MountEditorOptions, type MountPlayerOptions, type Note, type NoteData, type NoteRemove, PITCH_MAP, PREWARM_NOTES, type ParseMMLOptions, type ParseMidiFn, type ParsedMML, type PianoRollInstance, type PianoRollOptions, type PitchToken, type PlayDrumEvent, type PlayMmlOptions, type PlayNoteEvent, type PlaySingingMmlOptions, type PlaybackCue, type PlaybackState, type PresetSelectInstance, type PresetSelectOptions, type PreviewSoundCallback, type RenderConfig, type Sequencer, type SequencerOptions, type SequencerTrack, type SingingVoices, type SingingVoicesOptions, type StreamPlaybackOptions, type StreamVoiceNote, type StreamVoiceTrack, type Synth, TRACKS_ADVANCED, TRACKS_SIMPLE, type ToolMode, type TrackConfig, VOICE_IMAGES, VOICE_IMAGE_KEY, type VoiceModel, type VoiceRegistry, analyzeMidiTracks, applyHarmonicFilter, applyMonophonic, buildChordPlacements, buildNameToKeyMapping, collectPitchTokens, createAudioContext, createDtmStudio, createKlattVoice, createKoeVoice, createLyricsConductor, createPianoRoll, createSequencer, createSingingVoices, createSynth, createVoiceRegistry, decodeMml, decomposeToMonophonic, drawGrid, drawHeader, drawKeyboard, drawNotes, drawSelectedNotes, drawSelectionRect, encodeMml, exportMIDI, extractMidiPlacements, extractMidiPlacementsByTrack, fetchSoundFontList, formatMmlMeta, freqFromPitch, generateRandomPattern, getDrawOffset, getGridCanvas, getGridContext, getGridPosition, getHeaderCanvas, getMidiBPM, getRenderConfig, getXY, icon, init, injectStyles, isChordHeavyTrack, koeUrl, mountDAW, mountMmlPlayer, normalizeLyrics, onClick, panToStereo, parseLyrics, parseMML, parseMmlMeta, playMML, playSingingMML, setDrawOffset, shiftNotes, stripLyrics, stripMmlMeta, vocalVolumeToGain };