@onjmin/dtm 0.1.101 → 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;
@@ -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;
@@ -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

@@ -19156,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

@@ -19022,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.101",
+  "version": "0.1.102",
   "description": "MMLを中間言語に用いた、モバイルファーストなDAW / ピアノロール打ち込みコンポーネント",
   "homepage": "https://onjmin.github.io/dtm",
   "repository": {