Skip to main content
Glama
sd80

sd80

by senbaph08
README.md
# SD-80 Control API

Roland **SD-80 (Studio Canvas)** をLLMから演奏・制御するための **MCPサーバー + REST API +
Claude Skill** です。LLMは音色を「何の楽器か」で検索し、テキスト記法で書いた曲を
そのまま実機で鳴らせます。Bank Select / Program Change / SysEx の組み立て、発音の
スケジューリングはすべてサーバー側が行います。

> 非公式プロジェクトです。Roland Corporation とは関係がなく、同社による承認・保証は
> ありません。Roland、EDIROL、Studio Canvas、SD-80 は Roland Corporation の商標です。

```
LLM ─┬─ MCP (Streamable HTTP /mcp) ─┐
     ├─ Skill スクリプト (REST) ────┼─> ツール層 ──> コントローラ ──MIDI──> Roland SD-80
     └─ REST  POST /tools/{name} ───┘      ├ 音色辞書 1,280音色 + ドラム36セット(楽器名・タグ・音域つき)
                                           ├ ジャンル別編成 30種 / 聴き比べ / 評価の記憶
                                           └ テキスト記法 → 検算 → 高精度スケジューラ
```

## 必要なもの

- Roland SD-80(SD-90 でも同じ音色マップのため動く見込みですが未確認)
- SD-80 を USB でつないだ PC。動作確認は Windows 11 のみです
  (Windows 10 / 11 では本体を GENERIC モードで使います → [docs/SD80_DRIVER_SETUP.md](docs/SD80_DRIVER_SETUP.md))
- Python 3.10 以上

## セットアップ

```bat
py -m pip install -r requirements.txt

:: MIDIポートとSD-80自動検出の確認
py -m sd80ctl ports

:: 実機テスト(音が出ます)。SD-80が見つからない場合は --port-index N を指定
py -m sd80ctl selftest

:: サーバ起動 (http://127.0.0.1:8760 , Swagger UI は /docs)
start_server.bat
```

macOS / Linux では `py` を `python3` に読み替えてください(未検証)。
サーバーは起動時に SD-80 のポートを自動検出し、Native mode で初期化します。
別の PC から使う場合は [docs/REMOTE_SETUP.md](docs/REMOTE_SETUP.md) を参照してください。

## 使い方(3通り、中身は同じツール)

### 1. MCP

`/mcp` で Streamable HTTP(stateless)のMCPサーバーを公開しています。Claude Code で
このリポジトリを開くと、同梱の [.mcp.json](.mcp.json) により `sd80` サーバーに
接続されます(先にサーバーを起動しておく)。他のクライアントの設定例:

```json
{ "mcpServers": { "sd80": { "type": "http", "url": "http://127.0.0.1:8760/mcp" } } }
```

### 2. Claude Skill

[.claude/skills/sd80/](.claude/skills/sd80/SKILL.md) に、音色選び・記法・編曲の手順書と
クライアントスクリプトを収めたSkillがあります。Claude Code でこのリポジトリを開けば
自動で認識されます。MCPを設定していない環境でも、Skill同梱のスクリプトが同じツールを
REST経由で呼び出します。

```bat
:: 他のプロジェクトからも使えるようにユーザー全体(~/.claude/skills/sd80)へインストール
py -m sd80ctl install-skill
```

```bash
python .claude/skills/sd80/scripts/sd80.py health
python .claude/skills/sd80/scripts/sd80.py search_instruments query="tenor sax" role=solo
python .claude/skills/sd80/scripts/sd80.py play_song @.claude/skills/sd80/assets/jazz-trio-demo.json
```

### 3. REST

`POST /tools/{name}` にMCPと同じJSON引数を送ります(`GET /tools` で一覧とスキーマ)。
`py -m sd80ctl call <tool> key=value ...` でも呼べます。

```bash
curl -X POST http://127.0.0.1:8760/tools/suggest_palette -H "Content-Type: application/json" -d "{\"style\":\"jazz\"}"
```

チャンネル単位の細かいエンドポイント(`/channels/{ch}/note_on`、`/midi/sysex` など)も
スクリプト用に残してあります。一覧は `GET /` または `/docs`。

## ツール(19本)

