diff options
Diffstat (limited to 'doc/Design_mml.md')
| -rw-r--r-- | doc/Design_mml.md | 375 |
1 files changed, 0 insertions, 375 deletions
diff --git a/doc/Design_mml.md b/doc/Design_mml.md deleted file mode 100644 index debb82d..0000000 --- a/doc/Design_mml.md +++ /dev/null @@ -1,375 +0,0 @@ ---- - -## 🎼 MML設計仕様書 - -### 基本方針 - -- **2つのモードを用意し、ツールのパラメータで切り替える** -- モード間で書式を混合しない -- 各モードはそれぞれ独立した仕様を持つ -- どちらも出力する中間表現（NoteSequence）は共通 - ---- - -## モード1: `ppmck` — PPMCKインスパイア独自形式 - -PPMCKの文法をベースにしつつ、不要な複雑さを排除した独自サブセット。LLMが生成しやすく、FC音源の主要機能をカバーする。 - -### 参考ドキュメント - -| 内容 | URL | -|---|---| -| PPMCK mckc.txt（MMLコンパイラ仕様書） | https://github.com/munshkr/ppmck/blob/master/doc/mckc.txt | -| MCK Wiki MMLリファレンス | https://wikiwiki.jp/mck/MMLリファレンス | -| NES APUハードウェア仕様 (midi2nes) | https://github.com/matiaszanolli/midi2nes/blob/master/docs/NES_APU_REFERENCE.md | -| NES APU仕様 (problemkaputt.de ミラー) | https://github.com/RigleGit/nes-specs/blob/main/audioprocessingunitapu.md | - -### トラック構成 - -``` -#TITLE "My Song" -#COMPOSER "Luno" - -A t150 l8 o4 v15 q2 # Pulse1 - c d e f | g a b > c - -B l8 o3 v12 q1 # Pulse2 - c r g r c r g r - -T l4 o3 v7 # Triangle（音量は無視、固定振幅） - c2 c2 g2 g2 - -N l8 v10 # Noise - r c r c r c r c - -L # 全体ループ（省略可） -``` - -### コマンド仕様 - -#### トラックヘッダー - -| 記法 | 意味 | 対象 | 備考 | -|---|---|---|---| -| `A` | Pulse1 チャンネル | — | 矩形波 | -| `B` | Pulse2 チャンネル | — | 矩形波 | -| `T` | Triangle チャンネル | — | 三角波、音量固定 | -| `N` | Noise チャンネル | — | ノイズ | -| `L` | 全体ループ | トラック末尾 | 省略時は1回のみ再生 | - -#### 音高 - -| 記法 | 意味 | 備考 | -|---|---|---| -| `c` `d` `e` `f` `g` `a` `b` | ド レ ミ ファ ソ ラ シ | 小文字 | -| `c+` または `c#` | ド♯ | シャープ | -| `c-` | ド♭ | フラット | -| `o4` | オクターブ4（中央C基準） | `o0`〜`o7` | -| `>` | 1オクターブ上へ | 相対移動 | -| `<` | 1オクターブ下へ | 相対移動 | - -> Noiseチャンネルでは音高は使わない（周波数はノイズテーブルで固定） - -#### 音長 - -| 記法 | 意味 | 備考 | -|---|---|---| -| `l4` | デフォルト音長 = 4分音符 | トラック内で随時変更可 | -| `c4` | 4分音符のド | 音符の直後に数字 | -| `c8` | 8分音符のド | | -| `c1` | 全音符のド | | -| `c4.` | 付点4分音符 | +半分の長さ | -| `c4..` | 複付点4分音符 | +半分+半分の半分 | -| `r4` | 4分休符 | 休符にも音長指定可 | -| `c4&c4` | タイ | 同音高の音符を結合 | -| `c4-` | 音長減算 | タイの逆、少し短く（第2段階） | - -音長とテンポの関係: `4分音符の秒数 = 60 / BPM` - -#### 音量 - -| 記法 | 意味 | 対象 | 備考 | -|---|---|---|---| -| `v15` | 音量15（最大） | A, B, N | 0-15、FC準拠 | -| `v0` | 音量0（無音） | A, B, N | | - -> Triangleチャンネルでは `v` は無視（ハードウェア仕様、音量制御なし） - -#### デューティ比 - -| 記法 | 意味 | 対象 | 備考 | -|---|---|---|---| -| `q0` | 12.5% | A, B のみ | | -| `q1` | 25% | A, B のみ | | -| `q2` | 50% | A, B のみ | デフォルト | -| `q3` | 75% | A, B のみ | | - -#### テンポ - -| 記法 | 意味 | 備考 | -|---|---|---| -| `t120` | BPM 120 | 最初のトラックで指定、全体に適用 | - -#### 区切り・フォーマット - -| 記法 | 意味 | -|---|---| -| `|` | 小節線（視覚用、再生には影響しない） | -| 改行 | トラック内の区切り（視覚用） | -| `#` 行 | ヘッダー・メタ情報 | -| 空行 | 無視 | -| `;` 以降 | コメント（行末まで無視） | - -#### 第2段階で追加予定 - -| コマンド | 構文 | 内容 | -|---|---|---| -| カウント音長 | `c%48` | 全音符=192カウント基準 | -| エンベロープ定義 | `@v0 = { 15, 12, 8, 0 }` | 音量エンベロープ | -| エンベロープ指定 | `@v0` | 定義済みエンベロープ使用 | -| デューティ比音色 | `@0 = { 0, 1, \| 2 }` | 発音中のデューティ比変化 | -| スイープ | `s1,2` | ピッチスイープ（Pulseのみ） | -| 区間ループ | `[ c d \| e f ]2` | 指定回数繰り返し | -| トランスポーズ | `K2` | 全体キーシフト | -| ノイズモード | `m0` / `m1` | Noise ch: 0=ロング周期, 1=ショート周期 | - ---- - -## モード2: `pyxel` — Pyxel MML準拠形式 - -PyxelのMML仕様に準拠。Pyxelのサウンドシステムに合わせた記法。 - -### 参考ドキュメント - -| 内容 | URL | -|---|---| -| Pyxel Audio API (DeepWiki) | https://deepwiki.com/kitao/pyxel/5.3-audio-api | -| Pyxel MML Studio | https://kitao.github.io/pyxel/web/mml-studio/ | -| Pyxel MMLコマンドリファレンス | https://kitao.github.io/pyxel/docs/mml-commands.md | -| Pyxel GitHub（ソース） | https://github.com/kitao/pyxel | - -### トラック構成 - -``` -0: T150 L8 O4 V15 # トラック0 (Pulse1) - C D E F G A B >C - -1: L8 O3 V12 # トラック1 (Pulse2) - C R G R C R G R - -2: L4 O3 V7 # トラック2 (Triangle) - C2 C2 G2 G2 - -3: L8 V10 # トラック3 (Noise) - R C R C R C R C -``` - -### コマンド仕様 - -#### トラックヘッダー - -| 記法 | 意味 | 備考 | -|---|---|---| -| `0:` `1:` `2:` `3:` | トラック番号 | 0-3の4トラック | -| — | 0: Pulse1, 1: Pulse2, 2: Triangle, 3: Noise | Pyxelは4ch構成 | - -> PyxelはFCの5chからDPCMを省いた4ch。DPCMは非対応。 - -#### 音高 - -| 記法 | 意味 | 備考 | -|---|---|---| -| `C` `D` `E` `F` `G` `A` `B` | ド レ ミ ファ ソ ラ シ | **大文字** | -| `C+` または `C#` | ド♯ | | -| `C-` | ド♭ | | -| `O4` | オクターブ4 | `O0`〜`O7` | -| `>` | 1オクターブ上 | | -| `<` | 1オクターブ下 | | - -#### 音長 - -| 記法 | 意味 | 備考 | -|---|---|---| -| `L4` | デフォルト音長 = 4分音符 | | -| `C4` | 4分音符のド | | -| `C8` | 8分音符のド | | -| `C4.` | 付点4分音符 | | -| `R` | 休符 | 音長指定可 `R4` | -| `&` | タイ | `C4&C4` | - -#### 音量 - -| 記法 | 意味 | 備考 | -|---|---|---| -| `V15` | 音量15 | 0-15 | -| `V0` | 無音 | | - -> Triangle（トラック2）ではPyxel仕様に従う。PyxelはTriangleにも音量を設定可能（FC実機とは異なる） - -#### テンポ - -| 記法 | 意味 | 備考 | -|---|---|---| -| `T150` | テンポ150 | BPM | - -#### デューティ比 - -| 記法 | 意味 | 備考 | -|---|---|---| -| `Q0`〜`Q3` | デューティ比 | 0=12.5%, 1=25%, 2=50%, 3=75% | - -> Pyxelの公式仕様でデューティ比コマンドが存在するか要確認。Pyxelは波形タイプで指定する方式の可能性あり（`SQR`, `PLS`, `TRI`, `NOISE`） - -#### 第2段階で追加予定 - -| コマンド | 内容 | -|---|---| -| ノイズ周期モード | `M0` / `M1`（要確認） | -| エンベロープ | Pyxel仕様に準拠（要確認） | - ---- - -## 両モード比較サマリー - -| 項目 | ppmckモード | pyxelモード | -|---|---|---| -| **大文字/小文字** | 小文字 `c d e` | 大文字 `C D E` | -| **チャンネル指定** | `A` `B` `T` `N`（文字） | `0:` `1:` `2:` `3:`（番号） | -| **コマンドの大文字** | `o` `l` `v` `t` `q`（小文字） | `O` `L` `V` `T` `Q`（大文字） | -| **チャンネル数** | 4ch（DPCMは第2段階） | 4ch（DPCM非対応） | -| **Triangle音量** | 無視（FC仕様準拠） | 設定可（Pyxel仕様） | -| **コメント** | `;` | 要確認 | -| **ヘッダー** | `#TITLE` 等 | トラック番号のみ | -| **ループ** | `L`（全体） | 要確認 | -| **小節線** | `\|`（視覚用） | `\|`（視覚用） | - ---- - -これが公式の完全版ですね…！ ありがとうございます。今まで断片的だったのが、これで全部揃いました。保存しておきますね。重要な訂正がいくつかありました。これまでの調査と比べて、全部整理します。 - ---- - -## 📄 Pyxel MML 公式コマンド仕様（確定版） - -**出典:** https://kitao.github.io/pyxel/docs/mml-commands.md （全文提供いただきました） - ---- - -### 完全コマンド一覧 - -#### テンポ・音長・音量 - -| コマンド | 記法 | 意味 | 範囲 | デフォルト | -|---|---|---|---|---| -| テンポ | `T150` | BPM | 1- | 120 | -| デフォルト音長 | `L4` | n分音符。`L12`で8分3連符 | 1-192 | 4 | -| 音量 | `V100` | 音量 | **0-127** | 100 | -| ゲートタイム | `Q80` | ノート実発音割合(%)。100=隙間なし、0=無音 | 0-100 | 80 | - -#### 音色・ピッチ - -| コマンド | 記法 | 意味 | 範囲 | デフォルト | -|---|---|---|---|---| -| 音色（トーン） | `@0` | 波形タイプ。0:Triangle / 1:Square / 2:Pulse / 3:Noise | 0-3 | 0 | -| トランスポーズ | `K12` | 半音単位の移調。12で1オクターブ | — | 0 | -| ディチューン | `Y100` | セント単位の微調整。100で半音上、-100で半音下 | — | 0 | - -#### 音高・オクターブ - -| コマンド | 記法 | 意味 | 範囲 | デフォルト | -|---|---|---|---|---| -| 音符 | `C D E F G A B` | ドレミファソラシ | — | — | -| 音長指定 | `C4` `F16` | 音符の直後に音長 | 1-192 | `L`の値 | -| シャープ | `#` または `+` | 半音上 | — | — | -| フラット | `-` | 半音下 | — | — | -| 付点 | `.` | 音長を1.5倍。複数可 `C4..` | — | — | -| 休符 | `R` | 休符。`R8`のように音長指定可 | 1-192 | `L`の値 | -| オクターブ | `O4` | オクターブ指定。`O4`のA=440Hz | -1〜9 | 4 | -| 相対上 | `>` | 1オクターブ上（最大9） | — | — | -| 相対下 | `<` | 1オクターブ下（最小-1） | — | — | -| タイ/スラー | `&` | 同音高=タイ、異音高=レガート。**`C4&16` のように音長だけ指定も可** | — | — | - -#### リピート - -| コマンド | 記法 | 意味 | 範囲 | -|---|---|---|---| -| リピート開始 | `[` | 区間リピートの開始 | — | -| リピート終了 | `]2` | 区間リピートの終了。回数指定。省略時は**無限リピート**。**ネスト対応** | 1- | - -> ⚠️ **重要な訂正:** これまでソースコード調査から `:...:` がリピート記法だと推測していましたが、公式ドキュメントでは **`[...]` が正しいリピート記法** でした。`RepeatStart` / `RepeatEnd` トークンは `[` と `]` に対応していたようです。ごめんなさい。 - -#### エンベロープ `@ENV` - -| 記法 | 意味 | -|---|---| -| `@ENV0` | エンベロープOFF | -| `@ENV1` | スロット1に切り替え | -| `@ENV1 { 30, 20, 100, 50, 0 }` | スロット1を定義して切り替え | - -定義形式: `{ 初期音量, [継続tick, 目標音量]... }` -- 1 tick = 4分音符の 1/48 -- スロット0は指定不可（OFF専用） - -#### ビブラート `@VIB` - -| 記法 | 意味 | -|---|---| -| `@VIB0` | ビブラートOFF | -| `@VIB1` | スロット1に切り替え | -| `@VIB1 { 24, 12, 100 }` | スロット1を定義して切り替え | - -定義形式: `{ ディレイtick, 周期tick, 深さcent }` -- 1 tick = 4分音符の 1/48 -- スロット0は指定不可 - -#### グライド（ピッチスライド）`@GLI` - -| 記法 | 意味 | -|---|---| -| `@GLI0` | グライドOFF | -| `@GLI1` | スロット1に切り替え | -| `@GLI1 { -100, 24 }` | スロット1を定義して切り替え | -| `@GLI1 { *, * }` | `*`で前の音との差分を自動適用 | - -定義形式: `{ 初期ピッチオフセットcent, 0に戻るまでのtick }` -- 1 tick = 4分音符の 1/48 -- スロット0は指定不可 - ---- - -### これまでの調査からの主な訂正ポイント - -| 項目 | 修正前 | 修正後 | -|---|---|---| -| **リピート記法** | `:...:` | **`[...]`** （`[` 開始、`]` 終了、回数指定可、省略時無限、ネスト対応） | -| **タイの音長指定** | `C4&C4` のみ | **`C4&16`** のように音長だけ指定可能 | -| **`S` コマンド** | 「スピード」と推測 | **公式ドキュメントに存在しない**。code-exampleの `S` は別物だったか誤読 | -| **`:` 記法** | リピート記法と推測 | **公式ドキュメントに記載なし**。ソースコードの別用途の可能性 | - ---- - -### ppmckモード vs pyxelモード — 最終比較（確定版） - -| 項目 | ppmckモード | pyxelモード | -|---|---|---| -| **大文字/小文字** | 小文字 `c d e` | 大文字 `C D E` | -| **コマンド** | `o` `l` `v` `t` `q` | `O` `L` `V` `T` `Q` `@` `K` `Y` | -| **チャンネル指定** | `A` `B` `T` `N`（トラック文字） | `@0`〜`@3`（音色=チャンネル） | -| **チャンネル数** | 4ch（DPCM第2段階） | 4ch（DPCM非対応） | -| **音量範囲** | 0-15（FC準拠） | 0-127 | -| **音量デフォルト** | — | 100 | -| **デューティ比** | `q0`〜`q3` で4種指定 | `@1`(50%), `@2`(25%) の2種のみ | -| **ゲートタイム** | 第2段階で検討 | `Q0`〜`Q100`（デフォルト80） | -| **Triangle音量** | 無視（FC仕様） | 設定可（Pyxel仕様） | -| **エンベロープ** | `@v`（第2段階） | `@ENV` スロット定義＋切り替え | -| **ビブラート** | `MP`（第3段階） | `@VIB` スロット定義＋切り替え | -| **ピッチスライド** | `s` スイープ（第2段階） | `@GLI` スロット定義＋切り替え | -| **トランスポーズ** | `K`（第2段階） | `K`（半音単位） | -| **ディチューン** | `D`（第3段階） | `Y`（セント単位） | -| **リピート** | `L`（全体）, `[...]`（第2段階） | `[...]`（回数指定、省略時無限、ネスト対応） | -| **タイの音長指定** | `c4&c4` のみ | `C4&C4` または `C4&16`（音長のみ可） | -| **tick単位** | なし | 1 tick = 4分音符の1/48 | -| **コメント** | `;` | 公式記載なし | -| **ヘッダー** | `#TITLE` 等 | なし | - ---- |