@onjmin/dtm 0.1.100 → 0.1.102

package/README.md

@@ -75,6 +75,33 @@ const chordPlayer = studio.mountChordPlayer(chordEl, "| C | G | Am | F |", {
 chordPlayer.setVolume(65);
 ```
 
+### 「曲自体の音量」と「聴く人の音量」を分けて扱いたい場合
+
+上記の `masterVolume` / `volume` は**曲データが持つ音量**です（MML の `#volume=` と往復し、
+`daw.loadMML()` を呼ぶたびにそのMMLの値で上書きされます）。SNS のフィードのように、
+1つの `studio` を複数の投稿・複数の埋め込みプレイヤーで共有し、かつ「読者が自分の好みで
+サイト全体の音量を1つ調整したい」というケースでは、曲側の値をいじらずに
+`studio.setMasterVolume()` を使ってください。これは `studio.masterGain`（全ての
+`mountEditor` / `mountPlayer` / `mountChordPlayer` / `playSingingMML` インスタンスが
+最終的に合流する出力段の GainNode）を直接動かすため、曲データやモード切替・
+`loadMML()` の影響を一切受けません。
+
+```ts
+const studio = await createDtmStudio();
+
+// 読者側の「サイト全体の音量」— 曲を跨いで一度だけ管理すればよい
+studio.setMasterVolume(userPreferredVolume); // 0-100
+
+// 曲側の masterVolume/volume には触れない（#volume= が持つ作曲者の意図をそのまま尊重する）
+const daw = studio.mountEditor(editorEl, { initialMML: mml });
+const player = studio.mountPlayer(playerEl, mml);
+```
+
+`DawInstance.setMasterVolume` / `MmlPlayerOptions.masterVolume` と
+`DtmStudio.setMasterVolume` は同名ですが別物です。前者は「曲自体の音量」（`#volume=`
+と同期し、曲を読み込むたびに上書きされる）、後者は「聴く人の音量」（曲データと
+無関係に出力段へ一度だけ掛かる）という別レイヤーを担っています。
+
 ---
 
 ## 録音・動画エンコード用音声ストリームの取得 (`MediaStream`)

package/dist/index.d.mts

@@ -1162,9 +1162,15 @@ type DawInstance = {
     applyPatch: (trackId: string, added: NoteData[], removed: NoteRemove[]) => void;
     /** リモートから受信した歌詞・UTAU設定を適用する。 */
     applyLyrics: (trackId: string, data: LyricSyncData) => void;
-    /** マスタ音量を 0-100 で変更する。 */
+    /**
+     * このDAWインスタンス自身が持つ「曲自体の音量」（`#volume=`）を 0-100 で変更する。
+     * `getMML()`で出力・`loadMML()`で復元される、曲データの一部として永続化される値。
+     * `loadMML()` を呼ぶたびにそのMMLの `#volume=` で上書きされるため、リスナー側の
+     * 音量の好みを別途乗せたい場合は代わりに `DtmStudio.setMasterVolume`
+     * （`studio.masterGain`、曲データと無関係な出力段ゲイン）を使うこと。
+     */
     setMasterVolume: (volume: number) => void;
-    /** マスタ音量を 0-100 で変更する（`setMasterVolume` のエイリアス）。 */
+    /** `setMasterVolume` のエイリアス。 */
     setVolume: (volume: number) => void;
     /** ドラム音量を 0-100 で変更する。 */
     setDrumVolume: (volume: number) => void;
@@ -1885,7 +1891,7 @@ type MmlPlayerOptions = {
     onResumeAudio?: () => void | Promise<void>;
     /** 内蔵の簡易square-wave synthを使うか。既定は onPlayNote 未指定なら true */
     synth?: boolean;
-    /** マスタ音量 0-100。既定100。 */
+    /** マスタ音量 0-100。既定50（DAW編集画面の全体音量スライダーの既定値に合わせている）。 */
     masterVolume?: number;
     /** BPM未検出時のフォールバック。既定120 */
     defaultBpm?: number;
@@ -2123,9 +2129,12 @@ type DtmStudioEngines = {
 type DtmStudioOptions = {
     /** 既存の AudioContext を使う（未指定なら内部生成）。 */
     audioContext?: AudioContext;
-    /** マスター音量 0-1（楽器・歌声）。既定 1。 */
+    /**
+     * マスター音量 0-100（楽器・歌声）。既定100。
+     * ライブラリ内の他の音量パラメータ（`setMasterVolume` 等）と同じ0-100スケール。
+     */
     masterVolume?: number;
-    /** ドラム音量 0-1。既定 1。 */
+    /** ドラム音量 0-100。既定100。 */
     drumVolume?: number;
     /** マスタリバーブの掛かり具合 0-100。既定0（オフ）。全トラックへ一律で掛かる。 */
     reverbAmount?: number;
@@ -2351,9 +2360,18 @@ type DtmStudio = {
      * getDaw() で現在の DawInstance を取得できる（mountPresetSelect の getDaw に渡せる）。
      */
     mountModeSwitch: (target: HTMLElement, options: ModeSwitchOptions) => ModeSwitchInstance;
-    /** マスタ音量を 0-100 で変更する。 */
+    /**
+     * studio 全体（このstudioを共有する全ての mountEditor / mountPlayer / mountChordPlayer /
+     * playSingingMML インスタンス）の出力段ゲインを 0-100 で変更する。
+     *
+     * これは「聴く人（リスナー）側の音量設定」用のノブで、曲データとは無関係に
+     * オーディオグラフの最終段（`studio.masterGain`）に一度だけ掛かる。
+     * `DawInstance.setMasterVolume` / `MmlPlayerOptions.masterVolume`（`#volume=`
+     * と往復する“曲自体が持つ音量”）とは別物なので混同しないこと。
+     * `daw.loadMML()` や `#volume=` の内容に一切影響されない。
+     */
     setMasterVolume: (volume: number) => void;
-    /** マスタ音量を 0-100 で変更する（`setMasterVolume` のエイリアス）。 */
+    /** `setMasterVolume` のエイリアス。 */
     setVolume: (volume: number) => void;
     /** マスタリバーブの掛かり具合を 0-100 で変更する。 */
     setReverbAmount: (amount: number) => void;

package/dist/index.d.ts

@@ -1162,9 +1162,15 @@ type DawInstance = {
     applyPatch: (trackId: string, added: NoteData[], removed: NoteRemove[]) => void;
     /** リモートから受信した歌詞・UTAU設定を適用する。 */
     applyLyrics: (trackId: string, data: LyricSyncData) => void;
-    /** マスタ音量を 0-100 で変更する。 */
+    /**
+     * このDAWインスタンス自身が持つ「曲自体の音量」（`#volume=`）を 0-100 で変更する。
+     * `getMML()`で出力・`loadMML()`で復元される、曲データの一部として永続化される値。
+     * `loadMML()` を呼ぶたびにそのMMLの `#volume=` で上書きされるため、リスナー側の
+     * 音量の好みを別途乗せたい場合は代わりに `DtmStudio.setMasterVolume`
+     * （`studio.masterGain`、曲データと無関係な出力段ゲイン）を使うこと。
+     */
     setMasterVolume: (volume: number) => void;
-    /** マスタ音量を 0-100 で変更する（`setMasterVolume` のエイリアス）。 */
+    /** `setMasterVolume` のエイリアス。 */
     setVolume: (volume: number) => void;
     /** ドラム音量を 0-100 で変更する。 */
     setDrumVolume: (volume: number) => void;
@@ -1885,7 +1891,7 @@ type MmlPlayerOptions = {
     onResumeAudio?: () => void | Promise<void>;
     /** 内蔵の簡易square-wave synthを使うか。既定は onPlayNote 未指定なら true */
     synth?: boolean;
-    /** マスタ音量 0-100。既定100。 */
+    /** マスタ音量 0-100。既定50（DAW編集画面の全体音量スライダーの既定値に合わせている）。 */
     masterVolume?: number;
     /** BPM未検出時のフォールバック。既定120 */
     defaultBpm?: number;
@@ -2123,9 +2129,12 @@ type DtmStudioEngines = {
 type DtmStudioOptions = {
     /** 既存の AudioContext を使う（未指定なら内部生成）。 */
     audioContext?: AudioContext;
-    /** マスター音量 0-1（楽器・歌声）。既定 1。 */
+    /**
+     * マスター音量 0-100（楽器・歌声）。既定100。
+     * ライブラリ内の他の音量パラメータ（`setMasterVolume` 等）と同じ0-100スケール。
+     */
     masterVolume?: number;
-    /** ドラム音量 0-1。既定 1。 */
+    /** ドラム音量 0-100。既定100。 */
     drumVolume?: number;
     /** マスタリバーブの掛かり具合 0-100。既定0（オフ）。全トラックへ一律で掛かる。 */
     reverbAmount?: number;
@@ -2351,9 +2360,18 @@ type DtmStudio = {
      * getDaw() で現在の DawInstance を取得できる（mountPresetSelect の getDaw に渡せる）。
      */
     mountModeSwitch: (target: HTMLElement, options: ModeSwitchOptions) => ModeSwitchInstance;
-    /** マスタ音量を 0-100 で変更する。 */
+    /**
+     * studio 全体（このstudioを共有する全ての mountEditor / mountPlayer / mountChordPlayer /
+     * playSingingMML インスタンス）の出力段ゲインを 0-100 で変更する。
+     *
+     * これは「聴く人（リスナー）側の音量設定」用のノブで、曲データとは無関係に
+     * オーディオグラフの最終段（`studio.masterGain`）に一度だけ掛かる。
+     * `DawInstance.setMasterVolume` / `MmlPlayerOptions.masterVolume`（`#volume=`
+     * と往復する“曲自体が持つ音量”）とは別物なので混同しないこと。
+     * `daw.loadMML()` や `#volume=` の内容に一切影響されない。
+     */
     setMasterVolume: (volume: number) => void;
-    /** マスタ音量を 0-100 で変更する（`setMasterVolume` のエイリアス）。 */
+    /** `setMasterVolume` のエイリアス。 */
     setVolume: (volume: number) => void;
     /** マスタリバーブの掛かり具合を 0-100 で変更する。 */
     setReverbAmount: (amount: number) => void;

package/dist/index.js

@@ -8851,7 +8851,7 @@ var mountMmlPlayer = (target, mml, options = {}) => {
   };
   const drumPatternName = meta.drum ?? "none";
   const trackVolume = meta.volume ?? options.volume ?? 100;
-  let masterVolume = options.masterVolume ?? 100;
+  let masterVolume = options.masterVolume ?? 50;
   const drumVolume = meta.drumVolume ?? 80;
   const colors = options.trackColors ?? DEFAULT_TRACK_COLORS;
   const useSynth = options.synth ?? !options.onPlayNote;
@@ -18219,6 +18219,8 @@ var playSingingMML = async (mml, options = {}) => {
   const drumVolume = meta.drumVolume ?? 80;
   const trackVolume = meta.volume ?? 100;
   let masterVolume = options.volume ?? 100;
+  const trackVolumePercent = () => trackVolume / 100 * masterVolume;
+  const masterGainScalar = () => trackVolume / 100 * (masterVolume / 100);
   const trackIndices = [...new Set(placements.map((p) => p.trackIndex))].sort(
     (a, b) => a - b
   );
@@ -18233,7 +18235,7 @@ var playSingingMML = async (mml, options = {}) => {
     }));
     return {
       id: TRACK_ID_BY_INDEX2[index] ?? `t${index}`,
-      volume: trackVolume / 100 * masterVolume,
+      volume: trackVolumePercent(),
       notes
     };
   });
@@ -18270,7 +18272,7 @@ var playSingingMML = async (mml, options = {}) => {
     return {
       id: TRACK_ID_BY_INDEX2[index] ?? `t${index}`,
       model: lt.model,
-      volume: vocalVolumeToGain(lt.volume ?? DEFAULT_VOCAL_VOLUME),
+      volume: vocalVolumeToGain(lt.volume ?? DEFAULT_VOCAL_VOLUME) * masterGainScalar(),
       pan: panToStereo(lt.pan ?? DEFAULT_PAN),
       vibrato: lt.vibrato,
       reverbSend: (lt.reverb ?? 0) / 100,
@@ -18305,7 +18307,7 @@ var playSingingMML = async (mml, options = {}) => {
       synth?.playNote(e);
     },
     onPlayDrum: (e) => {
-      const velocity = e.velocity * (drumVolume / 100) * (trackVolume / 100) * (masterVolume / 100);
+      const velocity = e.velocity * (drumVolume / 100) * masterGainScalar();
       options.onPlayDrum?.({ ...e, velocity });
       synth?.playDrum({ ...e, velocity });
     },
@@ -18339,9 +18341,8 @@ var playSingingMML = async (mml, options = {}) => {
   };
   const setVolume = (volume) => {
     masterVolume = volume;
-    const effectiveTrackVolume = trackVolume / 100 * masterVolume;
-    for (const t of seqTracks) t.volume = effectiveTrackVolume;
-    voices?.setVolume(trackVolume / 100 * (masterVolume / 100));
+    for (const t of seqTracks) t.volume = trackVolumePercent();
+    voices?.setVolume(masterGainScalar());
   };
   const suspend = () => ctx.suspend();
   const resume = () => ctx.resume();
@@ -18427,7 +18428,7 @@ var playSingingMML = async (mml, options = {}) => {
         loopLengthSec = (loopEndStep - loopStartStep) * secondsPerStep;
       }
       seq.start(options.startStep ?? 0);
-      voices.setVolume(trackVolume / 100 * (masterVolume / 100));
+      voices.setVolume(masterGainScalar());
       voices.startStream(streamTracks, seq.getStartTime(), {
         loopLengthSec,
         loopStartSec
@@ -19155,9 +19156,9 @@ var createDtmStudio = async (options = {}) => {
   });
   const audioCtx = options.audioContext ?? new AudioContext({ sampleRate: 44100 });
   const masterGain = audioCtx.createGain();
-  masterGain.gain.value = options.masterVolume ?? 1;
+  masterGain.gain.value = (options.masterVolume ?? 100) / 100;
   const drumGain = audioCtx.createGain();
-  drumGain.gain.value = options.drumVolume ?? 1;
+  drumGain.gain.value = (options.drumVolume ?? 100) / 100;
   drumGain.connect(masterGain);
   let reverbDecaySec = options.reverbDecay ?? DEFAULT_REVERB_DECAY_SEC;
   const reverbPreDelay = audioCtx.createDelay(MAX_REVERB_PREDELAY_MS / 1e3);

package/dist/index.mjs

@@ -8718,7 +8718,7 @@ var mountMmlPlayer = (target, mml, options = {}) => {
   };
   const drumPatternName = meta.drum ?? "none";
   const trackVolume = meta.volume ?? options.volume ?? 100;
-  let masterVolume = options.masterVolume ?? 100;
+  let masterVolume = options.masterVolume ?? 50;
   const drumVolume = meta.drumVolume ?? 80;
   const colors = options.trackColors ?? DEFAULT_TRACK_COLORS;
   const useSynth = options.synth ?? !options.onPlayNote;
@@ -18086,6 +18086,8 @@ var playSingingMML = async (mml, options = {}) => {
   const drumVolume = meta.drumVolume ?? 80;
   const trackVolume = meta.volume ?? 100;
   let masterVolume = options.volume ?? 100;
+  const trackVolumePercent = () => trackVolume / 100 * masterVolume;
+  const masterGainScalar = () => trackVolume / 100 * (masterVolume / 100);
   const trackIndices = [...new Set(placements.map((p) => p.trackIndex))].sort(
     (a, b) => a - b
   );
@@ -18100,7 +18102,7 @@ var playSingingMML = async (mml, options = {}) => {
     }));
     return {
       id: TRACK_ID_BY_INDEX2[index] ?? `t${index}`,
-      volume: trackVolume / 100 * masterVolume,
+      volume: trackVolumePercent(),
       notes
     };
   });
@@ -18137,7 +18139,7 @@ var playSingingMML = async (mml, options = {}) => {
     return {
       id: TRACK_ID_BY_INDEX2[index] ?? `t${index}`,
       model: lt.model,
-      volume: vocalVolumeToGain(lt.volume ?? DEFAULT_VOCAL_VOLUME),
+      volume: vocalVolumeToGain(lt.volume ?? DEFAULT_VOCAL_VOLUME) * masterGainScalar(),
       pan: panToStereo(lt.pan ?? DEFAULT_PAN),
       vibrato: lt.vibrato,
       reverbSend: (lt.reverb ?? 0) / 100,
@@ -18172,7 +18174,7 @@ var playSingingMML = async (mml, options = {}) => {
       synth?.playNote(e);
     },
     onPlayDrum: (e) => {
-      const velocity = e.velocity * (drumVolume / 100) * (trackVolume / 100) * (masterVolume / 100);
+      const velocity = e.velocity * (drumVolume / 100) * masterGainScalar();
       options.onPlayDrum?.({ ...e, velocity });
       synth?.playDrum({ ...e, velocity });
     },
@@ -18206,9 +18208,8 @@ var playSingingMML = async (mml, options = {}) => {
   };
   const setVolume = (volume) => {
     masterVolume = volume;
-    const effectiveTrackVolume = trackVolume / 100 * masterVolume;
-    for (const t of seqTracks) t.volume = effectiveTrackVolume;
-    voices?.setVolume(trackVolume / 100 * (masterVolume / 100));
+    for (const t of seqTracks) t.volume = trackVolumePercent();
+    voices?.setVolume(masterGainScalar());
   };
   const suspend = () => ctx.suspend();
   const resume = () => ctx.resume();
@@ -18294,7 +18295,7 @@ var playSingingMML = async (mml, options = {}) => {
         loopLengthSec = (loopEndStep - loopStartStep) * secondsPerStep;
       }
       seq.start(options.startStep ?? 0);
-      voices.setVolume(trackVolume / 100 * (masterVolume / 100));
+      voices.setVolume(masterGainScalar());
       voices.startStream(streamTracks, seq.getStartTime(), {
         loopLengthSec,
         loopStartSec
@@ -19021,9 +19022,9 @@ var createDtmStudio = async (options = {}) => {
   });
   const audioCtx = options.audioContext ?? new AudioContext({ sampleRate: 44100 });
   const masterGain = audioCtx.createGain();
-  masterGain.gain.value = options.masterVolume ?? 1;
+  masterGain.gain.value = (options.masterVolume ?? 100) / 100;
   const drumGain = audioCtx.createGain();
-  drumGain.gain.value = options.drumVolume ?? 1;
+  drumGain.gain.value = (options.drumVolume ?? 100) / 100;
   drumGain.connect(masterGain);
   let reverbDecaySec = options.reverbDecay ?? DEFAULT_REVERB_DECAY_SEC;
   const reverbPreDelay = audioCtx.createDelay(MAX_REVERB_PREDELAY_MS / 1e3);

package/package.json

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