| 分類 | ツール | 役割 |
|---|---|---|
| 状態 | `sd80_status` | 接続・モード・再生位置・使用中チャンネル・評価済み音色・保存済みの曲 |
| | `sd80_init` | 接続 + モード切替 + 全パートを既知の状態に戻す |
| 音色 | `search_instruments` | 楽器名・性格・機材名・日本語で検索。`role` で最適なサウンドセットを先頭に |
| | `browse_instruments` | 概要、または系統ごとの一覧表(4セット横並び) |
| | `get_instrument` | 1音色の詳細: 正体・音域・書き方のコツ・代替候補・ドラムのキー表 |
| | `suggest_palette` | ジャンル別の編成一式(30種): チャンネル・音色・ミックス値・代替 |
| | `audition_instruments` | 候補を順番に鳴らして聴き比べ |
| | `rate_instrument` | 聴いた人の評価を保存(検索順位に反映) |
| チャンネル | `set_channel` | 音色とミックス(volume / pan / reverb / chorus) |
| | `set_channel_control` | 任意のControl Change |
| 演奏 | `play_notes` | 1チャンネルにフレーズやドラムパターンを即再生 |
| | `play_song` | マルチトラックの曲を検算して保存・再生。`dry_run`、音色差し替え、途中再生 |
| | `list_songs` / `get_song` / `export_midi` | 保存済みの曲の一覧・取得・MIDIファイル書き出し |
| | `stop_playback` | 全停止 |
| 接続 | `list_midi_ports` / `open_midi_port` | 自動検出できないときの手動接続 |
| 説明書 | `sd80_guide` | Skillと同じ手順書(overview / tones / notation / arranging / troubleshooting) |

結果は1行1項目のコンパクトなJSONで返り、失敗時は直し方を含むメッセージを返します。
MIDIポート未接続のときは `warning: NOT CONNECTED` が必ず付きます。

## 記法

```
C4:1 E4:0.5 G4:0.5 | C4+E4+G4:2 R:2      音名:拍数 / + 和音 / R 休符 / | 小節線(拍数を検算)
C4:1@110  C4:2~ | C4:2  [C2:1 G2:1]*4    ベロシティ / タイ / 繰り返し
ped=on  expr=40>110:4  bend=1.5          ペダル / クレッシェンド / ピッチベンド
{"kick":"x...x...x...x...","snare":"....x.......x..."}    ドラムグリッド(1文字=16分)
```

曲は `tracks`(チャンネル・音色・ミックス)と `sections`(セクションごとの各パート。短い
パートは自動で繰り返す)、`arrangement`(並び順)で書きます。全文法は
[references/notation.md](.claude/skills/sd80/references/notation.md)、動く例は
[assets/jazz-trio-demo.json](.claude/skills/sd80/assets/jazz-trio-demo.json)。

`play_song` は鳴らす前に全体を検算し、小節の拍数違い・楽器の音域外・MFX音色の置き場所
違いを `warnings` で返します。曲は `data/songs/` に保存され、次のセッションでも
`song_id` で再生・編集できます。

## セキュリティ

このサーバーは接続した相手に SD-80 を操作させ、任意の SysEx も送れます。

- 既定(`start_server.bat`)は `127.0.0.1` だけで待ち受け、`localhost` 宛ての要求にしか
  応答しません(Webページからの DNS リバインディング対策)。ブラウザからの CORS も既定で
  無効です(必要なら `SD80_CORS_ORIGINS` に許可するオリジンをカンマ区切りで指定)。
- ネットワークに公開する(`--host 0.0.0.0`、`start_server_tailscale.bat`)には共有トークン
  `SD80_MCP_TOKEN` が必須です。設定すると `/health` 以外のすべてのエンドポイントで
  `Authorization: Bearer <token>` が必要になります。
- トークンなしで別のホスト名を許可したい場合は `SD80_ALLOWED_HOSTS`(カンマ区切り)。
- インターネットに直接公開しないでください。Tailscale などのプライベートネットワークか
  信頼できる LAN の中で使ってください。

## 音色辞書

同梱の `data/instruments.json` は、Roland が配布していた SD-80 / SD-90 の公式音色リスト
(`SD_inst.txt` / `SD_drum.txt` / `SD_wave.txt`)と Cakewalk 用の純正インストゥルメント
定義(`SD-80.ins`)から生成したものです。これらの元ファイルは Roland の著作物のため
このリポジトリには含めていません。そのままで使えるので、通常は元ファイルは不要です。

- 4マップ(Classical / Contemporary / Solo / Enhanced, MSB 96-99)× PC 1-128 ×
  バリエーション(LSB)、Special 1/2(MSB 80/81)、ドラムセット 4マップ(MSB 104-107)
- `instrument_id` は `{マップ}-{PC 3桁}-{LSB 2桁}`(例: `sol-001-00` = Solo の St.Piano 1)

公式リストの名前は12文字の略称なので、`sd80ctl/tonemeta.py` が各音色に次を付与します:

| 項目 | 内容 | 出どころ |
|---|---|---|
| `is` | 実際の楽器(例: `Barely Bari` → Baritone Sax) | 純正Cakewalk定義のGM2名を4マップ全部に展開 |
| `category` | 16系統。公式では無分類の Special 1/2 も分類 | Special 256音色は手作業で分類(うち41は名前からの推測で `guess` の印) |
| `tags` | stereo / rotary / jupiter / wurlitzer / distortion … | 名前の略号を規則で解読 |
| `range` | 典型的な音域 | 楽器ごとの一般的な音域 |
| `mfx` | マルチエフェクト前提の音色か | Enhanced / Special |

