max-patgen

name	max-patgen
description	MaxMSPパッチ(.maxpat/.maxhelp)をJSONとして生成する

max-patgen

MaxMSPパッチを生JSONで直接生成する。外部ツール依存なし。

Trigger

ユーザーがMaxパッチの生成・作成を要求したとき。

Format Overview

.maxpat / .maxhelp は 同一のJSONフォーマット。拡張子と配置場所が違うのみ。

{
  "patcher" : {
    "fileversion" : 1,
    "appversion" : { "major" : 8, "minor" : 6, "revision" : 4 },
    "classnamespace" : "box",
    "rect" : [100, 100, 640, 480],
    "bglocked" : 0,
    "openrect" : [0, 0, 0, 0],
    "openinpresentation" : 0,
    "default_fontsize" : 12,
    "default_fontface" : 0,
    "default_fontname" : "Arial",
    "gridonopen" : 2,
    "gridsize" : [15, 15],
    "gridsnaponopen" : 0,
    "objectsnaponopen" : 1,
    "statusbarvisible" : 2,
    "toolbarvisible" : 2,
    "lefttoolbarpinned" : 0,
    "toptoolbarpinned" : 0,
    "righttoolbarpinned" : 0,
    "bottomtoolbarpinned" : 0,
    "toolbars_unpinned_last_save" : 0,
    "tallnewobj" : 0,
    "boxanimatetime" : 200,
    "enablehscroll" : 1,
    "enablevscroll" : 1,
    "devicewidth" : 0,
    "description" : "",
    "digest" : "",
    "tags" : "",
    "style" : "",
    "subpatcher_template" : "",
    "assistshowspatchername" : 0,
    "boxes" : [ ],
    "lines" : [ ]
  }
}

Box (オブジェクト)

{
  "box" : {
    "id" : "obj-1",
    "maxclass" : "newobj",
    "numinlets" : 2,
    "numoutlets" : 1,
    "outlettype" : [ "signal" ],
    "patching_rect" : [50, 100, 80, 22],
    "text" : "cycle~ 440"
  }
}

• id: "obj-N" 形式の文字列。連番。
• maxclass: "newobj" (一般オブジェクト) またはUI部品名 ("toggle", "number", "flonum", "button", "slider", "comment", "message", "live.dial", 等)
• text: ボックス内のテキスト (maxclass: "newobj" のみ)。
  • 書式: オブジェクト名 引数1 引数2 @属性名 値
  • 例: cycle~ 440, *~ 0.5, metro 500 @active 1
• patching_rect: [x, y, width, height]
  • 標準newobj: height=22
  • comment: height=20
  • UI部品は各部品のデフォルトheight
• numinlets / numoutlets / outlettype: 必ず正確に設定。不一致はMaxでエラー。

Line (接続)

{
  "patchline" : {
    "source" : ["obj-1", 0],
    "destination" : ["obj-2", 0]
  }
}

• source: [box_id, outlet_index] (0-indexed)
• destination: [box_id, inlet_index] (0-indexed)
• 省略可能: "midpoints" : [x, y, ...] (ケーブルの中継点座標)
• "color" : [r, g, b, a] (0.0-1.0) でケーブル色を指定可能

Subpatcher (ネスト)

box内に "patcher" キーで子パッチャーを定義:

{
  "box" : {
    "id" : "obj-3",
    "maxclass" : "newobj",
    "numinlets" : 1,
    "numoutlets" : 1,
    "outlettype" : [""],
    "patching_rect" : [50, 200, 100, 22],
    "text" : "p mysubpatch",
    "patcher" : {
      "fileversion" : 1,
      "boxes" : [
        {
          "box" : {
            "id" : "obj-1",
            "maxclass" : "inlet",
            "numinlets" : 0,
            "numoutlets" : 1,
            "outlettype" : [""],
            "patching_rect" : [50, 50, 25, 25]
          }
        },
        {
          "box" : {
            "id" : "obj-2",
            "maxclass" : "outlet",
            "numinlets" : 1,
            "numoutlets" : 0,
            "patching_rect" : [50, 150, 25, 25]
          }
        }
      ],
      "lines" : [
        { "patchline" : { "source" : ["obj-1", 0], "destination" : ["obj-2", 0] } }
      ]
    }
  }
}

Generation Workflow

1. 要件把握: ユーザーが作りたいパッチの目的・構成を確認
2. オブジェクト選定: reference/objects_*.md から適切なオブジェクトを選択
3. テンプレート選択: templates/ から近いテンプレートを選び出発点にする。ゼロからの場合は empty.maxpat を使用
4. 座標計算: 下記 Layout Rules に従い配置
5. JSON構築: boxes[] と lines[] を組み立て
6. 検証: Validation Checklist を確認
7. 出力: .maxpat または .maxhelp として保存

