Node Reference

Who this is for: Ableton producers who want to know which node to use — without reading code.

What this is not: A list of every port ID. For exact port names and types, see the Node Catalog (generated).

How to use this page: Start with How to read a node entry, pick your trigger, then find building blocks or Live-object nodes for your idea. Use Workflow recipes when you want a full pattern, and Validation rules when Build fails.

How to read a node entry

Every node in Patchwright is a box on the canvas. Each entry in this reference uses the same shape so you can scan quickly.

Ports (connection points)

Run wires define order: trigger → dialog → undo group → setters and actions.

Data wires feed values into nodes that need them. Many nodes have no Run input — they only supply data (getters, math, transpose, note builders).

Settings vs wires

Each node can show settings in the inspector (numbers, text, toggles, dropdowns).

Rule: Object inputs (clip, track, song, device) must be wired. Leaving them empty causes a build error.

Node entry sections

When this reference describes a category or node, you will see:

Symbols in the A–Z index

Triggers

Every extension needs at least one When you right-click… trigger. The trigger decides:

1. Where your command appears in Live’s right-click menu
2. What object you clicked — available on the trigger’s target output

When the user picks your command, the trigger’s Run output fires and your chain begins.

Important: You can place several triggers in one project. Each trigger becomes its own menu item in Live — for example My Tools: On MIDI Clip and My Tools: On MIDI Track are two separate commands. They do not share a Run chain unless you deliberately wire them together (unusual).

Quick picker

On MIDI Clip

Connect: Wire target into every node that needs “this clip.” Wire Run into your first step (dialog, Transaction, or setter).

Mistakes: Using this trigger for audio clips — use On Audio Clip instead. Using generic clip getters for notes — use MidiClip notes get/set nodes.

On Audio Clip

Connect: target → AudioClip or Clip inputs. Run → your chain.

Mistakes: Expecting MIDI note editing — audio clips have no piano-roll notes.

On MIDI Track

Connect: target → track actions and track getters. For song-wide create track, add Song context instead of only target.

Mistakes: Using for a single clip — right-click the clip and use On MIDI Clip.

On Audio Track

Connect: target → audio track nodes. Song context when you need create/duplicate at song level.

Mistakes: Creating MIDI clips on an audio track — use On MIDI Track or create a MIDI track first.

On Clip Slot

Connect: target → ClipSlot getters and create/delete actions.

Mistakes: Confusing with On Clip-Slot Selection (multi-slot selection) — pick the one that matches how you right-click.

On Clip-Slot Selection

Connect: target → selection-specific workflows from templates or PatchAI.

Mistakes: Using when you only care about one slot — On Clip Slot is simpler.

On MIDI Arrangement Selection

Connect: target → selection-aware actions (often combined with track/clip getters).

Mistakes: Using without an actual arrangement selection — the command only appears in the right context.

On Audio Arrangement Selection

Connect: Same pattern as MIDI arrangement selection.

Mistakes: Mixing MIDI note tools into audio selection workflows.

On Scene

Connect: target → Scene getters/setters. Use Song context to create or delete scenes.

Mistakes: Expecting track-level device access — use a track trigger for that.

On Drum Rack

Connect: target → DrumRack and chain nodes. Often combined with For Each over chains.

Mistakes: Treating like a normal Instrument Rack without using chain-specific nodes.

On Simpler

Connect: target → Simpler get/action nodes. File path often comes from dialog or sandbox files.

Mistakes: Using On Sample when you meant the device in a track — On Simpler targets the device instance.

On Sample

Connect: target → Sample getters.

Mistakes: Confusing browser sample with Simpler’s loaded sample — use On Simpler for the device.

Patchwright building blocks

These categories are Patchwright’s toolbox — not Live objects. They control flow, math, music, UI, files, and the web.

Flow

Flow nodes answer: in what order should things run, and how does undo work?

Transaction (one undo step)

Branch (if/else)

For Each (bounded)

Repeat (bounded)

Delay (bounded)

Parallel (all)

Switch enum

Try / Catch

Context

Context nodes give you entry points into Live’s object model. They have no Run wire — only a value output.

Connect: Context value → obj on getters and actions that need that scope. Song → get tracks → For Each, etc.

Mistakes: Forgetting Song on create-track graphs. For Resources actions (import into project, render pre-FX audio), you must wire Resources context into the action’s obj input — the action will not guess it.

Logic

Logic nodes compute numbers, booleans, text, and lists without touching Live until you connect results to setters.

