From b7f717df8ddc046139811fd8e8ee2399924ee71e Mon Sep 17 00:00:00 2001 From: tanaka takashi Date: Sat, 11 Jul 2026 22:17:57 +0900 Subject: ドキュメントとコメント一部更新 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 6 +- doc/Design.md | 34 ++++---- doc/mcp.md | 4 +- plans/trademark-replacement-plan.md | 146 ++++++++++++++++++++++++++++++++ pyproject.toml | 2 +- src/mml_composemusic_mcp/server.py | 2 +- src/mml_composemusic_mcp/synthesizer.py | 4 +- tests/test_synthesizer.py | 2 +- 8 files changed, 173 insertions(+), 27 deletions(-) create mode 100644 plans/trademark-replacement-plan.md diff --git a/README.md b/README.md index 231c56e..e5a1b51 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # mml-composemusic-mcp -ファミコン音源（2A03 APU）風のMMLをLLMに作曲させるためのMCPサーバです。 +レトロチップ音源（2A03 APU）風のMMLをLLMに作曲させるためのMCPサーバです。 `compose_mml` という1つのツールで、MMLの**作曲（WAV生成）**、**構文検証**、**テンプレート生成**を行えます。 @@ -24,7 +24,7 @@ | 機能 | 説明 | |---|---| -| `compose` | MMLを解析し、NES APU風の矩形波/三角波/ノイズでWAVファイルを生成する | +| `compose` | MMLを解析し、レトロAPU風の矩形波/三角波/ノイズでWAVファイルを生成する | | `validate` | MMLの構文を検証し、エラー・警告・チャンネル概要を返す | | `template` | `ppmck` / `pyxel` 用のテンプレートMMLを生成する | @@ -32,7 +32,7 @@ | モード | 特徴 | |---|---| -| `ppmck` | PPMCKインスパイアのFC準拠形式。小文字コマンド、`A`/`B`/`T`/`N` トラック | +| `ppmck` | PPMCKインスパイアのクラシックAPU準拠形式。小文字コマンド、`A`/`B`/`T`/`N` トラック | | `pyxel` | Pyxel MML準拠形式。大文字コマンド、`0:`〜`3:` トラック、リピート・ゲートタイム対応 | --- diff --git a/doc/Design.md b/doc/Design.md index b2ded54..fdaf860 100644 --- a/doc/Design.md +++ b/doc/Design.md @@ -1,4 +1,4 @@ -# ファミコン音源作曲MCPサーバ — 統合設計書 +# レトロチップ音源作曲MCPサーバ — 統合設計書 > 作成日: 2026-07-11 | ステータス: **実装済み（第1段階）** @@ -8,15 +8,15 @@ ### 1.1 目的 -LLMがMML（Music Macro Language）を記述することで、ファミコン（NES）のAPU音源をエミュレートした音楽を作曲・再生できるMCPサーバを設計・実装する。 +LLMがMML（Music Macro Language）を記述することで、レトロチップ音源（2A03 APU）のAPU音源をエミュレートした音楽を作曲・再生できるMCPサーバを設計・実装する。 ### 1.2 設計目標 | 目標 | 内容 | |---|---| | **LLMフレンドリ** | LLMが生成しやすいMML構文、明確なエラーメッセージ | -| **2モード対応** | `ppmck`モード（FC準拠）と`pyxel`モード（Pyxel準拠）を切り替え可能 | -| **正確な音源エミュレーション** | NES APU 4チャンネルの特性を忠実に再現 | +| **2モード対応** | `ppmck`モード（クラシックAPU準拠）と`pyxel`モード（Pyxel準拠）を切り替え可能 | +| **正確な音源エミュレーション** | レトロAPU 4チャンネルの特性を忠実に再現 | | **拡張性** | DPCM、エンベロープ等の第2段階機能を前提とした設計 | | **単一ツール** | `compose_mml` の1ツールで作曲・検証・テンプレート生成を完結 | @@ -25,7 +25,7 @@ LLMがMML（Music Macro Language）を記述することで、ファミコン（ | 対象 | 内容 | |---|---| | 第1段階（実装済み） | 4ch MML解析、WAV合成、バリデーション、テンプレート生成、基本エラーコード | -| 第2段階（将来） | DPCMチャンネル、NSFファイル出力、FC実機風非線形ミキシング、エンベロープ合成、区間ループ（ppmck） | +| 第2段階（将来） | DPCMチャンネル、NSFファイル出力、クラシックAPU実機風非線形ミキシング、エンベロープ合成、区間ループ（ppmck） | | 対象外 | GUI / Webフロントエンド | ### 1.4 技術スタック @@ -470,7 +470,7 @@ mode = 1 if period >= 13 else 0 ## 6. APU音声合成エンジン -### 6.1 NES APU ハードウェア仕様 +### 6.1 レトロAPU ハードウェア仕様 #### 概要 @@ -535,20 +535,20 @@ NoteSequence │ ├─ 3. ミキシング │ 第1段階: 線形ミキシング (ch1+ch2+ch3+ch4)/4 - │ 第2段階: NES非線形ミキシングテーブル + │ 第2段階: レトロAPU非線形ミキシングテーブル │ └─ 4. ノーマライズ → 16bit PCM → WAV出力 ``` ### 6.3 ミキシング仕様 -| 項目 | 第1段階（線形） | 第2段階（FC実機風） | +| 項目 | 第1段階（線形） | 第2段階（クラシックAPU実機風） | |---|---|---| -| 方式 | 単純平均 `(ch1+ch2+ch3+ch4)/4` | NES非線形ミキシング | +| 方式 | 単純平均 `(ch1+ch2+ch3+ch4)/4` | レトロAPU非線形ミキシング | | クリッピング | -1.0 ~ 1.0 でクランプ | 実機と同様の段階的ミックス | | ノーマライズ | 有効時ピークを-1.0に正規化 | 無効化可能 | -> FC実機の非線形ミキシング: `output = 95.88 - (8128 / (sum_of_active_channels + 1))`。第2段階で実装。 +> クラシックAPU実機の非線形ミキシング: `output = 95.88 - (8128 / (sum_of_active_channels + 1))`。第2段階で実装。 --- @@ -556,7 +556,7 @@ NoteSequence ### 7.1 モード1: `ppmck` — PPMCKインスパイア独自形式 -PPMCKの文法をベースにしつつ、不要な複雑さを排除した独自サブセット。LLMが生成しやすく、FC音源の主要機能をカバーする。 +PPMCKの文法をベースにしつつ、不要な複雑さを排除した独自サブセット。LLMが生成しやすく、クラシックAPU音源の主要機能をカバーする。 #### 参考ドキュメント @@ -564,8 +564,8 @@ PPMCKの文法をベースにしつつ、不要な複雑さを排除した独自 |---|---| | 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 | +| レトロAPUハードウェア仕様 (midi2nes) | https://github.com/matiaszanolli/midi2nes/blob/master/docs/NES_APU_REFERENCE.md | +| レトロAPU仕様 (problemkaputt.de ミラー) | https://github.com/RigleGit/nes-specs/blob/main/audioprocessingunitapu.md | #### トラック構成例 @@ -631,7 +631,7 @@ L # 全体ループ（省略可） | 記法 | 意味 | 対象 | 備考 | |---|---|---|---| -| `v15` | 音量15（最大） | A, B, N | 0-15、FC準拠 | +| `v15` | 音量15（最大） | A, B, N | 0-15、クラシックAPU準拠 | | `v0` | 音量0（無音） | A, B, N | | > Triangleチャンネルでは `v` は無視（ハードウェア仕様、音量制御なし） @@ -885,7 +885,7 @@ PyxelのMML仕様に準拠。Pyxelのサウンドシステムに合わせた記 | **コマンド** | `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 | +| **音量範囲** | 0-15（クラシックAPU準拠） | 0-127 | | **音量デフォルト** | 15 | 100 | | **デューティ比** | `q0`〜`q3` で4種 | `@1`(50%), `@2`(25%) の2種のみ（Pulse系のみ有効） | | **ゲートタイム** | 第2段階で検討 | `Q0`〜`Q100`（default 80） | @@ -941,7 +941,7 @@ PyxelのMML仕様に準拠。Pyxelのサウンドシステムに合わせた記 |---|---| | DPCMチャンネル | 5ch目のDPCM対応 | | NSF出力 | NSFファイル出力の検討 | -| 非線形ミキシング | FC実機風ミキシングテーブル | +| 非線形ミキシング | クラシックAPU実機風ミキシングテーブル | | エンベロープ合成 | `@v`(ppmck), `@ENV`(pyxel) の合成反映 | | ppmck 区間リピート | `[...]` の展開 | | ppmck スイープ | `s` コマンド | @@ -963,4 +963,4 @@ PyxelのMML仕様に準拠。Pyxelのサウンドシステムに合わせた記 --- -以上が、ファミコン音源作曲MCPサーバの統合設計書です。 +以上が、レトロチップ音源作曲MCPサーバの統合設計書です。 diff --git a/doc/mcp.md b/doc/mcp.md index b5a6b88..fbc8dbd 100644 --- a/doc/mcp.md +++ b/doc/mcp.md @@ -6,7 +6,7 @@ | ツール名 | 説明 | |---------|------| -| `compose_mml` | ファミコン音源風MMLの解析・合成・テンプレート生成を行う | +| `compose_mml` | レトロチップ音源風MMLの解析・合成・テンプレート生成を行う | ## `compose_mml` @@ -14,7 +14,7 @@ MML文字列を解析し、以下のいずれかの処理を実行します。 -- `compose`: MMLをNES APU風音源で合成し、WAVファイルを出力する +- `compose`: MMLをレトロAPU風音源で合成し、WAVファイルを出力する - `validate`: MMLの構文を検証し、エラー・警告・チャンネル概要を返す - `template`: 指定したモード用のテンプレートMMLを生成する diff --git a/plans/trademark-replacement-plan.md b/plans/trademark-replacement-plan.md new file mode 100644 index 0000000..7261bf3 --- /dev/null +++ b/plans/trademark-replacement-plan.md @@ -0,0 +1,146 @@ +# 商標リスク用語 置き換え対応計画 + +> 作成日: 2026-07-11 | ステータス: **計画中** + +## 1. 背景・目的 + +GitHub公開にあたり、任天堂の登録商標（ファミコン、Famicom、NES、FC等）がドキュメント・ソースコードに含まれている。商標権侵害のリスクを排除するため、これらの用語を商標問題のない汎用的な表現に置き換える。 + +## 2. 置き換えマッピング + +### 2.1 高リスク用語（置き換え対象） + +| 現在の用語 | 置き換え後 | リスク分類 | +|-----------|-----------|-----------| +| ファミコン音源 | レトロチップ音源 | 任天堂登録商標「ファミコン」 | +| ファミコン音源風 | レトロチップ音源風 | 同上 | +| ファミコン（NES） | レトロチップ音源（2A03 APU） | 同上 | +| ファミコン音源作曲MCPサーバ | レトロチップ音源作曲MCPサーバ | 同上 | +| Famicom-style | retro chiptune-style | 任天堂登録商標「Famicom」 | +| Famicom | retro chiptune | 同上 | +| NES APU | レトロAPU | 任天堂登録商標「NES」 | +| NES APU風 | レトロAPU風 | 同上 | +| NES APU-style | retro APU-style | 同上 | +| NES noise | retro noise | 同上 | +| NES非線形ミキシング | レトロAPU非線形ミキシング | 同上 | +| NES APU 4チャンネル | レトロAPU 4チャンネル | 同上 | +| NES APUハードウェア仕様 | レトロAPUハードウェア仕様 | 同上 | +| FC準拠 | クラシックAPU準拠 | 任天堂登録商標「FC」（Family Computer略称） | +| FC実機風 | クラシックAPU実機風 | 同上 | +| FC音源 | クラシックAPU音源 | 同上 | + +### 2.2 低リスク用語（置き換え不要） + +| 用語 | 理由 | +|------|------| +| 2A03 | Ricoh製チップのハードウェア型番。商標ではなく部品番号 | +| PPMCK | オープンソースのMMLコンパイラ名 | +| Pyxel | オープンソースのPythonゲームエンジン名 | +| DPCM | 汎用技術用語（Differential Pulse Code Modulation） | +| NSF | 汎用フォーマット名（NES Sound Format）※「NES」を含むが略語として定着 | + +> **注記:** NSFは「NES Sound Format」の略だが、ファイルフォーマット名として独自名詞的に定着している。第2段階の将来機能であり現状は未実装のため、今回は置き換え不要と判断。必要に応じて別途検討。 + +## 3. 影響範囲 + +### 3.1 ファイル別出現箇所 + +```mermaid +graph LR + A[商標リスク用語
計24箇所] --> B[README.md
3箇所] + A --> C[pyproject.toml
1箇所] + A --> D[doc/mcp.md
2箇所] + A --> E[doc/Design.md
14箇所] + A --> F[src/server.py
1箇所] + A --> G[src/synthesizer.py
2箇所] + A --> H[tests/test_synthesizer.py
1箇所] +``` + +### 3.2 詳細出現リスト + +#### README.md（3箇所） + +| 行 | 現在 | 置き換え後 | +|----|------|-----------| +| 3 | `ファミコン音源（2A03 APU）風のMML` | `レトロチップ音源（2A03 APU）風のMML` | +| 27 | `NES APU風の矩形波/三角波/ノイズ` | `レトロAPU風の矩形波/三角波/ノイズ` | +| 35 | `PPMCKインスパイアのFC準拠形式` | `PPMCKインスパイアのクラシックAPU準拠形式` | + +#### pyproject.toml（1箇所） + +| 行 | 現在 | 置き換え後 | +|----|------|-----------| +| 4 | `Famicom-style MML composition` | `retro chiptune-style MML composition` | + +#### doc/mcp.md（2箇所） + +| 行 | 現在 | 置き換え後 | +|----|------|-----------| +| 9 | `ファミコン音源風MMLの解析・合成` | `レトロチップ音源風MMLの解析・合成` | +| 17 | `MMLをNES APU風音源で合成し` | `MMLをレトロAPU風音源で合成し` | + +#### doc/Design.md（14箇所） + +| 行 | 現在 | 置き換え後 | +|----|------|-----------| +| 1 | `ファミコン音源作曲MCPサーバ` | `レトロチップ音源作曲MCPサーバ` | +| 11 | `ファミコン（NES）のAPU音源` | `レトロチップ音源（2A03 APU）のAPU音源` | +| 18 | `FC準拠` | `クラシックAPU準拠` | +| 19 | `NES APU 4チャンネル` | `レトロAPU 4チャンネル` | +| 28 | `FC実機風非線形ミキシング` | `クラシックAPU実機風非線形ミキシング` | +| 473 | `NES APU ハードウェア仕様` | `レトロAPU ハードウェア仕様` | +| 538 | `NES非線形ミキシングテーブル` | `レトロAPU非線形ミキシングテーブル` | +| 547 | `NES非線形ミキシング` | `レトロAPU非線形ミキシング` | +| 559 | `FC音源の主要機能` | `クラシックAPU音源の主要機能` | +| 567 | `NES APUハードウェア仕様` | `レトロAPUハードウェア仕様` | +| 568 | `NES APU仕様` | `レトロAPU仕様` | +| 634 | `FC準拠` | `クラシックAPU準拠` | +| 888 | `FC準拠` | `クラシックAPU準拠` | +| 966 | `ファミコン音源作曲MCPサーバ` | `レトロチップ音源作曲MCPサーバ` | + +#### src/mml_composemusic_mcp/server.py（1箇所） + +| 行 | 現在 | 置き換え後 | +|----|------|-----------| +| 59 | `Famicom-style MML` | `retro chiptune-style MML` | + +#### src/mml_composemusic_mcp/synthesizer.py（2箇所） + +| 行 | 現在 | 置き換え後 | +|----|------|-----------| +| 1 | `NES APU-style synthesizer` | `retro APU-style synthesizer` | +| 29 | `NES noise: rate = ...` | `retro noise: rate = ...` | + +#### tests/test_synthesizer.py（1箇所） + +| 行 | 現在 | 置き換え後 | +|----|------|-----------| +| 1 | `NES APU synthesizer engine` | `retro APU synthesizer engine` | + +## 4. 実行ステップ + +### Step 1: ドキュメント類の置き換え +1. `README.md` — 3箇所 +2. `doc/mcp.md` — 2箇所 +3. `doc/Design.md` — 14箇所 + +### Step 2: 設定ファイルの置き換え +4. `pyproject.toml` — 1箇所 + +### Step 3: ソースコードの置き換え +5. `src/mml_composemusic_mcp/server.py` — 1箇所（docstring） +6. `src/mml_composemusic_mcp/synthesizer.py` — 2箇所（docstring + コメント） + +### Step 4: テストコードの置き換え +7. `tests/test_synthesizer.py` — 1箇所（docstring） + +### Step 5: 検証 +8. テスト実行: `uv run pytest` で回帰確認 +9. 最終検索: `ファミコン|Famicom|NES|FC準拠|FC実機|FC音源` で残存0件を確認 + +## 5. 注意事項 + +- **コードロジックへの影響なし**: すべての置き換えは docstring・コメント・ドキュメント内の文字列のみ。実行ロジックには影響しない。 +- **API互換性維持**: `mode` パラメータの値（`ppmck`/`pyxel`）は変更しない。ユーザ向けIFはそのまま。 +- **2A03は保持**: チップ型番「2A03」は商標ではないため、技術仕様の補足として残す。 +- **外部URLは変更しない**: 参考文献のGitHub URL（midi2nes, nes-specs等）は外部リソースへのリンクであり、プロジェクト自身の商標使用ではないため変更不要。 \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 6ee2458..9070507 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "mml-composemusic-mcp" version = "0.1.0" -description = "MCP server for LLM-driven Famicom-style MML composition" +description = "MCP server for LLM-driven retro chiptune-style MML composition" readme = "README.md" requires-python = ">=3.14" dependencies = [ diff --git a/src/mml_composemusic_mcp/server.py b/src/mml_composemusic_mcp/server.py index f21159a..04b5546 100644 --- a/src/mml_composemusic_mcp/server.py +++ b/src/mml_composemusic_mcp/server.py @@ -56,7 +56,7 @@ def compose_mml( sample_rate: int = 44100, normalize: bool = True, ) -> dict: - """Compose, validate, or generate templates for Famicom-style MML.""" + """Compose, validate, or generate templates for retro chiptune-style MML.""" if action == "template": if mode not in ("ppmck", "pyxel"): mode = "ppmck" diff --git a/src/mml_composemusic_mcp/synthesizer.py b/src/mml_composemusic_mcp/synthesizer.py index 42a3c11..6d9ffe2 100644 --- a/src/mml_composemusic_mcp/synthesizer.py +++ b/src/mml_composemusic_mcp/synthesizer.py @@ -1,4 +1,4 @@ -"""NES APU-style synthesizer: NoteSequence -> WAV.""" +"""Retro APU-style synthesizer: NoteSequence -> WAV.""" import wave from math import floor @@ -26,7 +26,7 @@ def midi_to_freq(note_number: int) -> float: def noise_period_to_rate(period: int, mode: int, sample_rate: int) -> float: - # NES noise: rate = CPU_CLOCK / (NTSC divider for period) + # Retro noise: rate = CPU_CLOCK / (NTSC divider for period) # Approximate using pyxel mapping described in design dividers = [ 4, diff --git a/tests/test_synthesizer.py b/tests/test_synthesizer.py index d9680b6..722e64b 100644 --- a/tests/test_synthesizer.py +++ b/tests/test_synthesizer.py @@ -1,4 +1,4 @@ -"""Tests for the NES APU synthesizer engine.""" +"""Tests for the retro APU synthesizer engine.""" import wave -- cgit v1.2.3