@onjmin/dtm 0.1.67 → 0.1.68

package/README.md

@@ -67,6 +67,7 @@ const bgm = playMML("@0 t120 o5 l8 ccggaag4 ffeeddc4", {
 });
 bgm.setVolume(50);
 
+```ts
 const chordPlayer = studio.mountChordPlayer(chordEl, "| C | G | Am | F |", {
   volume: 80,
 });
@@ -75,6 +76,22 @@ chordPlayer.setVolume(65);
 
 ---
 
+## 再生機能・API 一覧
+
+用途や UI の有無、歌声対応の有無に応じた各種再生関数が用意されています。
+
+| 関数名 | UI描画 (DOM) | 歌声対応 (`@@n`) | 戻り値 | 主な用途と効果 |
+| --- | --- | --- | --- | --- |
+| `playMML(mml, options)` | 不要 | 非対応 | `MmlPlayback` | 楽器・ドラムの MML ヘッドレス再生。軽量内蔵シンセで BGM シームレスループや Cues 同期イベントを発火。 |
+| `playSingingMML(mml, options)` | 不要 | **対応** | `Promise<MmlPlayback>` | 歌声付き MML のヘッドレス再生。画面なしで `.koe` / `klatt` 歌声モデルをプリロードし、伴奏と同期再生。 |
+| `playChords(chordStr, options)` | 不要 | 非対応 | `MmlPlayback` | コード進行のヘッドレス再生。`"\| C \| G \| Am \| F \|"` などの文字列からアルペジオ等の伴奏音を鳴らす。 |
+| `playNote(options)` | 不要 | 非対応 | `void` | 簡易単音発音。SE や音高確認のためのテスト発音。 |
+| `mountMmlPlayer(target, mml, options)` | **必要** | **対応** | `MmlPlayerInstance` | 再生専用 UI ビュー。トークン帯のハイライト、オートスクロール、歌声キャラクター表示を含む埋め込みプレイヤー。 |
+| `mountChordPlayer(target, chordStr, options)` | **必要** | 非対応 | `MmlPlayerInstance` | コード進行再生専用 UI コンポーネント。コードネーム表示と試聴操作。 |
+| `createDtmStudio()` / `mountEditor` | **必要** | **対応** | `DtmStudio` / `DawInstance` | フル機能ピアノロールエディタ UI。SoundFont 演奏、マウス打ち込み編集、歌声合成、録音機能を提供。 |
+
+---
+
 ## モード（`simple` / `advanced`）
 
 トラック構成と MIDI の取り込み方が異なる 2 つのモードがあります。`mode` オプションで切り替え、合わせて `tracks` に対応するトラック構成（`TRACKS_SIMPLE` / `TRACKS_ADVANCED`）を渡します。
@@ -235,7 +252,28 @@ const bgm = playMML(mml, {
 });
 ```
 
-### 2. コード進行ヘッドレス再生 (`playChords`)
+### 2. 歌声付き MML ヘッドレス再生 (`playSingingMML`)
+
+歌声トラック（`@@n`）を含む MML を画面なしで再生するための関数です。歌声モデル（`klatt` または UTAU `.koe` 音源）の非同期プリロード・頭出し合成を行ってから再生を開始するため、`Promise<MmlPlayback>` を返します。
+
+```ts
+import { playSingingMML } from "@onjmin/dtm";
+
+const bgm = await playSingingMML("@@klatt カエルのウタガ;\nt120 o4 c d e f;", {
+  loop: true,               // シームレスループ対応（伴奏と歌声が同期して永久ループ）
+  volume: 80,
+  voiceWorkerUrl: "./voice-worker.js", // オプション（Worker を指定するとメインスレッドの負荷を軽減）
+});
+
+bgm.setVolume(50);   // 再生中も音量を即時反映
+bgm.stop();          // 停止
+bgm.destroy();       // 停止＋モデルと AudioContext の解放
+```
+
+- 楽器・ドラムの再生機能に加えて、`@@n` トラックの歌声を自動でロード・ストリーミング再生します。
+- `loop: true` や特定範囲の `loop` 指定時も、伴奏と歌声がピッタリ同期してシームレスにループします。
+
+### 3. コード進行ヘッドレス再生 (`playChords`)
 
 コード進行テキストを渡して、伴奏パターン（軽量シンセ）のみをヘッドレスで鳴らすための関数です。
 
@@ -261,8 +299,7 @@ chords.destroy(); // 停止＋AudioContextの解放
   - `"yatsume"`: 八つ目（特定のリズムパターン）
   - `"alternating"`: 交互に伴奏音を鳴らす
 
-> 歌声合成（`@@n` 歌詞トラック）はヘッドレス再生では未対応です（楽器・ドラムのみ）。
-> 歌声が必要なら `mountMmlPlayer` / `createDtmStudio` を使ってください。
+> 歌声合成（`@@n` 歌詞トラック）を含むヘッドレス再生には `playSingingMML` を使用してください。楽器・ドラムのみの軽量再生には `playMML` を使用できます。
 
 ---
 

package/dist/index.d.mts

