m4l-project

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

M4L Project

M4L Project

このスキルは、Max for LiveデバイスをLLMが作るときに必要な実務ルールだけを残した統合スキルである。網羅的なリファレンスではなく、壊れやすい判断を避けるためのチェックリストとして使う。
This skill is an integrated skill that retains only the practical rules needed when an LLM creates Max for Live devices. Rather than serving as an exhaustive reference, use it as a checklist for avoiding fragile implementation decisions.

基本方針

Basic Policy

  1. MUST: 生成スクリプトを正本として扱う。
    .maxpat
    /
    .amxd
    は生成物であり、直接編集した場合も必ず生成スクリプトへ反映する。
  2. MUST: デバイスごとに
    packages/<device>/
    を作り、少なくとも
    devices/
    ,
    scripts/
    ,
    assets/
    ,
    releases/
    ,
    DESIGN.md
    ,
    VERSION
    ,
    LICENSE
    の責務を分ける。
  3. MUST: UI寸法、色、余白、表示ロジック、MIDI仕様、同期仕様を変えたら
    packages/<device>/DESIGN.md
    に記録する。
  4. SHOULD: Max patcher JSONは構造化データとして扱い、文字列置換で編集しない。
  5. NEVER:
    .amxd
    を
    .maxpat
    のリネームで作らない。
  6. NEVER: 生成物だけを直して、生成元と乖離させない。
  1. MUST: Treat the generation script as the source of truth.
    .maxpat
    /
    .amxd
    are generated artifacts; even if they are edited directly, all changes must always be reflected in the generation script.
  2. MUST: Create
    packages/<device>/
    for each device, with clear separation of responsibilities among at least
    devices/
    ,
    scripts/
    ,
    assets/
    ,
    releases/
    ,
    DESIGN.md
    ,
    VERSION
    , and
    LICENSE
    .
  3. MUST: Record changes to UI dimensions, colors, spacing, display logic, MIDI specifications, and synchronization specifications in
    packages/<device>/DESIGN.md
    .
  4. SHOULD: Treat Max patcher JSON as structured data rather than editing it through string replacement.
  5. NEVER: Create an
    .amxd
    by renaming a
    .maxpat
    file.
  6. NEVER: Modify only the generated artifacts and allow them to diverge from their generation sources.

Max for Live生成

Max for Live Generation

  1. MUST: MIDI Effectは
    midiin
    /
    notein
    から入力し、
    midiout
    /
    noteout
    へ出力する。
  2. MUST: Audio Effect / Instrument / MIDI Effect のデバイスタイプを決めてから、I/Oと
    .amxd
    typeを合わせる。
  3. MUST: MIDI Effectの
    .amxd
    は FOURCC
    mmmm
    と
    project.amxdtype = 1835887981
    を持つ。
  4. MUST:
    .maxpat
    は
    openinpresentation: 1
    を持つ。
  5. MUST: visible UI object は
    presentation: 1
    と整数
    presentation_rect
    を持つ。
  6. MUST: 全visible UI objectは
    x + w <= devicewidth
    かつ
    y + h <= 169
    を満たす。
  7. SHOULD: 画像、JS、外部依存を使う
    .amxd
    は単体ロードできるように依存ファイルを同梱する。
  1. MUST: MIDI Effects must receive input from
    midiin
    /
    notein
    and send output to
    midiout
    /
    noteout
    .
  2. MUST: Determine whether the device is an Audio Effect, Instrument, or MIDI Effect before aligning its I/O with the
    .amxd
    type.
  3. MUST: An
    .amxd
    for a MIDI Effect must have the FOURCC
    mmmm
    and
    project.amxdtype = 1835887981
    .
  4. MUST: A
    .maxpat
    must have
    openinpresentation: 1
    .
  5. MUST: Every visible UI object must have
    presentation: 1
    and an integer
    presentation_rect
    .
  6. MUST: Every visible UI object must satisfy
    x + w <= devicewidth
    and
    y + h <= 169
    .
  7. SHOULD: An
    .amxd
    that uses images, JS, or external dependencies must include its dependency files so that it can load independently.