`tonemeta.py` を変更したときは辞書を作り直します。元ファイルを各自で用意し、
`SD80_INSTLIST/`(3ファイル)と `cw_ins/CW_SD80/SD-80.ins` に置いてから:

```bat
py -m sd80ctl build-db
```

### MFXについて

オーナーズマニュアルによると、Native modeでは Enhanced / Special の音色を選んだだけでは
エフェクト(MFX、3系統)は掛からず、出荷時設定でMFXに接続されているのはパート A01〜A03
だけです。そのためサーバーは、MFX音色がチャンネル1〜3以外に置かれると警告し、
同じ楽器の Contemporary / Solo 音色を提案します。`suggest_palette` の編成もこの配置に
従っています。本体パネルでパートのMFX割り当てを変えた場合は、この警告は当てはまりません。

### 評価の記憶

`rate_instrument` の内容は `data/user_tone_notes.json` に保存され、検索結果の表示と順位
(お気に入りは先頭、「避ける」は末尾)に反映されます。LLMは音を聴けないので、
`audition_instruments` で候補を聴き比べ → 評価を保存、という流れで選択が改善していきます。

## 制限事項

- 実機での動作確認は Windows 11 + SD-80 1台のみです。SD-90、macOS / Linux は未確認です。
- 音色の説明・ジャンル別編成・推奨音色は、名前とサウンドセットの性格から選んだもので、
  すべてを耳で確かめたわけではありません。`guess: true` の音色は特に要確認です。
- 本体の設定(MFX の割り当て、パートの受信チャンネルなど)を出荷時から変えていると、
  警告や推奨が実際と合わない場合があります。
- GM2 / GS / XG モードでは Special セットが使えず、`instrument_id` による音色選択は
  Native mode 前提です。

## トラブルシューティング

- **SD-80がポート一覧に出ない** — 本体を GENERIC モードで起動します
  ([docs/SD80_DRIVER_SETUP.md](docs/SD80_DRIVER_SETUP.md))。5pin MIDI 経由の場合は
  `POST /midi/probe` で応答ポートを特定し `open_midi_port` で開いてください。
- **`warning: NOT CONNECTED`** — MIDIポート未接続です。`sd80_init` で再接続します。
- **Enhanced/Special音色が薄い** — 上記「MFXについて」を参照。チャンネル1〜3に置きます。
- **`403 forbidden host`** — トークンなしのサーバーに別のホスト名で接続しています。
  `127.0.0.1` で接続するか、`SD80_MCP_TOKEN` を設定してください。
- その他は [references/troubleshooting.md](.claude/skills/sd80/references/troubleshooting.md)。

## 構成

```
sd80ctl/
  parser.py       公式音色リスト → data/instruments.json 変換
  insfile.py      Cakewalk 定義ファイル(.ins)の読み込みと突合
  tonemeta.py     音色メタデータ(正体・分類・タグ・音域・MFX)、サウンドセットの説明
  dictionary.py   音色辞書のロード、検索(日本語可)、ドラム名の解決、評価の保存
  palettes.py     ジャンル別編成 30種
  notation.py     テキスト記法のパーサ(音符・コントローラ・ドラムグリッド)
  song.py         ソングのモデル、コンパイルと検算、MIDIファイル書き出し、保存
  midi.py         python-rtmidi ラッパ(自動検出・Identityプローブ・A/Bグループ)
  sysex.py        モード切替SysEx・DT1(checksum自動計算)
  controller.py   パート状態、音色変更、スケジューラ、聴き比べ
  tools.py        LLM向けツール層(MCP / REST / Skill 共通)
  mcp_server.py   MCPサーバー (Streamable HTTP)
  server.py       FastAPI アプリ (REST + /mcp、アクセス制御)
  runtime.py      共有シングルトン
  cli.py          build-db / ports / selftest / serve / call / install-skill
.claude/skills/sd80/   Claude Skill(SKILL.md, references/, scripts/sd80.py, assets/)
tests/            単体テスト(偽のMIDIポートを使用、実機不要)
docs/             Windows での認識方法、別PCからの利用、API利用ガイド
data/instruments.json   音色辞書(生成済み)
```

実行中に `data/songs/`(保存した曲)、`data/user_tone_notes.json`(評価)が作られます
(`.gitignore` 済み)。

## テスト

```bat
py -m unittest discover -s tests -t tests
```

実機には触れず、偽のMIDIポートに対して送信内容とタイミングを検証します。

## ライセンス

[MIT License](LICENSE)。対象はこのリポジトリのコードとドキュメントです。

`data/instruments.json` に含まれる音色名・ドラム音名・バンク番号は Roland の公式資料に
由来する情報で、その権利は Roland Corporation に帰属します。MIT License はこれらの
名称自体には及びません。