@@ -373,6 +373,10 @@ type StreamPlaybackOptions = {
      * t0 は発音予定の AudioContext 絶対時刻。
      */
     onScheduled?: (track: StreamVoiceTrack, note: StreamVoiceNote, t0: number) => void;
+    /** シームレスループ用の1周の長さ（秒）。指定時は曲末に達したら音節インデックスを先頭に戻し内部オフセットへ加算する */
+    loopLengthSec?: number;
+    /** ループ再開位置（秒）。省略時は 0 */
+    loopStartSec?: number;
 };
 /**
  * 歌唱モデルをまとめて管理し、koeデモ式の「先読みストリーミング合成」で歌わせる高レベルヘルパ。
@@ -1010,59 +1014,12 @@ type PlayChordsOptions = PlayMmlOptions & {
 declare const playChords: (chordStr: string, options?: PlayChordsOptions) => MmlPlayback;
 
 /**
- * playSingingMML — 歌声付き（@@n 歌詞トラック）のヘッドレス MML 再生。【未実装スタブ】
+ * 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（歌声合成）。
+ * DOM を抜いたもの」。
  */
 
 type PlaySingingMmlOptions = PlayMmlOptions & {
@@ -1078,11 +1035,13 @@ type PlaySingingMmlOptions = PlayMmlOptions & {
     singingVoices?: SingingVoices;
 };
 /**
- * 歌声付き MML を画面なしで再生する。【未実装】
+ * 歌声付き MML を画面なしで再生する。
  *
- * @throws 現状は常に未実装エラーを投げる。実装方針は本ファイル冒頭の実装メモを参照。
+ * @param mml MML文字列
+ * @param options 再生オプション
+ * @returns MmlPlayback コントロールオブジェクトを含む Promise
  */
-declare const playSingingMML: (_mml: string, _options?: PlaySingingMmlOptions) => Promise<MmlPlayback>;
+declare const playSingingMML: (mml: string, options?: PlaySingingMmlOptions) => Promise<MmlPlayback>;
 
 /**
  * インラインSVGアイコン。外部アイコンフォント(MDI等)への依存を避けるため、
@@ -1667,6 +1626,7 @@ type Sequencer = {
      */
     getStartTime: () => number;
 };
