@onjmin/dtm 1.0.8 → 2.0.3

package/dist/index.d.ts

@@ -57,6 +57,151 @@ type ChordPlayerInstance = {
  */
 declare const mountChordPlayer: (target: HTMLElement, chords: string, options?: MountChordPlayerOptions) => ChordPlayerInstance;
 
+/**
+ * 音律（12平均律 / 31平均律）と、ピッチの内部表現。
+ *
+ * ## 単位
+ *
+ * ノートのピッチは **1/372オクターブの整数** で持つ。372 = 12 × 31 で、12と31は
+ * 互いに素なので最小公倍数がこれになり、**12平均律と31平均律の両方が誤差ゼロで
+ * 同じ数直線に乗る**。
+ *
+ *   12平均律 1半音 = 31 units
+ *   31平均律 1度   = 12 units
+ *   1 unit = 1200/372 ≒ 3.2258 セント
+ *
+ * 整数のままなので `a.pitchUnits === b.pitchUnits` の同値判定が全部生き残る
+ * （重複判定・当たり判定・協調編集の (startStep, pitchUnits) キー）。小数にすると
+ * ここが軒並み壊れるため、細かい整数単位を選んでいる。
+ *
+ * ## 音律は音声経路に入らない
+ *
+ * ピッチが絶対値なので、シーケンサも発音器も音律を知らなくてよい。音律は
+ * 「格子・記譜・表示」だけに効く編集上の概念で、`RenderConfig.edo` に置く。
+ */
+/**
+ * ピッチの単位を型で区別するためのブランド。
+ *
+ * `Units` と `MidiNote` はどちらも実体は number だが、互いに代入できない。
+ * これは「半音の数値を units のつもりで使う」「units を SoundFont の
+ * MIDIノート番号として渡す」といった取り違えを**コンパイラに検出させる**ため。
+ * 単位の取り違えは型が同じ number である限り一切検出できず、実際に
+ * 「楽器音が無音」「オクターブユニゾンが0.4半音ずれる」「多音階音源のサンプル
+ * 選択が常に最高音になる」といった不具合を作り込んだ。
+ *
+ * 生の number から作るときは {@link units} / {@link midiNote} を通す。
+ * 変換は {@link midiToUnits} / {@link unitsToMidi} など、この module の関数に集約する。
+ */
+declare const UNITS_BRAND: unique symbol;
+declare const MIDI_BRAND: unique symbol;
+/** ピッチ。1/372オクターブの整数。 */
+type Units = number & {
+    readonly [UNITS_BRAND]: true;
+};
+/** MIDIノート番号（半音）。0-127。SoundFont のゾーン選択やMIDI入出力で使う。 */
+type MidiNote = number & {
+    readonly [MIDI_BRAND]: true;
+};
+/** 生の数値を units として扱う。単位が units であると確信できる箇所だけで使う。 */
+declare const units: (n: number) => Units;
+/** 生の数値をMIDIノート番号として扱う。MIDI入出力の境界だけで使う。 */
+declare const midiNote: (n: number) => MidiNote;
+/** units 同士・units と生の差分の加算。結果も units。 */
+declare const addUnits: (a: Units, delta: number) => Units;
+/** 1オクターブあたりの units。12 × 31。 */
+declare const UNITS_PER_OCTAVE = 372;
+/** 12平均律の1半音あたりの units。 */
+declare const UNITS_PER_SEMITONE: number;
+/** 31平均律の1度あたりの units。 */
+declare const UNITS_PER_EDO31_DEGREE: number;
+/** 1 unit のセント値。 */
+declare const CENTS_PER_UNIT: number;
+/** A4 (MIDI 69) の units。周波数計算の基準。 */
+declare const A4_UNITS: Units;
+/** A4 の周波数(Hz)。 */
+declare const A4_HZ = 440;
+/** 対応する音律（1オクターブの分割数）。 */
+type Edo = 12 | 31;
+/** 既定の音律。宣言のない曲はすべてこれ（＝既存データは素通り）。 */
+declare const DEFAULT_EDO: Edo;
+/** その音律の1格子ステップが何 units か。 */
+declare const unitsPerStep: (edo: Edo) => number;
+/** MIDIノート番号 → units。 */
+declare const midiToUnits: (midi: MidiNote | number) => Units;
+/**
+ * units → MIDIノート番号（小数）。
+ * 歌声合成（koe）は Hz を受けるためこの小数値をそのまま渡してよい。
+ * SoundFont のように整数ゾーンしか持たない発音器は {@link unitsToMidiDetune} を使う。
+ */
+declare const unitsToMidi: (u: Units) => number;
+/** units → 周波数(Hz)。 */
+declare const unitsToHz: (u: Units) => number;
+/**
+ * units → 「最寄りの整数MIDIノート番号 + セント補正」。
+ *
+ * SoundFont は音高ごとに整数キーでゾーンを持つため小数ピッチを直接鳴らせない。
+ * 最寄りのゾーンを鳴らして残差を `AudioBufferSourceNode.detune` で補正する。
+ * 31平均律での残差は最大 ±48.4 セントで、detune の可動域に十分収まる。
+ */
+declare const unitsToMidiDetune: (u: Units) => {
+    midi: MidiNote;
+    detuneCents: number;
+};
+/**
+ * 臨時記号1つあたりの格子ステップ数。
+ *
+ * - `#` / `+`(12平均律) … クロマチック半音上げ
+ * - `-` … クロマチック半音下げ
+ * - `+`(31平均律) … 格子1ステップ上げ（微分音）
+ * - `_` … 格子1ステップ下げ（微分音）
+ *
+ * 12平均律ではクロマチック半音＝1格子ステップなので4記号すべてが従来の意味に潰れ、
+ * 既存MMLの解釈は1文字も変わらない。31平均律でのみ `#`/`-`（±2度）と
+ * `+`/`_`（±1度）が分岐する。
+ */
+declare const chromaticStep: (edo: Edo) => number;
+/** 微分音記号 `+` / `_` 1つあたりの格子ステップ数。常に1。 */
+declare const MICRO_STEP = 1;
+/** 幹音の文字か。 */
+declare const isNaturalLetter: (ch: string) => boolean;
+/** 幹音の文字 → オクターブ内の格子ステップ。未知の文字は null。 */
+declare const naturalStep: (ch: string, edo: Edo) => number | null;
+/**
+ * 音名・オクターブ・臨時記号から units を組み立てる。
+ *
+ * `octave` はMMLの `o` 指定（MIDI慣習で o4 の c が中央ド = MIDI 60）。
+ * 臨時記号でオクターブを跨ぐ綴り（`b##` が次オクターブへ、`c--` が前オクターブへ）も
+ * そのまま加算されるので、度数を 0〜edo-1 にクランプしてはいけない。
+ */
+declare const spellingToUnits: (letter: string, octave: number, chromatic: number, micro: number, edo: Edo) => number | null;
+/**
+ * 五度圏インデックス（C=0, G=1, F=-1, C#=7, Db=-5）→ オクターブ内の格子ステップ。
+ *
+ * ミーントーン系の音律はすべて「五度を何ステップとするか」だけで決まるため、
+ * 綴りを持つ音（chord-parser の `rootFifth` / `noteFifths` など）はこの一本で
+ * どちらの音律へも正確に写せる。12平均律では C# と Db が同じ値に潰れ、
+ * 31平均律では 2 と 3 に分かれる。
+ */
+declare const fifthToStep: (fifthIndex: number, edo: Edo) => number;
+/** 五度圏インデックス → オクターブ内の units。 */
+declare const fifthToUnits: (fifthIndex: number, edo: Edo) => number;
+/**
+ * ピッチ表現のバージョン。
+ *
+ * - v1 … `pitch` が半音（MIDIノート番号）。dtm 1.x
+ * - v2 … `pitchUnits` が 1/372オクターブ単位。dtm 2.x
+ *
+ * dtm 自身は通信路を持たず `onNotesPatch` / `applyPatch` のフックを出すだけなので、
+ * バージョンの突き合わせは利用側アプリのハンドシェイクの責務になる。変換の知識だけを
+ * ここに置く。v1→v2 は無損失だが、**v2→v1 は12平均律の曲でしか成立しない**
+ * （31平均律を半音へ丸めると最大48.4セント動く）。
+ */
+declare const PITCH_ENCODING_VERSION = 2;
+/** v1（半音）→ v2（units）。無損失。 */
+declare const pitchV1ToUnits: (pitch: number) => Units;
+/** v2（units）→ v1（半音）。12平均律の曲でのみ無損失。 */
+declare const unitsToPitchV1: (u: Units) => number;
+
 /**
  * コード進行文字列を伴奏トラックのノート配置へ展開する。
  *
@@ -64,24 +209,28 @@ declare const mountChordPlayer: (target: HTMLElement, chords: string, options?:
  * 旧 demo/index.html の applyChordProgression を移植・整理し、
  * 実際のノート追加を行わず配置（placement）の配列を返す純関数にした。
  */
+
 type ChordPatternType = "block" | "arpeggio" | "arpeggio-fast" | "offbeat" | "yatsume" | "alternating";
 type ChordPlacement = {
     startStep: number;
-    pitch: number;
+    /**
+     * 1/372オクターブ単位。chord-parser が返すのは12平均律の半音なので、
+     * ここへ入れる時点で音律に応じた格子へ写している。
+     */
+    pitchUnits: Units;
     durationSteps: number;
     velocity: number;
 };
 type ApplyChordOptions = {
     chordStr: string;
+    /** 曲の音律（1オクターブの分割数）。省略時は12平均律。 */
+    edo?: number;
     patternType: ChordPatternType;
     /** ルートのセミトーンシフト（0-11） */
     rootShift: number;
     bpm: number;
     stepsPerBar: number;
 };
-/**
- * コード進行 → 伴奏ノート配置。
- */
 declare const buildChordPlacements: (options: ApplyChordOptions) => ChordPlacement[];
 
 type SongDrumInstruction = {
@@ -412,8 +561,11 @@ declare const createKoeVoice: (ctx: AudioContext, destination: AudioNode, option
 /** ストリーミング再生する歌唱ノート1つ（絶対時刻ベース）。 */
 type StreamVoiceNote = {
     syllable: LyricSyllable;
-    /** MIDIノート番号 */
-    pitch: number;
+    /**
+     * ピッチ。単位は units（1/372オクターブ）。koe は Hz を受けるので、
+     * ここから直接 Hz へ変換して歌わせる（整数MIDIノートに丸めない）。
+     */
+    pitch: Units;
     /** アンカー（再生開始時刻）からの相対秒。実発音時刻 = anchorTime + startSec。 */
     startSec: number;
     /** ゲート適用済みの発音長（秒）。 */
@@ -650,19 +802,55 @@ declare const DEFAULT_VELOCITY = 100;
 declare const DEFAULT_PLAYBACK_VELOCITY = 127;
 declare const DEFAULT_STEPS_PER_BAR = 192;
 declare const MML_END_MARKER = "#end;";
+/**
+ * ピアノロールが扱う音域の下端・上端（両端含む）。音律に依らず固定で、MIDI 0-127 に相当する。
+ * 「音律を変えても鳴らせる音の高さの範囲は変わらない」を保証するための不変条件。
+ */
+declare const PITCH_RANGE_START = 0;
+/** MIDI 127 相当。単位は 1/372オクターブ（127 × 31）。 */
+declare const PITCH_RANGE_END = 3937;
+/**
+ * 1行が受け持つピッチ幅（units）。12平均律は1半音 = 31、31平均律は1度 = 12。
+ * 行数はここから導出されるので、12平均律で128行・31平均律で328行になる。
+ */
+declare const unitsPerRow: (edo: number) => number;
+/** その音律での行数。音域と1行あたりのピッチ幅から導出する（直接指定しないこと）。 */
+declare const keyCountFor: (edo: number) => number;
+/** 12平均律の行数（従来と同じ128）。 */
+declare const KEY_COUNT: number;
 type Note = {
     id: number;
     startStep: number;
     durationSteps: number;
-    pitch: number;
+    /**
+     * ピッチ。単位は **1/372オクターブの整数**（`tuning.ts` 参照）。
+     * 12平均律の1半音 = 31、31平均律の1度 = 12。MIDIノート番号ではないので注意。
+     * dtm 1.x の `pitch`（半音）から意味が変わっている。
+     */
+    pitchUnits: Units;
     velocity?: number;
 };
 type RenderConfig = {
     stepsPerBar: number;
+    /**
+     * 行数。{@link KEY_COUNT} のように「音域 ÷ 1行あたりのピッチ幅」から導出した値を渡す。
+     * 音律ごとに直接指定しないこと（31平均律で音域が勝手に縮む）。
+     */
     keyCount: number;
+    /** 音域の下端。単位は units（1/372オクターブ）。 */
     pitchRangeStart: number;
+    /** 1行が受け持つ units。{@link unitsPerRow} から導出した値を渡す。省略時は31（12平均律）。 */
+    unitsPerRow?: number;
     keyHeight: number;
     stepWidth: number;
+    /**
+     * 曲全体の音律（1オクターブの分割数）。省略時は12（12平均律）。
+     *
+     * 音律はデータにも音声経路にも入らず、格子・記譜・表示だけに効く編集上の概念なので、
+     * 描画設定と同じ場所に置く。MMLCore も `getConfig()` 経由でここから音律を読み、
+     * 綴り（`#`=2度 / `+`=1度 など）を切り替える。
+     */
+    edo?: number;
 };
 type CoreEventHandlers = {
     onMMLGenerated: (mml: string) => void;
@@ -693,14 +881,16 @@ type LyricSyncData = {
 /** パッチ送受信用ノートデータ（ローカルIDを持たない）。 */
 type NoteData = {
     startStep: number;
-    pitch: number;
+    /** 1/372オクターブ単位。{@link Note.pitchUnits} と同じ。 */
+    pitchUnits: Units;
     durationSteps: number;
     velocity?: number;
 };
-/** パッチ削除指定（startStep + pitch で音符を特定）。 */
+/** パッチ削除指定（startStep + pitchUnits で音符を特定）。 */
 type NoteRemove = {
     startStep: number;
-    pitch: number;
+    /** 1/372オクターブ単位。{@link Note.pitchUnits} と同じ。 */
+    pitchUnits: Units;
 };
 type PianoRollOptions = {
     mountTarget: HTMLElement;
@@ -740,7 +930,13 @@ type TrackConfig = {
 };
 type PlayNoteEvent = {
     trackId: string;
-    pitch: number;
+    /**
+     * ピッチ。単位は 1/372オクターブの整数（{@link Note.pitchUnits} と同じ）。
+     * 周波数へは `tuning.ts` の `unitsToHz`、SoundFont のような整数ゾーンの音源へは
+     * `unitsToMidiDetune` を使う。{@link PlayDrumEvent.pitch} はGM打楽器のキー番号で
+     * 音高ではないため、こちらとは別物。
+     */
+    pitchUnits: Units;
     /** 元ノートのvelocity (0-127) */
     velocity: number;
     /** トラックvolume×velocityを反映した 0-1 程度の音量係数 */
@@ -822,7 +1018,7 @@ type LyricTrack = {
      */
     pan: number;
     /**
-     * オクターブシフト -2〜+2（半音換算で octave×12 だけ歌唱ピッチを上下する）。既定0。
+     * オクターブシフト -2〜+2（octave×372 units = octave オクターブぶん歌唱ピッチを上下する）。既定0。
      * 音源ごとに得意な音域が異なるため、演奏ノート（@n）のピッチをそのまま使わず
      * オクターブ単位でずらして歌わせるための合成専用パラメータ。
      * MMLでは `@@n klatt o-1 …` のように o トークンで付与する。
@@ -1195,11 +1391,12 @@ type DawInstance = {
      */
     setTrackAudible: (trackId: string, audible: boolean) => void;
     /**
-     * 指定ノート位置（step, pitch）のキャンバス上のピクセル座標を返す。
+     * 指定ノート位置（step, pitchUnits）のキャンバス上のピクセル座標を返す。
+     * `pitch` の単位は units（1/372オクターブ）。
      * 画面外の場合は onScreen=false と方角 side を返す。
      * 協力DAWでのカーソル表示に使う。
      */
-    noteToCanvas: (step: number, pitch: number) => {
+    noteToCanvas: (step: number, pitch: Units) => {
         x: number;
         y: number;
         onScreen: boolean;
@@ -1353,7 +1550,8 @@ declare const playPlacements: (placements: Array<{
     trackIndex: number;
     startStep: number;
     durationSteps: number;
-    pitch: number;
+    /** ピッチ。単位は units（1/372オクターブ）。 */
+    pitchUnits: Units;
     velocity: number;
 }>, options: PlayPlacementsOptions) => MmlPlayback;
 /**
@@ -1364,7 +1562,7 @@ declare const playMML: (mml: string, options?: PlayMmlOptions) => MmlPlayback;
 type PlayNoteOptions = {
     audioContext?: AudioContext;
     destination?: AudioNode;
-    pitch: number;
+    pitchUnits: Units;
     volume?: number;
     duration?: number;
 };
@@ -1475,6 +1673,15 @@ declare class LinkedList<T> {
 }
 
 declare const PITCH_MAP: string[];
+/**
+ * 31平均律の綴り表（度数0〜30）。
+ *
+ * 五度連鎖の伝統的綴りを基本にしつつ、重複臨時記号（`##`／`--`）を要する度数だけ
+ * 微分音記号（`+`／`_`）の短縮形を採る。結果として全31度が2文字以内に収まる。
+ * どの綴りもオクターブを跨がないものを選んであるので、`o<n>` の直後に置ける
+ * （たとえば29度は `c-` ではなく `b+`。`c-` はCの2度下＝前オクターブになってしまう）。
+ */
+declare const EDO31_NAMES: string[];
 /**
  * ノートデータ管理とMML生成の責務を持つDOM非依存のコアロジック
  */
@@ -1491,7 +1698,9 @@ declare class MMLCore {
     private lastUndoTime;
     private static readonly UNDO_DEBOUNCE_MS;
     private toolMode;
-    constructor(handlers: CoreEventHandlers, volume?: number);
+    /** グリッド寸法の供給元（描画器ではなく呼び出し側が持つ設定を読む） */
+    private getConfig;
+    constructor(handlers: CoreEventHandlers, volume: number | undefined, getConfig: () => RenderConfig);
     beginBatch(): void;
     endBatch(): void;
     saveHistory(): void;
@@ -1512,10 +1721,10 @@ declare class MMLCore {
      * @param pitch ピッチ番号
      * @param options ノート長などの設定
      */
-    addNote(step: number, pitch: number, options: AddNoteOptions): void;
+    addNote(step: number, pitch: Units, options: AddNoteOptions): void;
     deleteNoteById(noteId: number): void;
     private getMaxStep;
-    moveNote(noteId: number, startStep: number, pitch: number): void;
+    moveNote(noteId: number, startStep: number, pitch: Units): void;
     moveNoteEnd(_: number): void;
     resizeNote(noteId: number, durationSteps: number): void;
     resizeNoteEnd(_: number): void;
@@ -1533,6 +1742,8 @@ declare class MMLCore {
      * ギャップに収まる最大の音符を探す（減算アルゴリズム用）
      */
     private findBestFitDuration;
+    /** ピッチ(units) → その音律での「オクターブ番号」と「音名」。 */
+    private spell;
     /**
      * ピッチからオクターブ最適化のある音名を取得
      */
@@ -1577,13 +1788,12 @@ declare const isChordHeavyTrack: (notes: Note[], threshold?: number) => boolean;
  * applyMonophonicMacro / shiftAllNotes を移植・整理したもの。
  */
 
-/**
- * アクティブトラックにスケールに沿ったランダムなノートを8小節分配置する。
- */
 declare const generateRandomPattern: (core: MMLCore, options: {
     stepsPerBar: number;
     startStep: number;
     pitchRangeStart: number;
+    /** 曲の音律。省略時は12平均律。 */
+    edo?: number;
 }) => void;
 /**
  * 半小節ごとに伴奏トラックの構成音(pitch class)に合致しない音を削除する。
@@ -1602,11 +1812,16 @@ declare const applyMonophonic: (targetCore: MMLCore, chordCore: MMLCore, options
  */
 declare const shiftNotes: (cores: MMLCore[], shiftSteps: number) => void;
 /**
- * 全トラックのノートを一括で移調する（半音単位）。歌唱ピッチもノート由来なので、
- * 歌詞トラックの歌声も一緒に移調される。MIDI範囲(0-127)を超える場合はクランプする
- * （音域外に飛んで無音・破綻するのを防ぐ）。
+ * 全トラックのノートを一括で移調する。歌唱ピッチもノート由来なので、歌詞トラックの
+ * 歌声も一緒に移調される。音域（{@link PITCH_RANGE_START}〜{@link PITCH_RANGE_END}）を
+ * 超える場合はクランプする（音域外に飛んで無音・破綻するのを防ぐ）。
+ *
+ * 単位は「半音」ではなく**格子1ステップ**。12平均律では1ステップ＝1半音だが、
+ * 31平均律では1ステップ＝1度（≒38.7セント）になる。31平均律で「半音」は
+ * クロマチック半音（2度）とダイアトニック半音（3度）に分岐して一意に定まらないため、
+ * 画面の「移調」操作と同じ格子基準に揃えてある。
  */
-declare const transposeNotes: (cores: MMLCore[], semitones: number) => void;
+declare const transposeNotes: (cores: MMLCore[], steps: number) => void;
 
 type MidiTrackAnalysis = {
     index: number;
@@ -1752,6 +1967,11 @@ type MmlMeta = {
     fadeOut?: number;
     /** DAWの動作モード（simple | advanced） */
     mode?: "simple" | "advanced";
+    /**
+     * 曲全体の音律（1オクターブの分割数）。`#edo=31` で埋め込む。省略時は12（12平均律）。
+     * 12と31のみ対応。音律は曲単位で、トラックや小節では変えられない。
+     */
+    edo?: number;
     /**
      * トラックごとの個別楽器名（GM楽器名）。`#t<n>inst=<名前>` で埋め込む。
      * 省略されたトラックはプリセットが適用される。
@@ -1801,7 +2021,8 @@ type MMLNotePlacement = {
     /** 0:melody 1:submelody 2:bass 3:chord */
     trackIndex: number;
     startStep: number;
-    pitch: number;
+    /** 1/372オクターブ単位（{@link Note.pitchUnits} と同じ）。 */
+    pitchUnits: Units;
     durationSteps: number;
     /** v コマンドで指定されたベロシティ（0-127、既定100） */
     velocity: number;
@@ -1961,87 +2182,55 @@ type PianoRollInstance = {
 };
 declare const createPianoRoll: (options: PianoRollOptions, handlers: CoreEventHandlers) => PianoRollInstance;
 
-declare const getRenderConfig: () => RenderConfig;
 /**
- * カスタム背景画像の有無を設定します。
- * 有効時はグリッド/ヘッダーの塗りつぶしを半透明にし、背景を透過させます。
- */
-declare const setBackgroundActive: (active: boolean) => void;
-declare const getDrawOffset: () => {
-    x: number;
-    y: number;
-};
-declare const getGridCanvas: () => HTMLCanvasElement;
-declare const getGridContext: () => CanvasRenderingContext2D;
-declare const getHeaderCanvas: () => HTMLCanvasElement;
-/**
- * Canvasを初期化し、指定されたターゲット要素にマウントします。
- * ヘッダー用、鍵盤用、ノート用の3つのCanvasを作成します。
- */
-declare const init: (mountTarget: HTMLElement, width: number | undefined, height: number | undefined, config: RenderConfig) => void;
-/**
- * 鍵盤を描画します。
- * - 白鍵: クリーム色、全幅
- * - 黒鍵: 左 62% を黒塗り、右 38% は白鍵色（奥に伸びて見える）
- * - E→F / C→B(下オクターブ) の白白境界に区切り線
- */
-declare const drawKeyboard: () => void;
-declare const drawHeader: () => void;
-/**
- * グリッドと背景を描画します。（グリッドCanvasと鍵盤/ヘッダー描画の呼び出し）
- * @param noteLengthSteps ノート長ステップ数（この値ごとに縦線を表示）
- */
-declare const drawGrid: (noteLengthSteps?: number) => void;
-/**
- * 指定されたノートの配列を描画します。
- * @param notes 描画対象のノートリスト
- * @param color [r, g, b, a] のカラー値
- * @param isActive アクティブトラックかどうか（アクティブ時は立体ハイライト・鮮明表示、非アクティブ時はゴースト表示）
- */
-declare const drawNotes: (notes: Note[], color?: number[], isActive?: boolean) => void;
-/**
- * ノートの上に歌詞（かな）を重ねて描画します。
- *
- * 音節の割り当ては発音側（StreamVoiceTrack の組み立て）と同じ規則で、
- * startStep 昇順に並べたノートの i 番目へ syllables[i] を対応させます。
- * 音節が足りないぶんのノートには何も描きません。
+ * 1つのピアノロール描画面（ヘッダー/鍵盤/グリッドの3枚のCanvas）を表す描画器。
  *
- * 文字はノート矩形でクリップするため、隣のノートへはみ出しません。
- */
-declare const drawNoteLyrics: (notes: Note[], syllables: string[]) => void;
-/**
- * 選択範囲の四角形を描画します。
- */
-declare const drawSelectionRect: (rect: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-} | null) => void;
-/**
- * 選択されたノートをハイライト描画します。（濃い色で描画、枠なし）
- */
-declare const drawSelectedNotes: (notes: Note[], selectedIds: Set<number>, baseColor?: number[]) => void;
-/**
- * カーソルの座標取得
- * (グリッドCanvasの相対座標を取得)
- */
-declare const getXY: (e: MouseEvent | PointerEvent) => [number, number, number];
-declare const getGridPosition: (e: MouseEvent | PointerEvent) => {
-    step: number;
-    pitch: number;
-    x: number;
-    y: number;
+ * 以前はモジュールグローバル（`g_config` / 各Canvas / 描画オフセット）を直に触る
+ * 関数群だったが、それだと1ページに2つ以上のエディタをマウントしたとき後からマウント
+ * した側がグローバルを奪い、先にマウントした側の描画が相手のCanvasへ流れ込んでいた。
+ * 曲ごとに音律（12平均律 / 31平均律）が違うと格子まで食い違うため、描画状態は
+ * インスタンスに閉じ込める。
+ */
+type Renderer = {
+    getRenderConfig: () => RenderConfig;
+    setBackgroundActive: (active: boolean) => void;
+    getDrawOffset: () => {
+        x: number;
+        y: number;
+    };
+    getGridCanvas: () => HTMLCanvasElement;
+    getGridContext: () => CanvasRenderingContext2D;
+    getHeaderCanvas: () => HTMLCanvasElement;
+    drawKeyboard: () => void;
+    drawHeader: () => void;
+    drawGrid: (noteLengthSteps?: number) => void;
+    drawNotes: (notes: Note[], color?: number[], isActive?: boolean) => void;
+    drawNoteLyrics: (notes: Note[], syllables: string[]) => void;
+    drawSelectionRect: (rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null) => void;
+    drawSelectedNotes: (notes: Note[], selectedIds: Set<number>, baseColor?: number[]) => void;
+    getXY: (e: MouseEvent | PointerEvent) => [number, number, number];
+    getGridPosition: (e: MouseEvent | PointerEvent) => {
+        step: number;
+        /** ピッチ。単位は units（1/372オクターブ）。 */
+        pitch: Units;
+        x: number;
+        y: number;
+    };
+    onClick: (callback: (step: number, pitch: Units) => void) => void;
+    setDrawOffset: (x: number, y: number) => void;
+    /** Canvasをマウント先から取り外す。 */
+    destroy: () => void;
 };
 /**
- * ユーザーのクリックイベントを抽象化し、グリッド座標をコールバックに渡します。
- * イベントリスナーをグリッドCanvasにのみ追加します。
- */
-declare const onClick: (callback: (step: number, pitch: number) => void) => void;
-/**
- * 描画オフセット（描画開始ピクセル位置）を設定します。
+ * Canvasを生成してマウントし、そのマウント面専用の描画器を返す。
+ * 同じページに複数生成しても互いの状態を踏まない。
  */
-declare const setDrawOffset: (x: number, y: number) => void;
+declare const createRenderer: (mountTarget: HTMLElement, width: number | undefined, height: number | undefined, config: RenderConfig) => Renderer;
 
 /**
  * 再生シーケンサ。タイムライン計算と先読みスケジューリングを担い、
@@ -2097,10 +2286,13 @@ type SoundFontInstance = {
     play: (o: {
         ctx: AudioContext;
         destination: AudioNode;
+        /** 最寄りの整数MIDIノート番号（ゾーン選択用）。 */
         pitch: number;
         volume: number;
         /** 元ノートのvelocity(0-127)。音量ではなく音色の明るさにだけ効く。 */
         velocity?: number;
+        /** pitch からの微調整（セント）。31平均律など整数ノートに乗らない音高用。 */
+        detuneCents?: number;
         when: number;
         duration: number;
     }) => void;
@@ -2352,7 +2544,8 @@ type DtmStudio = {
     playDrumEvent: (e: PlayDrumEvent) => void;
     /** SoundFontを用いた単音再生を行う */
     playNote: (options: {
-        pitch: number;
+        /** ピッチ。単位は units（1/372オクターブ）。`pitchV1ToUnits` でMIDI番号から変換できる。 */
+        pitchUnits: Units;
         volume?: number;
         duration?: number;
         instrument?: string;
@@ -2444,8 +2637,11 @@ declare const showLoadingOverlay: (container: HTMLElement, options?: {
  * ミキサーへルーティングしたり、SE と AudioContext を共有したりできるようにするため。
  */
 
-/** MIDIピッチ番号 → 周波数(Hz)。A4(69)=440Hz 基準。 */
-declare const freqFromPitch: (pitch: number) => number;
+/**
+ * ピッチ(units) → 周波数(Hz)。A4 = 2139 units = 440Hz 基準。
+ * 単位は 1/372オクターブの整数（`tuning.ts` 参照）。12平均律・31平均律とも同じ式で鳴る。
+ */
+declare const freqFromPitch: (pitchUnits: Units) => number;
 type Synth = {
     /** メロディックノートを発音する（PlayNoteEvent.when は ctx.currentTime からの相対秒） */
     playNote: (e: PlayNoteEvent) => void;
@@ -2486,4 +2682,4 @@ declare const encodeWavPCM16: (channels: Float32Array[], sampleRate: number) =>
 /** Float32Array のチャンクを1本へ連結する。 */
 declare const concatFloat32: (chunks: Float32Array[]) => Float32Array;
 
-export { type AddNoteOptions, type AnyDrumPattern, 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 DrumPatternDef, type DtmStudio, type DtmStudioEngines, type DtmStudioOptions, type ExportMidiOptions, type FadeScheduleParams, 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, type OctaveUnisonMode, 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, VIBRATO_MIN_SEC, VOICE_IMAGES, VOICE_IMAGE_KEY, type VoiceExpression, type VoiceModel, type VoiceRegistry, analyzeMidiTracks, applyHarmonicFilter, applyMonophonic, buildChordPlacements, buildDrumPatternJson, buildNameToKeyMapping, collectPitchTokens, concatFloat32, createAudioContext, createDtmStudio, createKlattVoice, createKoeVoice, createLyricsConductor, createPianoRoll, createSequencer, createSingingVoices, createSynth, createVoiceRegistry, decodeMml, decomposeToMonophonic, drawGrid, drawHeader, drawKeyboard, drawNoteLyrics, drawNotes, drawSelectedNotes, drawSelectionRect, encodeMml, encodeWavPCM16, exportMIDI, extractDrumPatternFromNotes, extractMidiDrumPattern, extractMidiPlacements, extractMidiPlacementsByTrack, formatMmlMeta, freqFromPitch, generateRandomPattern, getDrawOffset, getDrumPatternKeys, getGridCanvas, getGridContext, getGridPosition, getHeaderCanvas, getMidiBPM, getRenderConfig, getXY, icon, init, injectStyles, isChordHeavyTrack, isPlausibleMidiTranscription, isValidHttpUrl, koeUrl, mountChordPlayer, mountDAW, mountMmlPlayer, normalizeDrumPatterns, normalizeLyrics, onClick, panToStereo, parseCustomVocals, parseLyrics, parseMML, parseMmlMeta, playChords, playMML, playNote, playPlacements, playSingingMML, resolveDrumPattern, resolveLoopPoint, setBackgroundActive, setDrawOffset, shiftNotes, showLoadingOverlay, stripCustomVocals, stripLyrics, stripMmlMeta, transposeNotes, vocalVolumeToGain };
+export { A4_HZ, A4_UNITS, type AddNoteOptions, type AnyDrumPattern, type ApplyChordOptions, CENTS_PER_UNIT, type ChordPatternType, type ChordPlacement, type ChordPlayerInstance, type ConsumedSyllable, type CoreEventHandlers, type CustomVocalDef, DAW_CSS, DEFAULT_BPM, DEFAULT_EDO, 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 DrumPatternDef, type DtmStudio, type DtmStudioEngines, type DtmStudioOptions, EDO31_NAMES, type Edo, type ExportMidiOptions, type FadeScheduleParams, GM_INSTRUMENT_NAMES, INSTRUMENT_PRESETS, type InstrumentPreset, KEY_COUNT, 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, MICRO_STEP, MMLCore, type MMLDisplayToken, type MMLNotePlacement, MML_END_MARKER, type MidiExtraction, type MidiNote, 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, type OctaveUnisonMode, PITCH_ENCODING_VERSION, PITCH_MAP, PITCH_RANGE_END, PITCH_RANGE_START, 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 Renderer, 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, UNITS_PER_EDO31_DEGREE, UNITS_PER_OCTAVE, UNITS_PER_SEMITONE, type Units, VIBRATO_MIN_SEC, VOICE_IMAGES, VOICE_IMAGE_KEY, type VoiceExpression, type VoiceModel, type VoiceRegistry, addUnits, analyzeMidiTracks, applyHarmonicFilter, applyMonophonic, buildChordPlacements, buildDrumPatternJson, buildNameToKeyMapping, chromaticStep, collectPitchTokens, concatFloat32, createAudioContext, createDtmStudio, createKlattVoice, createKoeVoice, createLyricsConductor, createPianoRoll, createRenderer, createSequencer, createSingingVoices, createSynth, createVoiceRegistry, decodeMml, decomposeToMonophonic, encodeMml, encodeWavPCM16, exportMIDI, extractDrumPatternFromNotes, extractMidiDrumPattern, extractMidiPlacements, extractMidiPlacementsByTrack, fifthToStep, fifthToUnits, formatMmlMeta, freqFromPitch, generateRandomPattern, getDrumPatternKeys, getMidiBPM, icon, injectStyles, isChordHeavyTrack, isNaturalLetter, isPlausibleMidiTranscription, isValidHttpUrl, keyCountFor, koeUrl, midiNote, midiToUnits, mountChordPlayer, mountDAW, mountMmlPlayer, naturalStep, normalizeDrumPatterns, normalizeLyrics, panToStereo, parseCustomVocals, parseLyrics, parseMML, parseMmlMeta, pitchV1ToUnits, playChords, playMML, playNote, playPlacements, playSingingMML, resolveDrumPattern, resolveLoopPoint, shiftNotes, showLoadingOverlay, spellingToUnits, stripCustomVocals, stripLyrics, stripMmlMeta, transposeNotes, units, unitsPerRow, unitsPerStep, unitsToHz, unitsToMidi, unitsToMidiDetune, unitsToPitchV1, vocalVolumeToGain };