UI / Presentation

UI / Presentation

  1. MUST: Max for Liveデバイスの高さは
    169px
    固定として設計する。
  2. MUST: UIを変更したら、Presentation boundsを機械的に検査する。
  3. MUST: 背景panelを使う場合は、操作UIを覆わない重なり順にする。
  4. SHOULD:
    live.*
    UIはLiveテーマとの整合性を優先し、必要以上に色を上書きしない。
  5. SHOULD: 固定サイズの入力欄、アイコン、キャンバス、ロゴは安定した
    presentation_rect
    を持たせ、値変更でレイアウトが動かないようにする。
  1. MUST: Design Max for Live devices with a fixed height of
    169px
    .
  2. MUST: Mechanically validate Presentation bounds whenever the UI changes.
  3. MUST: When using a background panel, ensure its layering does not obscure the interactive UI.
  4. SHOULD: Prioritize consistency with the Live theme for
    live.*
    UI elements and avoid overriding colors more than necessary.
  5. SHOULD: Give fixed-size input fields, icons, canvases, and logos stable
    presentation_rect
    values so that value changes do not shift the layout.

JS / MIDIロジック

JS / MIDI Logic

  1. MUST: 表示上のドット判定と発音判定は同じ関数、または同じデータから導出する。
  2. MUST: Note OnとNote Offの対応を崩さない。
  3. MUST: 入力MIDIを使う仕様では、入力が無いときに勝手にフォールバック音を鳴らさない。
  4. MUST: Randomの対象は仕様で明示された値だけに限定する。
  5. MUST: 「ヒットした瞬間だけ鳴る」仕様では、同じヒット範囲内にいる間に再発音しないエッジ判定を入れる。
  6. SHOULD: Max JSの関数名はMaxメッセージ名との対応が分かるようにする。
  7. SHOULD: JS
    Task
    は低優先度イベントであることを前提にし、Freeze/Exportで厳密なMIDIタイミングが必要な処理には慎重に使う。
  1. MUST: The visual dot-state check and note-trigger check must use the same function or be derived from the same data.
  2. MUST: Preserve the correspondence between Note On and Note Off events.
  3. MUST: For specifications that use input MIDI, do not automatically play a fallback note when no input is present.
  4. MUST: Limit the scope of
    Random
    to values explicitly defined by the specification.
  5. MUST: For behavior that fires only at the hit instant, include edge detection so that notes are not retriggered while the same hit range remains active.
  6. SHOULD: Make Max JS function names clearly reflect their corresponding Max message names.
  7. SHOULD: Treat a JS
    Task
    as a low-priority event and use it cautiously for processing that requires strict MIDI timing during Freeze/Export.

Transport / Freeze / Export

Transport / Freeze / Export

  1. MUST: Live API (
    live.object
    ,
    live.observer
    ,
    LiveAPI
    ) を発音クロックとして使わない。Live APIは低優先度・非同期で、Freeze/Export中のタイミング源として信頼しない。
  2. SHOULD: Transport同期が必要な場合は、Maxのtransport/tempo-relative clockなど、Live transportに同期するMax側の仕組みを使う。
  3. MUST: 重い処理でscheduler tickが飛んだとき、過去イベントを現在時刻にまとめて発音するcatch-up実装にしない。遅れた過去音は捨てるか、明示した別モードにする。
  4. MUST: 同じtransport位置・同じdegree・同じtickが複数回来ても、同じイベントを再発音しない。
  5. SHOULD: Freeze/Exportで問題が出る場合は、JS内の発音スケジューリングよりもMax標準オブジェクト (
    makenote
    ,
    pipe
    ,
    flush
    ,
    midiformat
    など) へ逃がすことを検討する。
  1. MUST: Do not use the Live API (
    live.object
    ,
    live.observer
    ,
    LiveAPI
    ) as a note-timing clock. The Live API is low-priority and asynchronous and must not be relied upon as a timing source during Freeze/Export.
  2. SHOULD: When Transport synchronization is required, use a Max-side mechanism synchronized to the Live transport, such as Max's transport/tempo-relative clock.
  3. MUST: Do not use a catch-up implementation that batches past events and triggers them all at the current time when heavy processing causes scheduler ticks to be missed. Discard delayed past notes or define a separate mode explicitly.
  4. MUST: Do not retrigger the same event when the same Transport position, degree, and tick occur multiple times.
  5. SHOULD: If problems occur during Freeze/Export, consider offloading note scheduling from JS to standard Max objects such as
    makenote
    ,
    pipe
    ,
    flush
    , and
    midiformat
    .