+declare const resolveLoopPoint: (point: LoopPoint, _bpm: number, stepsPerBar: number, sps: number) => number;
 declare const createSequencer: (options: SequencerOptions) => Sequencer;
 
 type SoundFontInstance = {
@@ -1967,4 +1927,4 @@ declare const createSynth: (ctx: AudioContext, destination?: AudioNode, tone?: S
 
 declare const VOICE_IMAGES: Record<string, string>;
 
-export { type AddNoteOptions, type ApplyChordOptions, type ChordPatternType, type ChordPlacement, type ChordPlayerInstance, type ConsumedSyllable, type CoreEventHandlers, type CustomVocalDef, 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, GM_INSTRUMENT_NAMES, 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 LyricSyncData, type LyricTrack, type LyricsConductor, MAX_VOCAL_VOLUME, MMLCore, type MMLDisplayToken, type MMLNotePlacement, MML_END_MARKER, type MidiExtraction, type MidiNotePlacement, MidiSearchClient, type MidiSearchConfig, type MidiTrackAnalysis, type MmlMeta, type MmlPlayback, type MmlPlayerInstance, type MmlPlayerOptions, type ModeSwitchInstance, type ModeSwitchOptions, type MountChordPlayerOptions, 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 PicotuneSearchParams, type PicotuneSong, type PitchToken, type PlayChordsOptions, type PlayDrumEvent, type PlayMmlOptions, type PlayNoteEvent, type PlayNoteOptions, type PlayPlacementsOptions, 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, formatMmlMeta, freqFromPitch, generateRandomPattern, getDrawOffset, getGridCanvas, getGridContext, getGridPosition, getHeaderCanvas, getMidiBPM, getRenderConfig, getXY, icon, init, injectStyles, isChordHeavyTrack, isPlausibleMidiTranscription, isValidHttpUrl, koeUrl, mountChordPlayer, mountDAW, mountMmlPlayer, normalizeLyrics, onClick, panToStereo, parseCustomVocals, parseLyrics, parseMML, parseMmlMeta, playChords, playMML, playNote, playPlacements, playSingingMML, setBackgroundActive, setDrawOffset, shiftNotes, showLoadingOverlay, stripCustomVocals, stripLyrics, stripMmlMeta, vocalVolumeToGain };
+export { type AddNoteOptions, type ApplyChordOptions, type ChordPatternType, type ChordPlacement, type ChordPlayerInstance, type ConsumedSyllable, type CoreEventHandlers, type CustomVocalDef, 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, GM_INSTRUMENT_NAMES, 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 LyricSyncData, type LyricTrack, type LyricsConductor, MAX_VOCAL_VOLUME, MMLCore, type MMLDisplayToken, type MMLNotePlacement, MML_END_MARKER, type MidiExtraction, type MidiNotePlacement, MidiSearchClient, type MidiSearchConfig, type MidiTrackAnalysis, type MmlMeta, type MmlPlayback, type MmlPlayerInstance, type MmlPlayerOptions, type ModeSwitchInstance, type ModeSwitchOptions, type MountChordPlayerOptions, 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 PicotuneSearchParams, type PicotuneSong, type PitchToken, type PlayChordsOptions, type PlayDrumEvent, type PlayMmlOptions, type PlayNoteEvent, type PlayNoteOptions, type PlayPlacementsOptions, 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, formatMmlMeta, freqFromPitch, generateRandomPattern, getDrawOffset, getGridCanvas, getGridContext, getGridPosition, getHeaderCanvas, getMidiBPM, getRenderConfig, getXY, icon, init, injectStyles, isChordHeavyTrack, isPlausibleMidiTranscription, isValidHttpUrl, koeUrl, mountChordPlayer, mountDAW, mountMmlPlayer, normalizeLyrics, onClick, panToStereo, parseCustomVocals, parseLyrics, parseMML, parseMmlMeta, playChords, playMML, playNote, playPlacements, playSingingMML, resolveLoopPoint, setBackgroundActive, setDrawOffset, shiftNotes, showLoadingOverlay, stripCustomVocals, stripLyrics, stripMmlMeta, vocalVolumeToGain };

package/dist/index.d.ts

@@ -373,6 +373,10 @@ type StreamPlaybackOptions = {
      * t0 は発音予定の AudioContext 絶対時刻。
      */
     onScheduled?: (track: StreamVoiceTrack, note: StreamVoiceNote, t0: number) => void;
+    /** シームレスループ用の1周の長さ（秒）。指定時は曲末に達したら音節インデックスを先頭に戻し内部オフセットへ加算する */
+    loopLengthSec?: number;
+    /** ループ再開位置（秒）。省略時は 0 */
+    loopStartSec?: number;
 };
 /**
  * 歌唱モデルをまとめて管理し、koeデモ式の「先読みストリーミング合成」で歌わせる高レベルヘルパ。
@@ -1010,59 +1014,12 @@ type PlayChordsOptions = PlayMmlOptions & {
 declare const playChords: (chordStr: string, options?: PlayChordsOptions) => MmlPlayback;
 
 /**
- * playSingingMML — 歌声付き（@@n 歌詞トラック）のヘッドレス MML 再生。【未実装スタブ】
+ * 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（歌声合成）。
+ * DOM を抜いたもの」。
  */
 
 type PlaySingingMmlOptions = PlayMmlOptions & {
@@ -1078,11 +1035,13 @@ type PlaySingingMmlOptions = PlayMmlOptions & {
     singingVoices?: SingingVoices;
 };
 /**
- * 歌声付き MML を画面なしで再生する。【未実装】
+ * 歌声付き MML を画面なしで再生する。
  *
- * @throws 現状は常に未実装エラーを投げる。実装方針は本ファイル冒頭の実装メモを参照。
+ * @param mml MML文字列
+ * @param options 再生オプション
+ * @returns MmlPlayback コントロールオブジェクトを含む Promise
  */
-declare const playSingingMML: (_mml: string, _options?: PlaySingingMmlOptions) => Promise<MmlPlayback>;
+declare const playSingingMML: (mml: string, options?: PlaySingingMmlOptions) => Promise<MmlPlayback>;
 
 /**
  * インラインSVGアイコン。外部アイコンフォント(MDI等)への依存を避けるため、
@@ -1667,6 +1626,7 @@ type Sequencer = {
      */
     getStartTime: () => number;
 };
+declare const resolveLoopPoint: (point: LoopPoint, _bpm: number, stepsPerBar: number, sps: number) => number;
 declare const createSequencer: (options: SequencerOptions) => Sequencer;
 
 type SoundFontInstance = {
@@ -1967,4 +1927,4 @@ declare const createSynth: (ctx: AudioContext, destination?: AudioNode, tone?: S
 
 declare const VOICE_IMAGES: Record<string, string>;
 
-export { type AddNoteOptions, type ApplyChordOptions, type ChordPatternType, type ChordPlacement, type ChordPlayerInstance, type ConsumedSyllable, type CoreEventHandlers, type CustomVocalDef, 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, GM_INSTRUMENT_NAMES, 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 LyricSyncData, type LyricTrack, type LyricsConductor, MAX_VOCAL_VOLUME, MMLCore, type MMLDisplayToken, type MMLNotePlacement, MML_END_MARKER, type MidiExtraction, type MidiNotePlacement, MidiSearchClient, type MidiSearchConfig, type MidiTrackAnalysis, type MmlMeta, type MmlPlayback, type MmlPlayerInstance, type MmlPlayerOptions, type ModeSwitchInstance, type ModeSwitchOptions, type MountChordPlayerOptions, 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 PicotuneSearchParams, type PicotuneSong, type PitchToken, type PlayChordsOptions, type PlayDrumEvent, type PlayMmlOptions, type PlayNoteEvent, type PlayNoteOptions, type PlayPlacementsOptions, 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, formatMmlMeta, freqFromPitch, generateRandomPattern, getDrawOffset, getGridCanvas, getGridContext, getGridPosition, getHeaderCanvas, getMidiBPM, getRenderConfig, getXY, icon, init, injectStyles, isChordHeavyTrack, isPlausibleMidiTranscription, isValidHttpUrl, koeUrl, mountChordPlayer, mountDAW, mountMmlPlayer, normalizeLyrics, onClick, panToStereo, parseCustomVocals, parseLyrics, parseMML, parseMmlMeta, playChords, playMML, playNote, playPlacements, playSingingMML, setBackgroundActive, setDrawOffset, shiftNotes, showLoadingOverlay, stripCustomVocals, stripLyrics, stripMmlMeta, vocalVolumeToGain };
+export { type AddNoteOptions, type ApplyChordOptions, type ChordPatternType, type ChordPlacement, type ChordPlayerInstance, type ConsumedSyllable, type CoreEventHandlers, type CustomVocalDef, 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, GM_INSTRUMENT_NAMES, 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 LyricSyncData, type LyricTrack, type LyricsConductor, MAX_VOCAL_VOLUME, MMLCore, type MMLDisplayToken, type MMLNotePlacement, MML_END_MARKER, type MidiExtraction, type MidiNotePlacement, MidiSearchClient, type MidiSearchConfig, type MidiTrackAnalysis, type MmlMeta, type MmlPlayback, type MmlPlayerInstance, type MmlPlayerOptions, type ModeSwitchInstance, type ModeSwitchOptions, type MountChordPlayerOptions, 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 PicotuneSearchParams, type PicotuneSong, type PitchToken, type PlayChordsOptions, type PlayDrumEvent, type PlayMmlOptions, type PlayNoteEvent, type PlayNoteOptions, type PlayPlacementsOptions, 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, formatMmlMeta, freqFromPitch, generateRandomPattern, getDrawOffset, getGridCanvas, getGridContext, getGridPosition, getHeaderCanvas, getMidiBPM, getRenderConfig, getXY, icon, init, injectStyles, isChordHeavyTrack, isPlausibleMidiTranscription, isValidHttpUrl, koeUrl, mountChordPlayer, mountDAW, mountMmlPlayer, normalizeLyrics, onClick, panToStereo, parseCustomVocals, parseLyrics, parseMML, parseMmlMeta, playChords, playMML, playNote, playPlacements, playSingingMML, resolveLoopPoint, setBackgroundActive, setDrawOffset, shiftNotes, showLoadingOverlay, stripCustomVocals, stripLyrics, stripMmlMeta, vocalVolumeToGain };

package/dist/index.js

@@ -109,6 +109,7 @@ __export(index_exports, {
   playNote: () => playNote,
   playPlacements: () => playPlacements,
   playSingingMML: () => playSingingMML,
+  resolveLoopPoint: () => resolveLoopPoint,
   setBackgroundActive: () => setBackgroundActive,
   setDrawOffset: () => setDrawOffset,
   shiftNotes: () => shiftNotes,
@@ -2775,54 +2776,73 @@ var createSingingVoices = (ctx, destination, options = {}) => {
       forEachSungNote(track, (note, prevVowel) => {
         items.push({ note, prevVowel });
       });
+      if (items.length === 0) return;
       const peak = Math.max(1e-4, track.volume);
-      for (const { note, prevVowel } of items) {
-        if (session !== streamSession) return;
-        while (note.startSec - (ctx.currentTime - anchorTime) > STREAM_LOOKAHEAD_SEC) {
-          await new Promise((resolve) => setTimeout(resolve, STREAM_POLL_MS));
+      const loopStartSec = opts?.loopStartSec ?? 0;
+      let loopOffsetSec = 0;
+      let pass = 0;
+      do {
+        for (const { note, prevVowel } of items) {
           if (session !== streamSession) return;
-        }
-        if (opts?.isAudible && !opts.isAudible(track)) continue;
-        const t0 = anchorTime + note.startSec;
-        if (model.renderToCache && model.scheduleCached) {
-          const renderToCache = model.renderToCache;
-          const scheduleCached = model.scheduleCached;
-          void (async () => {
-            const key = await renderToCache(
-              note.syllable,
-              prevVowel,
-              note.pitch,
-              note.durationSec * 1e3
-            );
+          if (pass > 0 && note.startSec < loopStartSec - 1e-4) {
+            continue;
+          }
+          if (opts?.loopLengthSec && opts.loopLengthSec > 0 && note.startSec >= loopStartSec + opts.loopLengthSec - 1e-4) {
+            continue;
+          }
+          const startSec = note.startSec + loopOffsetSec;
+          while (startSec - (ctx.currentTime - anchorTime) > STREAM_LOOKAHEAD_SEC) {
+            await new Promise((resolve) => setTimeout(resolve, STREAM_POLL_MS));
             if (session !== streamSession) return;
-            if (key) {
-              const delay = ctx.currentTime - t0;
-              if (delay < 0.05) {
-                scheduleCached(key, t0, peak, track.pan);
-                opts?.onScheduled?.(track, note, t0);
-              } else {
-                console.warn(
-                  `[dtm] Synthesizer late skip: ${note.syllable.kana} at ${note.startSec}s (delayed by ${delay.toFixed(3)}s)`
-                );
-                opts?.onLateSkip?.(note, delay);
+          }
+          if (opts?.isAudible && !opts.isAudible(track)) continue;
+          const t0 = anchorTime + startSec;
+          if (model.renderToCache && model.scheduleCached) {
+            const renderToCache = model.renderToCache;
+            const scheduleCached = model.scheduleCached;
+            void (async () => {
+              const key = await renderToCache(
+                note.syllable,
+                prevVowel,
+                note.pitch,
+                note.durationSec * 1e3
+              );
+              if (session !== streamSession) return;
+              if (key) {
+                const delay = ctx.currentTime - t0;
+                if (delay < 0.05) {
+                  scheduleCached(key, t0, peak, track.pan);
+                  opts?.onScheduled?.(track, note, t0);
+                } else {
+                  console.warn(
+                    `[dtm] Synthesizer late skip: ${note.syllable.kana} at ${startSec}s (delayed by ${delay.toFixed(3)}s)`
+                  );
+                  opts?.onLateSkip?.(note, delay);
+                }
               }
-            }
-          })();
+            })();
+          } else {
+            const when = t0 - ctx.currentTime;
+            model(note.syllable, {
+              trackId: "",
+              pitch: note.pitch,
+              velocity: 100,
+              volume: peak,
+              when,
+              duration: note.durationSec,
+              pan: track.pan
+            });
+            opts?.onScheduled?.(track, note, t0);
+            await new Promise((resolve) => setTimeout(resolve, 0));
+          }
+        }
+        if (opts?.loopLengthSec && opts.loopLengthSec > 0) {
+          loopOffsetSec += opts.loopLengthSec;
+          pass++;
         } else {
-          const when = t0 - ctx.currentTime;
-          model(note.syllable, {
-            trackId: "",
-            pitch: note.pitch,
-            velocity: 100,
-            volume: peak,
-            when,
-            duration: note.durationSec,
-            pan: track.pan
-          });
-          opts?.onScheduled?.(track, note, t0);
-          await new Promise((resolve) => setTimeout(resolve, 0));
+          break;
         }
-      }
+      } while (session === streamSession);
     };
     for (const track of tracks) void runTrack(track);
   };
@@ -13128,12 +13148,234 @@ var mountDAW = (target, options = {}) => {
 };
 
 // src/headless-singing-player.ts
-var playSingingMML = (_mml, _options = {}) => {
-  return Promise.reject(
-    new Error(
-      "playSingingMML is not implemented yet. See implementation notes at the top of headless-singing-player.ts."
-    )
+var STEPS_PER_BEAT4 = 48;
+var STEPS_PER_BAR3 = 192;
+var playSingingMML = async (mml, options = {}) => {
+  const {
+    placements,
+    bpm: parsedBpm,
+    meta,
+    lyrics
+  } = parseMML(mml, {
+    collectLyrics: true
+  });
+  const lyricTracks = lyrics ?? /* @__PURE__ */ new Map();
+  const customVocalByKey = new Map(
+    parseCustomVocals(mml).map((d) => [d.key, d])
   );
+  const bpm = parsedBpm ?? options.defaultBpm ?? DEFAULT_BPM;
+  const secondsPerStep = 60 / bpm / STEPS_PER_BEAT4;
+  const drumPatternDict = options.drumPatterns ?? DRUM_PATTERNS;
+  const drumPattern = meta.drum ? drumPatternDict[meta.drum] ?? null : null;
+  const drumVolume = meta.drumVolume ?? 80;
+  const trackVolume = meta.volume ?? 100;
+  let masterVolume = options.volume ?? 100;
+  const trackIndices = [...new Set(placements.map((p) => p.trackIndex))].sort(
+    (a, b) => a - b
+  );
+  const seqTracks = trackIndices.map((index) => {
+    let id = 0;
+    const notes = placements.filter((p) => p.trackIndex === index).map((p) => ({
+      id: id++,
+      startStep: p.startStep,
+      durationSteps: p.durationSteps,
+      pitch: p.pitch,
+      velocity: p.velocity
+    }));
+    return {
+      id: String(index),
+      volume: trackVolume / 100 * masterVolume,
+      notes
+    };
+  });
+  const ownsCtx = !options.audioContext;
+  const ctx = options.audioContext ?? new AudioContext();
+  const destination = options.destination ?? ctx.destination;
+  const useSynth = options.synth ?? !options.onPlayNote;
+  const synth = useSynth ? createSynth(ctx, destination) : null;
+  const pauseWhenHidden = options.pauseWhenHidden ?? ownsCtx;
+  let playing = false;
+  let destroyed = false;
+  let voices = options.singingVoices ?? null;
+  const buildStreamTracks = (fromStep) => [...lyricTracks.entries()].map(([index, lt]) => {
+    const seqTrack = seqTracks.find((t) => Number(t.id) === index);
+    const sorted = [...seqTrack?.notes ?? []].sort(
+      (a, b) => a.startStep - b.startStep
+    );
+    const gate = (lt.gate ?? DEFAULT_GATE) / 100;
+    const semis = (lt.octave ?? 0) * 12;
+    const count = Math.min(sorted.length, lt.syllables.length);
+    const notes = [];
+    for (let i = 0; i < count; i++) {
+      const n = sorted[i];
+      if (n.startStep < fromStep) continue;
+      notes.push({
+        syllable: lt.syllables[i],
+        pitch: n.pitch + semis,
+        startSec: (n.startStep - fromStep) * secondsPerStep,
+        durationSec: n.durationSteps * secondsPerStep * gate
+      });
+    }
+    return {
+      id: String(index),
+      model: lt.model,
+      volume: vocalVolumeToGain(lt.volume ?? DEFAULT_VOCAL_VOLUME),
+      pan: panToStereo(lt.pan ?? DEFAULT_PAN),
+      notes
+    };
+  });
+  const seq = createSequencer({
+    getTracks: () => seqTracks,
+    getBpm: () => bpm,
+    getPlayStartStep: () => 0,
+    getDrumPattern: () => drumPattern,
+    getSoloTrackId: () => null,
+    getLoop: () => options.loop ?? false,
+    cues: options.cues,
+    onCue: options.onCue,
+    getAudioTime: () => ctx.currentTime,
+    onPlayNote: (e) => {
+      const trackIdx = Number(e.trackId);
+      if (lyricTracks.has(trackIdx)) return;
+      options.onPlayNote?.(e);
+      synth?.playNote(e);
+    },
+    onPlayDrum: (e) => {
+      const velocity = e.velocity * (drumVolume / 100) * (trackVolume / 100) * (masterVolume / 100);
+      options.onPlayDrum?.({ ...e, velocity });
+      synth?.playDrum({ ...e, velocity });
+    },
+    onTick: (step) => {
+      options.onTick?.(step);
+    },
+    onEnd: (_interrupted) => finish(),
+    stepsPerBar: STEPS_PER_BAR3
+  });
+  const finish = () => {
+    if (!playing) return;
+    playing = false;
+    voices?.stopStream();
+    options.onStop?.();
+  };
+  const onVisibilityChange = () => {
+    if (!playing) return;
+    if (document.hidden) {
+      void ctx.suspend();
+    } else if (ctx.state === "suspended") {
+      void ctx.resume();
+    }
+  };
+  if (pauseWhenHidden && typeof document !== "undefined") {
+    document.addEventListener("visibilitychange", onVisibilityChange);
+  }
+  const stop = () => {
+    if (!playing) return;
+    seq.stop();
+    finish();
+  };
+  const setVolume = (volume) => {
+    masterVolume = volume;
+    const effectiveTrackVolume = trackVolume / 100 * masterVolume;
+    for (const t of seqTracks) t.volume = effectiveTrackVolume;
+    voices?.setVolume(trackVolume / 100 * (masterVolume / 100));
+  };
+  const suspend = () => ctx.suspend();
+  const resume = () => ctx.resume();
+  const destroy = () => {
+    seq.stop();
+    playing = false;
+    destroyed = true;
+    voices?.reset();
+    if (pauseWhenHidden && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    }
+    if (ownsCtx && ctx.state !== "closed") {
+      void ctx.close();
+    }
+  };
+  const playback = {
+    stop,
+    isPlaying: () => playing,
+    setVolume,
+    suspend,
+    resume,
+    destroy
+  };
+  playing = true;
+  try {
+    const resumes = [];
+    const r = options.onResumeAudio?.();
+    if (r) resumes.push(Promise.resolve(r));
+    if (ctx.state === "suspended") resumes.push(ctx.resume());
+    if (resumes.length > 0) await Promise.all(resumes);
+    if (!playing || destroyed) {
+      return playback;
+    }
+    if (lyricTracks.size > 0) {
+      if (!voices) {
+        voices = createSingingVoices(ctx, destination, {
+          voiceWorkerUrl: options.voiceWorkerUrl
+        });
+      }
+      if (customVocalByKey.size > 0 && voices.registerVoicebanks) {
+        voices.registerVoicebanks(
+          Object.fromEntries([...customVocalByKey].map(([k, d]) => [k, d.url]))
+        );
+      }
+      const streamTracks = buildStreamTracks(0);
+      await voices.loadModels(streamTracks.map((t) => t.model));
+      if (!playing || destroyed) {
+        return playback;
+      }
+      await voices.warm(streamTracks, PREWARM_NOTES);
+      if (!playing || destroyed) {
+        return playback;
+      }
+      let loopLengthSec;
+      let loopStartSec;
+      const loopOption = options.loop ?? false;
+      if (loopOption) {
+        let loopStartStep = 0;
+        let loopEndStep = -1;
+        if (typeof loopOption === "object") {
+          loopStartStep = loopOption.start ? resolveLoopPoint(
+            loopOption.start,
+            bpm,
+            STEPS_PER_BAR3,
+            secondsPerStep
+          ) : 0;
+          const endVal = loopOption.end ? resolveLoopPoint(
+            loopOption.end,
+            bpm,
+            STEPS_PER_BAR3,
+            secondsPerStep
+          ) : null;
+          loopEndStep = endVal !== null ? endVal : -1;
+        }
+        if (loopEndStep === -1) {
+          let maxEndStep = 0;
+          for (const p of placements) {
+            maxEndStep = Math.max(maxEndStep, p.startStep + p.durationSteps);
+          }
+          loopEndStep = maxEndStep;
+        }
+        loopStartSec = loopStartStep * secondsPerStep;
+        loopLengthSec = (loopEndStep - loopStartStep) * secondsPerStep;
+      }
+      seq.start(0);
+      voices.setVolume(trackVolume / 100 * (masterVolume / 100));
+      voices.startStream(streamTracks, seq.getStartTime(), {
+        loopLengthSec,
+        loopStartSec
+      });
+    } else {
+      seq.start(0);
+    }
+  } catch (err2) {
+    stop();
+    throw err2;
+  }
+  return playback;
 };
 
 // src/piano-roll.ts
@@ -14493,6 +14735,7 @@ var createDtmStudio = async (options = {}) => {
   playNote,
   playPlacements,
   playSingingMML,
+  resolveLoopPoint,
   setBackgroundActive,
   setDrawOffset,
   shiftNotes,

package/dist/index.mjs

@@ -2653,54 +2653,73 @@ var createSingingVoices = (ctx, destination, options = {}) => {
       forEachSungNote(track, (note, prevVowel) => {
         items.push({ note, prevVowel });
       });
+      if (items.length === 0) return;
       const peak = Math.max(1e-4, track.volume);
-      for (const { note, prevVowel } of items) {
-        if (session !== streamSession) return;
-        while (note.startSec - (ctx.currentTime - anchorTime) > STREAM_LOOKAHEAD_SEC) {
-          await new Promise((resolve) => setTimeout(resolve, STREAM_POLL_MS));
+      const loopStartSec = opts?.loopStartSec ?? 0;
+      let loopOffsetSec = 0;
+      let pass = 0;
+      do {
+        for (const { note, prevVowel } of items) {
           if (session !== streamSession) return;
-        }
-        if (opts?.isAudible && !opts.isAudible(track)) continue;
-        const t0 = anchorTime + note.startSec;
-        if (model.renderToCache && model.scheduleCached) {
-          const renderToCache = model.renderToCache;
-          const scheduleCached = model.scheduleCached;
-          void (async () => {
-            const key = await renderToCache(
-              note.syllable,
-              prevVowel,
-              note.pitch,
-              note.durationSec * 1e3
-            );
+          if (pass > 0 && note.startSec < loopStartSec - 1e-4) {
+            continue;
+          }
+          if (opts?.loopLengthSec && opts.loopLengthSec > 0 && note.startSec >= loopStartSec + opts.loopLengthSec - 1e-4) {
+            continue;
+          }
+          const startSec = note.startSec + loopOffsetSec;
+          while (startSec - (ctx.currentTime - anchorTime) > STREAM_LOOKAHEAD_SEC) {
+            await new Promise((resolve) => setTimeout(resolve, STREAM_POLL_MS));
             if (session !== streamSession) return;
-            if (key) {
-              const delay = ctx.currentTime - t0;
-              if (delay < 0.05) {
-                scheduleCached(key, t0, peak, track.pan);
-                opts?.onScheduled?.(track, note, t0);
-              } else {
-                console.warn(
-                  `[dtm] Synthesizer late skip: ${note.syllable.kana} at ${note.startSec}s (delayed by ${delay.toFixed(3)}s)`
-                );
-                opts?.onLateSkip?.(note, delay);
+          }
+          if (opts?.isAudible && !opts.isAudible(track)) continue;
+          const t0 = anchorTime + startSec;
+          if (model.renderToCache && model.scheduleCached) {
+            const renderToCache = model.renderToCache;
+            const scheduleCached = model.scheduleCached;
+            void (async () => {
+              const key = await renderToCache(
+                note.syllable,
+                prevVowel,
+                note.pitch,
+                note.durationSec * 1e3
+              );
+              if (session !== streamSession) return;
+              if (key) {
+                const delay = ctx.currentTime - t0;
+                if (delay < 0.05) {
+                  scheduleCached(key, t0, peak, track.pan);
+                  opts?.onScheduled?.(track, note, t0);
+                } else {
+                  console.warn(
+                    `[dtm] Synthesizer late skip: ${note.syllable.kana} at ${startSec}s (delayed by ${delay.toFixed(3)}s)`
+                  );
+                  opts?.onLateSkip?.(note, delay);
+                }
               }
-            }
-          })();
+            })();
+          } else {
+            const when = t0 - ctx.currentTime;
+            model(note.syllable, {
+              trackId: "",
+              pitch: note.pitch,
+              velocity: 100,
+              volume: peak,
+              when,
+              duration: note.durationSec,
+              pan: track.pan
+            });
+            opts?.onScheduled?.(track, note, t0);
+            await new Promise((resolve) => setTimeout(resolve, 0));
+          }
+        }
+        if (opts?.loopLengthSec && opts.loopLengthSec > 0) {
+          loopOffsetSec += opts.loopLengthSec;
+          pass++;
         } else {
-          const when = t0 - ctx.currentTime;
-          model(note.syllable, {
-            trackId: "",
-            pitch: note.pitch,
-            velocity: 100,
-            volume: peak,
-            when,
-            duration: note.durationSec,
-            pan: track.pan
-          });
-          opts?.onScheduled?.(track, note, t0);
-          await new Promise((resolve) => setTimeout(resolve, 0));
+          break;
         }
-      }
+      } while (session === streamSession);
     };
     for (const track of tracks) void runTrack(track);
   };
@@ -13006,12 +13025,234 @@ var mountDAW = (target, options = {}) => {
 };
 
 // src/headless-singing-player.ts
-var playSingingMML = (_mml, _options = {}) => {
-  return Promise.reject(
-    new Error(
-      "playSingingMML is not implemented yet. See implementation notes at the top of headless-singing-player.ts."
-    )
+var STEPS_PER_BEAT4 = 48;
+var STEPS_PER_BAR3 = 192;
+var playSingingMML = async (mml, options = {}) => {
+  const {
+    placements,
+    bpm: parsedBpm,
+    meta,
+    lyrics
+  } = parseMML(mml, {
+    collectLyrics: true
+  });
+  const lyricTracks = lyrics ?? /* @__PURE__ */ new Map();
+  const customVocalByKey = new Map(
+    parseCustomVocals(mml).map((d) => [d.key, d])
   );
+  const bpm = parsedBpm ?? options.defaultBpm ?? DEFAULT_BPM;
+  const secondsPerStep = 60 / bpm / STEPS_PER_BEAT4;
+  const drumPatternDict = options.drumPatterns ?? DRUM_PATTERNS;
+  const drumPattern = meta.drum ? drumPatternDict[meta.drum] ?? null : null;
+  const drumVolume = meta.drumVolume ?? 80;
+  const trackVolume = meta.volume ?? 100;
+  let masterVolume = options.volume ?? 100;
+  const trackIndices = [...new Set(placements.map((p) => p.trackIndex))].sort(
+    (a, b) => a - b
+  );
+  const seqTracks = trackIndices.map((index) => {
+    let id = 0;
+    const notes = placements.filter((p) => p.trackIndex === index).map((p) => ({
+      id: id++,
+      startStep: p.startStep,
+      durationSteps: p.durationSteps,
+      pitch: p.pitch,
+      velocity: p.velocity
+    }));
+    return {
+      id: String(index),
+      volume: trackVolume / 100 * masterVolume,
+      notes
+    };
+  });
+  const ownsCtx = !options.audioContext;
+  const ctx = options.audioContext ?? new AudioContext();
+  const destination = options.destination ?? ctx.destination;
+  const useSynth = options.synth ?? !options.onPlayNote;
+  const synth = useSynth ? createSynth(ctx, destination) : null;
+  const pauseWhenHidden = options.pauseWhenHidden ?? ownsCtx;
+  let playing = false;
+  let destroyed = false;
+  let voices = options.singingVoices ?? null;
+  const buildStreamTracks = (fromStep) => [...lyricTracks.entries()].map(([index, lt]) => {
+    const seqTrack = seqTracks.find((t) => Number(t.id) === index);
+    const sorted = [...seqTrack?.notes ?? []].sort(
+      (a, b) => a.startStep - b.startStep
+    );
+    const gate = (lt.gate ?? DEFAULT_GATE) / 100;
+    const semis = (lt.octave ?? 0) * 12;
+    const count = Math.min(sorted.length, lt.syllables.length);
+    const notes = [];
+    for (let i = 0; i < count; i++) {
+      const n = sorted[i];
+      if (n.startStep < fromStep) continue;
+      notes.push({
+        syllable: lt.syllables[i],
+        pitch: n.pitch + semis,
+        startSec: (n.startStep - fromStep) * secondsPerStep,
+        durationSec: n.durationSteps * secondsPerStep * gate
+      });
+    }
+    return {
+      id: String(index),
+      model: lt.model,
+      volume: vocalVolumeToGain(lt.volume ?? DEFAULT_VOCAL_VOLUME),
+      pan: panToStereo(lt.pan ?? DEFAULT_PAN),
+      notes
+    };
+  });
+  const seq = createSequencer({
+    getTracks: () => seqTracks,
+    getBpm: () => bpm,
+    getPlayStartStep: () => 0,
+    getDrumPattern: () => drumPattern,
+    getSoloTrackId: () => null,
+    getLoop: () => options.loop ?? false,
+    cues: options.cues,
+    onCue: options.onCue,
+    getAudioTime: () => ctx.currentTime,
+    onPlayNote: (e) => {
+      const trackIdx = Number(e.trackId);
+      if (lyricTracks.has(trackIdx)) return;
+      options.onPlayNote?.(e);
+      synth?.playNote(e);
+    },
+    onPlayDrum: (e) => {
+      const velocity = e.velocity * (drumVolume / 100) * (trackVolume / 100) * (masterVolume / 100);
+      options.onPlayDrum?.({ ...e, velocity });
+      synth?.playDrum({ ...e, velocity });
+    },
+    onTick: (step) => {
+      options.onTick?.(step);
+    },
+    onEnd: (_interrupted) => finish(),
+    stepsPerBar: STEPS_PER_BAR3
+  });
+  const finish = () => {
+    if (!playing) return;
+    playing = false;
+    voices?.stopStream();
+    options.onStop?.();
+  };
+  const onVisibilityChange = () => {
+    if (!playing) return;
+    if (document.hidden) {
+      void ctx.suspend();
+    } else if (ctx.state === "suspended") {
+      void ctx.resume();
+    }
+  };
+  if (pauseWhenHidden && typeof document !== "undefined") {
+    document.addEventListener("visibilitychange", onVisibilityChange);
+  }
+  const stop = () => {
+    if (!playing) return;
+    seq.stop();
+    finish();
+  };
+  const setVolume = (volume) => {
+    masterVolume = volume;
+    const effectiveTrackVolume = trackVolume / 100 * masterVolume;
+    for (const t of seqTracks) t.volume = effectiveTrackVolume;
+    voices?.setVolume(trackVolume / 100 * (masterVolume / 100));
+  };
+  const suspend = () => ctx.suspend();
+  const resume = () => ctx.resume();
+  const destroy = () => {
+    seq.stop();
+    playing = false;
+    destroyed = true;
+    voices?.reset();
+    if (pauseWhenHidden && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    }
+    if (ownsCtx && ctx.state !== "closed") {
+      void ctx.close();
+    }
+  };
+  const playback = {
+    stop,
+    isPlaying: () => playing,
+    setVolume,
+    suspend,
+    resume,
+    destroy
+  };
+  playing = true;
+  try {
+    const resumes = [];
+    const r = options.onResumeAudio?.();
+    if (r) resumes.push(Promise.resolve(r));
+    if (ctx.state === "suspended") resumes.push(ctx.resume());
+    if (resumes.length > 0) await Promise.all(resumes);
+    if (!playing || destroyed) {
+      return playback;
+    }
+    if (lyricTracks.size > 0) {
+      if (!voices) {
+        voices = createSingingVoices(ctx, destination, {
+          voiceWorkerUrl: options.voiceWorkerUrl
+        });
+      }
+      if (customVocalByKey.size > 0 && voices.registerVoicebanks) {
+        voices.registerVoicebanks(
+          Object.fromEntries([...customVocalByKey].map(([k, d]) => [k, d.url]))
+        );
+      }
+      const streamTracks = buildStreamTracks(0);
+      await voices.loadModels(streamTracks.map((t) => t.model));
+      if (!playing || destroyed) {
+        return playback;
+      }
+      await voices.warm(streamTracks, PREWARM_NOTES);
+      if (!playing || destroyed) {
+        return playback;
+      }
+      let loopLengthSec;
+      let loopStartSec;
+      const loopOption = options.loop ?? false;
+      if (loopOption) {
+        let loopStartStep = 0;
+        let loopEndStep = -1;
+        if (typeof loopOption === "object") {
+          loopStartStep = loopOption.start ? resolveLoopPoint(
+            loopOption.start,
+            bpm,
+            STEPS_PER_BAR3,
+            secondsPerStep
+          ) : 0;
+          const endVal = loopOption.end ? resolveLoopPoint(
+            loopOption.end,
+            bpm,
+            STEPS_PER_BAR3,
+            secondsPerStep
+          ) : null;
+          loopEndStep = endVal !== null ? endVal : -1;
+        }
+        if (loopEndStep === -1) {
+          let maxEndStep = 0;
+          for (const p of placements) {
+            maxEndStep = Math.max(maxEndStep, p.startStep + p.durationSteps);
+          }
+          loopEndStep = maxEndStep;
+        }
+        loopStartSec = loopStartStep * secondsPerStep;
+        loopLengthSec = (loopEndStep - loopStartStep) * secondsPerStep;
+      }
+      seq.start(0);
+      voices.setVolume(trackVolume / 100 * (masterVolume / 100));
+      voices.startStream(streamTracks, seq.getStartTime(), {
+        loopLengthSec,
+        loopStartSec
+      });
+    } else {
+      seq.start(0);
+    }
+  } catch (err2) {
+    stop();
+    throw err2;
+  }
+  return playback;
 };
 
 // src/piano-roll.ts
@@ -14369,6 +14610,7 @@ export {
   playNote,
   playPlacements,
   playSingingMML,
+  resolveLoopPoint,
   setBackgroundActive,
   setDrawOffset,
   shiftNotes,

package/package.json

@@ -2,7 +2,7 @@
   "author": "onjmin",
   "license": "MIT",
   "name": "@onjmin/dtm",
-  "version": "0.1.67",
+  "version": "0.1.68",
   "description": "MMLを中間言語に用いた、モバイルファーストなDAW / ピアノロール打ち込みコンポーネント",
   "homepage": "https://onjmin.github.io/dtm",
   "repository": {