Numbers

Use for semitone offsets, color indices, bar math, progress counters.

Compare (numbers only)

Important: Equals is for numbers only. There is no string equals node. To compare text, use String includes, Slice string, or branch on dialog choices — not Equals.

Booleans

Text

Lists

JSON

Other

Mistakes: Equals on clip names — use String includes or compare Length after Slice. Filter without a real list — wire get tracks or note list first.

Notes

Notes nodes build one note or a list of notes for set MidiClip notes.

Connect: get MidiClip notes → Transpose / Quantize / Chord → set MidiClip notes. Or Note → Note List → set notes.

Mistakes: set notes replaces the entire clip — always wire the full processed list, not a partial one. Using generic Clip getters for MIDI editing — use MidiClip notes only.

Music

Music nodes understand pitch and rhythm on note lists.

Connect: Always between get MidiClip notes and set MidiClip notes (or into Note List).

Mistakes: Quantize with grid 0 — pick a sensible beat fraction. Chord without wiring Song scale getters when you want Live’s current scale — optional but common in templates.

UI

Connect: trigger Run → Show Dialog Run → Show Dialog Then → next step. Wire dialog outputs into setters or logic.

Designer: Open Designer on the toolbar (overlay on canvas, not the dock). Save a design, then pick it on the Show Dialog node.

Mistakes: Dialog inside Transaction — move before undo group. Cancel should leave Run chain without mutations (template pattern).

PatchAI keys live in the AI Assistant panel (toolbar PatchAI), not in Settings → API Secrets.

Long task

Connect: trigger Run → Progress Dialog Run; body → loop or long work. Keep outside Transaction — same rule as Show Dialog.

Mistakes: Nesting inside undo group. Never updating progress during For Each — wire step counts so the bar moves.

Web

| Node | What | When | |------|------| | HTTP Fetch | GET/POST to an HTTPS URL; returns body text and status | Lyrics API, webhook, download text |

