m4l-project
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseM4L 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
- MUST: 生成スクリプトを正本として扱う。/
.maxpatは生成物であり、直接編集した場合も必ず生成スクリプトへ反映する。.amxd - MUST: デバイスごとに を作り、少なくとも
packages/<device>/,devices/,scripts/,assets/,releases/,DESIGN.md,VERSIONの責務を分ける。LICENSE - MUST: UI寸法、色、余白、表示ロジック、MIDI仕様、同期仕様を変えたら に記録する。
packages/<device>/DESIGN.md - SHOULD: Max patcher JSONは構造化データとして扱い、文字列置換で編集しない。
- NEVER: を
.amxdのリネームで作らない。.maxpat - NEVER: 生成物だけを直して、生成元と乖離させない。
- MUST: Treat the generation script as the source of truth. /
.maxpatare generated artifacts; even if they are edited directly, all changes must always be reflected in the generation script..amxd - MUST: Create for each device, with clear separation of responsibilities among at least
packages/<device>/,devices/,scripts/,assets/,releases/,DESIGN.md, andVERSION.LICENSE - MUST: Record changes to UI dimensions, colors, spacing, display logic, MIDI specifications, and synchronization specifications in .
packages/<device>/DESIGN.md - SHOULD: Treat Max patcher JSON as structured data rather than editing it through string replacement.
- NEVER: Create an by renaming a
.amxdfile..maxpat - NEVER: Modify only the generated artifacts and allow them to diverge from their generation sources.
Max for Live生成
Max for Live Generation
- MUST: MIDI Effectは /
midiinから入力し、notein/midioutへ出力する。noteout - MUST: Audio Effect / Instrument / MIDI Effect のデバイスタイプを決めてから、I/Oと typeを合わせる。
.amxd - MUST: MIDI Effectの は FOURCC
.amxdとmmmmを持つ。project.amxdtype = 1835887981 - MUST: は
.maxpatを持つ。openinpresentation: 1 - MUST: visible UI object は と整数
presentation: 1を持つ。presentation_rect - MUST: 全visible UI objectは かつ
x + w <= devicewidthを満たす。y + h <= 169 - SHOULD: 画像、JS、外部依存を使う は単体ロードできるように依存ファイルを同梱する。
.amxd
- MUST: MIDI Effects must receive input from /
midiinand send output tonotein/midiout.noteout - MUST: Determine whether the device is an Audio Effect, Instrument, or MIDI Effect before aligning its I/O with the type.
.amxd - MUST: An for a MIDI Effect must have the FOURCC
.amxdandmmmm.project.amxdtype = 1835887981 - MUST: A must have
.maxpat.openinpresentation: 1 - MUST: Every visible UI object must have and an integer
presentation: 1.presentation_rect - MUST: Every visible UI object must satisfy and
x + w <= devicewidth.y + h <= 169 - SHOULD: An that uses images, JS, or external dependencies must include its dependency files so that it can load independently.
.amxd
UI / Presentation
UI / Presentation
- MUST: Max for Liveデバイスの高さは 固定として設計する。
169px - MUST: UIを変更したら、Presentation boundsを機械的に検査する。
- MUST: 背景panelを使う場合は、操作UIを覆わない重なり順にする。
- SHOULD: UIはLiveテーマとの整合性を優先し、必要以上に色を上書きしない。
live.* - SHOULD: 固定サイズの入力欄、アイコン、キャンバス、ロゴは安定した を持たせ、値変更でレイアウトが動かないようにする。
presentation_rect
- MUST: Design Max for Live devices with a fixed height of .
169px - MUST: Mechanically validate Presentation bounds whenever the UI changes.
- MUST: When using a background panel, ensure its layering does not obscure the interactive UI.
- SHOULD: Prioritize consistency with the Live theme for UI elements and avoid overriding colors more than necessary.
live.* - SHOULD: Give fixed-size input fields, icons, canvases, and logos stable values so that value changes do not shift the layout.
presentation_rect
JS / MIDIロジック
JS / MIDI Logic
- MUST: 表示上のドット判定と発音判定は同じ関数、または同じデータから導出する。
- MUST: Note OnとNote Offの対応を崩さない。
- MUST: 入力MIDIを使う仕様では、入力が無いときに勝手にフォールバック音を鳴らさない。
- MUST: Randomの対象は仕様で明示された値だけに限定する。
- MUST: 「ヒットした瞬間だけ鳴る」仕様では、同じヒット範囲内にいる間に再発音しないエッジ判定を入れる。
- SHOULD: Max JSの関数名はMaxメッセージ名との対応が分かるようにする。
- SHOULD: JS は低優先度イベントであることを前提にし、Freeze/Exportで厳密なMIDIタイミングが必要な処理には慎重に使う。
Task
- MUST: The visual dot-state check and note-trigger check must use the same function or be derived from the same data.
- MUST: Preserve the correspondence between Note On and Note Off events.
- MUST: For specifications that use input MIDI, do not automatically play a fallback note when no input is present.
- MUST: Limit the scope of to values explicitly defined by the specification.
Random - 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.
- SHOULD: Make Max JS function names clearly reflect their corresponding Max message names.
- SHOULD: Treat a JS as a low-priority event and use it cautiously for processing that requires strict MIDI timing during Freeze/Export.
Task
Transport / Freeze / Export
Transport / Freeze / Export
- MUST: Live API (,
live.object,live.observer) を発音クロックとして使わない。Live APIは低優先度・非同期で、Freeze/Export中のタイミング源として信頼しない。LiveAPI - SHOULD: Transport同期が必要な場合は、Maxのtransport/tempo-relative clockなど、Live transportに同期するMax側の仕組みを使う。
- MUST: 重い処理でscheduler tickが飛んだとき、過去イベントを現在時刻にまとめて発音するcatch-up実装にしない。遅れた過去音は捨てるか、明示した別モードにする。
- MUST: 同じtransport位置・同じdegree・同じtickが複数回来ても、同じイベントを再発音しない。
- SHOULD: Freeze/Exportで問題が出る場合は、JS内の発音スケジューリングよりもMax標準オブジェクト (,
makenote,pipe,flushなど) へ逃がすことを検討する。midiformat
- MUST: Do not use the Live API (,
live.object,live.observer) 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.LiveAPI - SHOULD: When Transport synchronization is required, use a Max-side mechanism synchronized to the Live transport, such as Max's transport/tempo-relative clock.
- 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.
- MUST: Do not retrigger the same event when the same Transport position, degree, and tick occur multiple times.
- SHOULD: If problems occur during Freeze/Export, consider offloading note scheduling from JS to standard Max objects such as ,
makenote,pipe, andflush.midiformat
AMXD / Packaging
AMXD / Packaging
- MUST: のバイナリ容器を書き出す場合は、生成後に最低限、期待する
.amxd/ JS / 画像名が含まれていることを検査する。.maxpat - MUST: 依存ファイルの は配布環境で解決できるパスにする。ローカル絶対パスへ依存させない。
dependency_cache - MUST: リリース成果物には ,
VERSION,LICENSE,.amxd, JS、参照画像を含める。.maxpat - SHOULD: Ableton User Libraryへインストールする場合、古い同名ファイルを削除してから新しい をコピーする。
.amxd - MUST: ユーザーへ最終報告するとき、既存Liveインスタンスの挿し直しが必要なら明記する。
- MUST: After emitting the binary container, validate at minimum that it contains the expected
.amxd/ JS / image names..maxpat - MUST: Ensure the paths for dependency files can be resolved in the distribution environment. Do not rely on local absolute paths.
dependency_cache - MUST: Include ,
VERSION,LICENSE,.amxd, JS, and reference images in release artifacts..maxpat - SHOULD: When installing into the Ableton User Library, remove the old file with the same name before copying in the new .
.amxd - MUST: In the final report to the user, explicitly state whether the device must be reinserted into an existing Live instance.
検証
Validation
- MUST: JS変更後は を実行する。
node --check <device>.js - SHOULD: Python生成スクリプト変更後は を実行する。
python3 -m py_compile <script>.py - SHOULD: 生成後に のPresentation boundsとpatchline endpointを検査する。
.maxpat - SHOULD: 生成後に、デバイスタイプ、同梱依存、主要JS文字列が入っていることを検査する。
.amxd - SHOULD: Liveでの挙動確認が必要な場合は、Max Console / Open Max Windowのエラー有無を確認する。
- MUST: Run after changing JS.
node --check <device>.js - SHOULD: Run after changing a Python generation script.
python3 -m py_compile <script>.py - SHOULD: After generation, validate the Presentation bounds and patchline endpoints.
.maxpat - SHOULD: After generating an , validate its device type, bundled dependencies, and key JS strings.
.amxd - 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.