AMXD / Packaging

AMXD / Packaging

  1. MUST:
    .amxd
    のバイナリ容器を書き出す場合は、生成後に最低限、期待する
    .maxpat
    / JS / 画像名が含まれていることを検査する。
  2. MUST: 依存ファイルの
    dependency_cache
    は配布環境で解決できるパスにする。ローカル絶対パスへ依存させない。
  3. MUST: リリース成果物には
    VERSION
    ,
    LICENSE
    ,
    .amxd
    ,
    .maxpat
    , JS、参照画像を含める。
  4. SHOULD: Ableton User Libraryへインストールする場合、古い同名ファイルを削除してから新しい
    .amxd
    をコピーする。
  5. MUST: ユーザーへ最終報告するとき、既存Liveインスタンスの挿し直しが必要なら明記する。
  1. MUST: After emitting the binary
    .amxd
    container, validate at minimum that it contains the expected
    .maxpat
    / JS / image names.
  2. MUST: Ensure the
    dependency_cache
    paths for dependency files can be resolved in the distribution environment. Do not rely on local absolute paths.
  3. MUST: Include
    VERSION
    ,
    LICENSE
    ,
    .amxd
    ,
    .maxpat
    , JS, and reference images in release artifacts.
  4. SHOULD: When installing into the Ableton User Library, remove the old file with the same name before copying in the new
    .amxd
    .
  5. MUST: In the final report to the user, explicitly state whether the device must be reinserted into an existing Live instance.

検証

Validation

  1. MUST: JS変更後は
    node --check <device>.js
    を実行する。
  2. SHOULD: Python生成スクリプト変更後は
    python3 -m py_compile <script>.py
    を実行する。
  3. SHOULD: 生成後に
    .maxpat
    のPresentation boundsとpatchline endpointを検査する。
  4. SHOULD:
    .amxd
    生成後に、デバイスタイプ、同梱依存、主要JS文字列が入っていることを検査する。
  5. SHOULD: Liveでの挙動確認が必要な場合は、Max Console / Open Max Windowのエラー有無を確認する。
  1. MUST: Run
    node --check <device>.js
    after changing JS.
  2. SHOULD: Run
    python3 -m py_compile <script>.py
    after changing a Python generation script.
  3. SHOULD: After generation, validate the
    .maxpat
    Presentation bounds and patchline endpoints.
  4. SHOULD: After generating an
    .amxd
    , validate its device type, bundled dependencies, and key JS strings.
  5. SHOULD: When behavior must be verified in Live, check the Max Console / Open Max Window for errors.

削減した旧スキルの扱い

Handling Legacy Skills

旧構成では、overview、maxpat format、amxd conversion、presentation layout、live api、javascript、gen、debugging、py2maxを別skillに分けていた。しかし実作業では、必要な判断が分断され、Live APIをクロックに使うなど局所知識に引っ張られるリスクがあった。
今後はこの統合スキルを入口にし、詳細な公式ドキュメントや既存実装は必要になった時点で個別に確認する。
In the previous structure, overview, maxpat format, amxd conversion, presentation layout, live api, javascript, gen, debugging, and py2max were separated into individual skills. In practice, however, the required decisions were fragmented, creating a risk that isolated knowledge would lead to problematic choices, such as using the Live API as a clock.
From now on, use this integrated skill as the entry point and consult detailed official documentation or existing implementations individually only when necessary.