Connect: Run chain through fetch. Wire url (must start with https://). Optional body for POST. Use Settings → API Secrets for named auth headers — not PatchAI keys.

Mistakes: http:// URLs — build fails. Storing secrets in the graph — use API Secrets. Parsing response — add Parse JSON after fetch.

Files

File nodes only touch the extension sandbox (safe storage folders).

Connect: Environment → get storageDirectory / tempDirectory → Join Path → read/write. Run through read/write nodes.

Mistakes: Absolute paths outside sandbox — build fails. .. in paths — not allowed.

Commands

Connect: Run in → Run out. Wire commandId in settings. Optional arg wire passes data to the target command.

Important: Execute Command does not require the Commands context node. Do not add Commands context unless a specific template tells you to.

Mistakes: Calling a command ID that does not exist in your extension — register both triggers first.

Live objects by producer concept

These nodes talk directly to Live. Names match what you see in the Set — Song, Track, Clip, and so on.

Song (the whole Set)

What it is: Your current Live Set — all tracks, scenes, tempo, scale, cue points.

Common getters

Common actions

When: You need “all tracks” or “add a track” — not just the one you right-clicked.

Connect: Song context → obj on every Song node. Run through actions.

Mistakes: Using target from a clip trigger when you meant song-wide — add Song context.

Tracks

What it is: A channel in the mixer — MIDI, audio, or return.

Applies to: MidiTrack, AudioTrack, and generic Track nodes where noted.

Common getters

Common setters

Common actions

When: Device chains, track mix state, slot/arrangement clip management.

Connect: target from On MIDI Track / On Audio Track, or Current Item from For Each over get tracks.

Mistakes: insertDevice name must match Live’s device name string exactly.

Clips

What it is: A region of MIDI or audio on a track — Session slot or Arrangement.

MidiClip vs AudioClip vs Clip

Common getters (any clip)

Common setters

MidiClip only

AudioClip only

When: Clip-focused tools — use On MIDI Clip or On Audio Clip and wire target.

Mistakes: Hex colors — use color index. Partial set notes — wipes other notes.

Scenes

What it is: A Session view row — launch column.

When: Scene launcher tools, set list organization.

Connect: target from On Scene, or item from get scenes loop.

Clip slots

What it is: One Session cell (track × scene).

When: “Create clip in this slot” before you have a clip to right-click.

Connect: target from On Clip Slot.

Devices

What it is: Any device on a track — instrument, audio effect, MIDI effect.

DeviceParameter nodes

When: Macro knobs, utility gain, device-specific tools.

Connect: get devices → Index or For Each → parameter chain. Often Track target or Current Item.

Mistakes: Guessing parameter index — use get parameters and pick by name in logic or settings.

Racks (Instrument / Drum / Effect)

What it is: Multi-chain devices — Drum Rack pads, rack macros.

When: Drum map tools, multi-sample racks, chain-level gain.

Connect: On Drum Rack target, or device from track’s device list.

Samples

What it is: A sample file reference — in Simpler or browser.

When: Sample swap tools, path stamping.

Connect: On Simpler or On Sample target.

Resources (project media)

What it is: Live’s project resource layer — import and render.

When: Import stems; offline bounce slice for external processing.

Connect: Resources context → obj on the action (required). Wire file path and track/time args.

Mistakes: Forgetting Resources context on obj — build error.

Cue points (locators)

get name / time, set name — locator label and position. Use with get cuePoints + For Each for set-list tools.

Take lanes, Environment & UI

Take lanes: get/set name, get clips, createMidiClip / createAudioClip — comping workflows on tracks with lanes.

Environment: get language, get storageDirectory / tempDirectory — sandbox roots for file nodes.

UI object: showModalDialog — modal web panel (URL, width, height).

Compatibility

Patchwright checks types when you wire and again at Build. Think of types as “what Live expects.”

General rules

1. Run connects to Run only.
2. More specific → more general works: MidiClip into Clip inputs.
3. General → specific does not: Clip into MidiClip inputs fails.
4. Lists need list outputs — one track is not a track list.
5. Object inputs must be wired — settings cannot replace a missing clip or track.

Quick compatibility matrix

Producer-friendly type cheat sheet

Workflow recipes

Copy these patterns as skeletons. Adjust triggers and settings for your tool.

Recipe: Read → transform → write MIDI

Goal: Change notes in the clip you right-clicked.

1. On MIDI Clip trigger.
2. target → get MidiClip notes.
3. Notes through Transpose, Quantize, Chord, or Filter as needed.
4. Run: trigger → optional Show Dialog → Transaction → set MidiClip notes.
5. Wire transformed list into set notes value.
6. target → set notes obj.

Undo: Wrap set notes (and any clip setters) in Transaction.

Fails if: Audio clip trigger; partial note list; generic Clip notes getter.

Recipe: Stamp name + color (one undo)

Goal: Rename and recolor in one command, one Cmd+Z.

1. On MIDI Clip (or On Audio Clip for audio-only name/color).
2. Run: trigger → Transaction → set name → set color.
3. target → both setters’ clip obj.
4. Name: setting or dialog wire. Color: integer color index in setting or wired number.

Undo: Both setters inside same Transaction body chain.

Fails if: Color as hex; one setter outside Transaction.

Recipe: Create track

Goal: Add a MIDI or audio track from the menu.

1. On MIDI Track or On Audio Track (or any track trigger where you test).
2. Song context → createMidiTrack or createAudioTrack obj.
3. Run: trigger → create action.
4. Optional: set name on result track inside Transaction.

Undo: Wrap create + rename in Transaction if you want one undo.

Fails if: Song unwired; clip trigger for track creation.

Recipe: Dialog-driven tool

Goal: Ask user, then act.

1. Design UI in toolbar Designer; save.
2. Run: trigger → Show Dialog → Transaction → mutations.
3. Pick design on Show Dialog node.
4. Wire dialog outputs to setters/logic (semitones, name, toggle).
5. Do not put Show Dialog inside Transaction.

Cancel: User cancel should stop before Transaction.

PatchAI: Keys in AI Assistant panel, not API Secrets (those are for HTTP Fetch).

Recipe: For each track (or device)

Goal: Same logic on every track.

1. Song → get tracks → list wire to For Each.
2. Run: trigger → optional Progress Dialog → For Each.
3. Body: Current Item → track setters/getters.
4. Progress Dialog outside Transaction.

Branching: If Branch inside loop, duplicate downstream steps — do not merge Then and Else into one Run input.

Fails if: Current Item missing; unbounded loop.

Recipe: HTTPS fetch → use response

Goal: Call an API, then use text in the Set.

1. Store API key in Settings → API Secrets if needed.
2. Run: trigger → HTTP Fetch (HTTPS URL only).
3. Parse JSON on result if response is JSON.
4. Use text in set name, file Write, or dialog message via show modal dialog.

Fails if: http:// URL; secret pasted in node settings.

Recipe: Import file into project

Goal: Pull audio or MIDI from sandbox into Live.

1. Resources context → importIntoProject obj.
2. Build path: Environment storageDirectory → Join Path → path arg.
3. Run: trigger → read path → import action.
4. Optional Progress Dialog for large files.

Fails if: Resources not wired to obj; path outside sandbox.

Recipe: Device, sample, and scene shortcuts

See manual tutorials for worked examples (scale chord arp, insert device, and others).

Validation rules (why Build fails)

Patchwright validates your graph before Live runs it. Fix the first error in the log; later errors are often knock-ons.

Wiring and objects

Colors and notes

Strings and logic

Dialogs, progress, undo

Web, files, resources

Commands

Loops and lifetime

Studio setup (not node wiring)

When stuck, paste the exact build error into PatchAI or see How to read build errors.

A–Z node index

One line per node. ⚡ = Run chain · 📖 = data only · 🔄 = async · 🎯 = trigger.

A

• Add (+) 📖 — Add two numbers.
• And (&&) 📖 — True if both booleans true.
• Application 📖 — Context: Live application; usually use Song instead.
• Application: song 📖 — Get Song from Application.

B

• Branch (if/else) ⚡ — Run Then or Else from boolean; paths do not merge.

C

• Chain: deleteDevice ⚡🔄 — Remove device from rack chain.
• Chain: devices 📖 — List devices in chain.
• Chain: duplicateDevice ⚡🔄 — Copy device in chain.
• Chain: insertDevice ⚡🔄 — Add device to chain by name.
• Chain: mixer 📖 — Chain volume/pan/sends.
• ChainMixer: panning / sends / volume 📖 — Per-chain mix parameters.
• Chord (scale-aware) 📖 — Build chord or arp note list from root + intervals.
• Chord/Arp Mode 📖 — Pick chord or arpeggio notes from mode.
• Clip: color / duration / endMarker / endTime / loopEnd / looping / loopStart / muted / name / startMarker / startTime 📖 — Read clip properties.
• Clip: set color / set looping / set muted / set name ⚡ — Write clip properties; color is index.
• ClipSlot: clip 📖 — Clip in slot or empty.
• ClipSlot: createAudioClip / createMidiClip / deleteClip ⚡🔄 — Slot clip lifecycle.
• Commands 📖 — Context: command registry (rarely needed).
• Concat strings 📖 — Join two strings.
• CuePoint: name / time 📖 — Locator label and position.
• CuePoint: set name ⚡ — Rename locator.
• Current Item 📖 — Item from enclosing For Each.

D

• DataModelObject: parent 📖 — Parent object in Live tree.
• Delay (bounded) ⚡🔄 — Wait milliseconds on Run chain.
• Device: name / parameters 📖 — Device title and knobs.
• DeviceParameter: defaultValue / isQuantized / max / min / name / valueItems 📖 — Parameter metadata.
• DeviceParameter: getValue / setValue ⚡🔄 — Read or write parameter.
• Divide (÷) 📖 — Divide two numbers.
• DrumChain: receivingNote / set receivingNote 📖⚡ — MIDI note for drum pad.
• DrumRack: chains 📖 — Pads/chains in drum rack.

E

• Environment 📖 — Context: language and sandbox folders.
• Environment: language / storageDirectory / tempDirectory 📖 — Locale and paths.
• Equals (=) 📖 — Numbers equal (not strings).
• Execute Command ⚡ — Run another command by id; no Commands context required.

F

• Filter 📖 — Subset list by condition.
• For Each (bounded) ⚡ — Run body per list item; use Current Item.

G

• Greater (>) 📖 — Number comparison.

H

• HTTP Fetch ⚡🔄 — HTTPS request; returns body and status.

I

• Index ([i]) 📖 — List item at index.

J

• Join Path 📖 — Combine sandbox path segments.
• JSON get key 📖 — Read object field.
• JSON Parse / Stringify JSON 📖 — Text ↔ JSON.

L

• Length 📖 — List length or string length.
• Less (<) 📖 — Number comparison.

M

• Map 📖 — Transform each list item.
• MidiClip: notes / set notes 📖⚡ — Read or replace all MIDI notes.
• MidiTrack: createMidiClip ⚡🔄 — New MIDI clip in arrangement.
• Modulo (%) 📖 — Remainder.
• Multiply (×) 📖 — Multiply numbers.

N

• Not (!) 📖 — Boolean negation.
• Note 📖 — Build one NoteDescription.
• Note List 📖 — Collect notes for set notes.
• Nullish coalesce 📖 — Default when value empty.

O

• On Audio Arrangement Selection 🎯 — Trigger: audio arrangement time selection.
• On Audio Clip 🎯 — Trigger: audio clip menu.
• On Audio Track 🎯 — Trigger: audio track menu.
• On Clip Slot 🎯 — Trigger: session slot.
• On Clip-Slot Selection 🎯 — Trigger: multi-slot selection.
• On Drum Rack 🎯 — Trigger: drum rack device.
• On MIDI Arrangement Selection 🎯 — Trigger: MIDI arrangement selection.
• On MIDI Clip 🎯 — Trigger: MIDI clip menu.
• On MIDI Track 🎯 — Trigger: MIDI track menu.
• On Sample 🎯 — Trigger: browser sample.
• On Scene 🎯 — Trigger: scene row.
• On Simpler 🎯 — Trigger: Simpler device.

P

• Parallel (all) ⚡🔄 — Two Run branches concurrently.
• Pick keys 📖 — Keep selected JSON keys.
• Pitch class → MIDI 📖 — Convert Live pitch class (0–11) to MIDI pitch number.
• Progress Dialog ⚡🔄 — Progress UI; keep outside Transaction.

Q

• Quantize 📖 — Snap note starts to grid.

R

• RackDevice: chains / insertChain 📖⚡🔄 — Rack chain list or add chain.
• Read Text File ⚡🔄 — Read sandbox text file.
• Repeat (bounded) ⚡ — Fixed-repeat loop body.
• Replace string 📖 — Text find/replace.
• Resources 📖 — Context: import and render.
• Resources: importIntoProject / renderPreFxAudio ⚡🔄 — Import file or bounce slice; wire Resources obj.

S

• Sample: filePath 📖 — Path to sample file.
• Scene: name / signatureNumerator / signatureDenominator / tempo 📖 — Scene metadata.
• Scene: set name ⚡ — Rename scene.
• Show Dialog ⚡🔄 — Designed dialog; toolbar Designer.
• Simpler: replaceSample / sample 📖⚡🔄 — Swap or read Simpler sample.
• Slice string 📖 — Substring by index range.
• Song (current Set) 📖 — Context: whole Set.
• Song: createAudioTrack / createMidiTrack / createScene / createCuePoint ⚡🔄 — Add tracks, scenes, locators.
• Song: cuePoints / gridIsTriplet / gridQuantization / mainTrack / returnTracks / rootNote / scaleIntervals / scaleMode / scaleName / scenes / tempo / tracks 📖 — Set-wide reads.
• Song: deleteCuePoint / deleteScene / deleteTrack / duplicateScene / duplicateTrack ⚡🔄 — Remove or duplicate.
• Song: set tempo ⚡ — Change tempo.
• Split string 📖 — Split to list by separator.
• String includes 📖 — True if substring found.
• Subtract (−) 📖 — Subtract numbers.
• Switch enum ⚡ — Branch on string match.

T

• TakeLane: clips / name / set name / createAudioClip / createMidiClip 📖⚡🔄 — Comping lanes.
• To lower case / To upper case 📖 — Change string case.
• Track: arm / arrangementClips / clipSlots / devices / groupTrack / mixer / mute / mutedViaSolo / name / solo / takeLanes 📖 — Track state reads.
• Track: set arm / set mute / set name / set solo ⚡ — Track toggles and rename.
• Track: clearClipsInRange / createTakeLane / deleteClip / deleteDevice / duplicateDevice / insertDevice ⚡🔄 — Track mutations.
• TrackMixer: panning / sends / volume 📖 — Track mix parameters.
• Transaction (one undo step) ⚡ — Undo group; body chain only.
• Transpose 📖 — Shift note pitches by semitones.
• Trim string 📖 — Strip whitespace.
• Try / Catch ⚡ — Run catch chain on error.

U

• UI 📖 — Context: Live UI object.
• Ui: showModalDialog ⚡🔄 — Modal web panel.

W

• Write File ⚡🔄 — Write text to sandbox.

≤ ≥

• ≤ / ≥ 📖 — Less-or-equal / greater-or-equal numbers.

See also

• Node Catalog (generated) — every port ID and SDK type
• Core Concepts — Run vs data, undo, branching
• How-To Guides — step-by-step tasks
• Glossary — Patchwright terms
• Troubleshooting — when Live and Patchwright disagree

Node Reference v1.0 · Patchwright 0.1.0 · June 2026