Layout Rules

基本グリッド

• x間隔: 120px (オブジェクト幅の目安: 80px, 余白40px)
• y間隔: 60px (信号の流れ: 上→下)
• 開始位置: x=50, y=50

信号の流れ

入力 → 処理1 → 処理2 → 出力
(左→右 の流れも可。上→下 を基本とする)

配置パターン

直列チェーン (縦配置):

obj-1: [50, 50]
obj-2: [50, 110]  (+60)
obj-3: [50, 170]  (+60)

並列→ミックス (横→縦):

obj-1: [50, 50]
obj-2: [170, 50]   (+120横)
obj-3: [50, 110]   (+60縦, mix)

フィードバック (右に逃がして戻す):

obj-1: [50, 50]
obj-2: [50, 110]
obj-3: [290, 80]    (フィードバック経路)

コメント配置

• 説明コメントは対象オブジェクトの 左上 に配置: [obj.x - 10, obj.y - 25]
• セクション区切りコメントは [50, y - 30] に配置

ポート番号に注意

• inlet / outlet 共に 左から右へ 0-indexed (左端 = 0)
• プロキシインレットの番号付けに注意。詳細は Inlet/Outlet Indexing セクションを参照

Object Selection

用途に応じて reference/ 配下のファイルを参照:

用途	ファイル
音声処理 (MSP)	reference/objects_msp.md
MIDI処理	reference/objects_midi.md
映像処理 (Jitter)	reference/objects_jitter.md
データ/ロジック	reference/objects_logic.md
フォーマット詳細	reference/format.md

Template Usage

templates/ 配下のテンプレートを出発点として使う:

テンプレート	用途
empty.maxpat	ゼロから作成する場合の最小ひな形
audio_synth.maxpat	オシレータ→ゲイン→DAC の基本シンセ
audio_fx_chain.maxpat	エフェクトチェーン (delay/reverb等)
midi_process.maxpat	MIDI入力→処理→出力
jitter_basic.maxpat	映像入力→加工→表示
data_logic.maxpat	データ処理/ロジックの基本
help_template.maxhelp	ヘルプパッチのテンプレート

テンプレートの使い方:

1. テンプレートファイルを読み込む
2. boxes にオブジェクトを追加 (idは "obj-N" の連番を継続)
3. lines に接続を追加
4. 必要に応じて既存オブジェクトのパラメータを変更

maxhelp Generation

.maxhelp は .maxpat と 完全に同一のJSONフォーマット。拡張子を .maxhelp にするだけ。

ヘルプパッチの慣習

1. 先頭に comment でオブジェクト名と概要を記載
2. 対象オブジェクト を中央に配置
3. インレット説明: 左側に inlet の用途を記載した comment
4. アウトレット説明: 右側に outlet の用途を記載した comment
5. 使用例: 下部に代表的な使用例を subpatcher またはインラインで配置
6. preset: バリエーションを preset オブジェクトで保存
7. locked: "bglocked" : 1 で背景をロック推奨

ヘルプパッチのレイアウト

[Title Comment]
[Description Comment]

[Inlet Docs] → [TARGET OBJECT] → [Outlet Docs]

[Example 1]
[Example 2]

[preset]

Common Patterns

オーディオ信号チェーン

oscillator → *~ (gain) → effect → ezdac~

MIDI → Audio

notein → midiparse → mtof → oscillator → envelope → *~ → ezdac~

エフェクトパラレル

input → tapin~/tapout~ (delay)
     → *~ (dry/wet mix) → output

Jitter映像処理

jit.movie → jit.op → jit.colorspace → jit.window

データ蓄積

input → pack → coll (保存)
coll → unpack → 出力 (読み出し)

Validation Checklist

出力前に以下を確認:

• 全boxに id, maxclass, numinlets, numoutlets, patching_rect が存在
• maxclass: "newobj" のboxに text が存在
• outlettype が numoutlets の数と一致
• IDが "obj-1", "obj-2"... の連番で重複なし
• lines の source/destination の box_id が実在するboxを参照
• lines の outlet/inlet index が対象boxの numoutlets/numinlets の範囲内
• JSONが有効 (カンマ過多/不足なし)
• "patching_rect" の値が合理的 (負の座標なし、width>0, height>0)

Safety

• 既存の .maxpat / .maxhelp を上書きする場合はユーザーに確認
• filepath パラメータを含むオブジェクト (readsf~, jit.movie 等) はプレースホルダを使用
• パッチが大きすぎる場合 (50+ オブジェクト) は subpatcher への分割を提案

Acceptance Criteria

• 生成された .maxpat / .maxhelp が Max 8/9 でエラーなく開ける
• 全ての patchline が有効な接続先を参照している
• オブジェクトの inlet/outlet 数が正確
• レイアウトが重なりなく視認可能