Tool Reference

Every Producer Pal tool and its parameters. For what Producer Pal can do in plain terms, start with Features.

The AI picks these tools and fills in the parameters itself — you don't call them by hand. Read this when you want to know exactly what a tool accepts, or when you're driving Producer Pal from the REST API or the Agent Skill.

About the example output

Every tool shows one example call and what it returns. They all run against the same made-up Live Set — three tracks (Drums, Bass, Vocals), one return, two scenes — so the names, IDs, colors, and file paths are invented. IDs are opaque in real Live Sets too: read one from a tool result, don't guess it.

The examples are pretty-printed here. Producer Pal sends a more compact form over the wire by default; ?format=json on the REST API gives you this shape.

Core Tools

🔧 Connect (`ppal-connect`)

Summarizes the state of the current Live Set
Returns a skill set and context that teach the AI how to use Producer Pal effectively. Standard skills cover the full feature set. Small model mode provides simplified skills and schemas for less capable models.
Call it first when a model is driving Producer Pal — that's how the AI learns the notation and conventions. A plain REST script can skip it.

(no parameters)

Example output

Called with {}:

json

{
  "connected": true,
  "producerPalVersion": "2.2.0",
  "abletonLiveVersion": "12.4.1",
  "liveSet": {
    "name": "Example Set",
    "tempo": 110,
    "timeSignature": "4/4",
    "sceneCount": 2,
    "regularTrackCount": 3,
    "returnTrackCount": 1,
    "isPlaying": true,
    "scale": "F Minor",
    "scalePitches": "F,G,Ab,Bb,C,Db,Eb"
  }
}

The response carries these as separate text blocks after the JSON, in this order — ppal-connect does not return them as fields on the result. What goes in them is up to you: see Context & Memory and Customizing Skills.

# Producer Pal Skills

## Positions & Meter
… 339 more lines

Project context (this Live Set):

Downtempo sketch in F minor. Keep the drums sparse.

Global context (all projects):

I write downtempo and lo-fi house. Keep arrangements under 3 minutes.

Memory index — load a body with ppal-context (action:"read", scope:"memory", name:"<name>"):

- `prefers-hardware-drums` — Records drums on hardware, wants MIDI kept out of the kick bus

Report the connection status and Live Set overview to the user, then wait for their instructions.

🔧 Context (`ppal-context`)

Read and write the three context layers: project context (notes about this Live Set), global context (preferences that apply to every project), and memory (facts AI records about you as you work)

Parameters

Parameter	Type	Description
`action`	`"read"` \| `"write"` \| `"delete"` 🐘	read (default): project/global → the document; memory → the entry named `name`, or the whole index if no `name`. write: replace the document, or create/update the memory entry `name`. delete: remove the memory entry `name`.
`scope`	`"project"` \| `"global"` \| `"memory"` 🐘	project (default): facts about THIS Live Set (genre, song structure), always in its context. global: who the user is across ALL projects (style, preferences, high-level goals), always in context. memory: durable facts and rules that matter only in CERTAIN situations, loaded on demand by name.
`content`	string	Text to write — project/global: the whole document; memory: the entry body (one fact). Max 10000 chars.
`name` 🐘	string	Memory entry name (read/write/delete on scope:memory). Reuse a name to update, not duplicate.
`description` 🐘	string	Memory entry's one-line recall hook for the index — what's inside and when it's relevant. Required on a memory write.
`force`	boolean	Only when a write was skipped for dropping the whole document: true replaces it anyway.

🐘 = large model only (hidden in small model mode)

Example output

Called with {"action":"read"}:

json

{
  "content": "Downtempo sketch in F minor. Keep the drums sparse."
}

Session Tools

🔧 Playback (`ppal-playback`)

Start/stop playback in Session or Arrangement view
Play specific scenes or clips
Set loop points and playback position
Jump to arrangement locators by ID or name
Set loop start/end using locators
Playback always follows the Arrangement (no per-track override)
Stop all clips or specific clips

Parameters

Parameter	Type	Description
`action`	`"play-arrangement"` \| `"update-arrangement"` \| `"play-scene"` \| `"play-session-clips"` \| `"stop-session-clips"` \| `"stop-all-session-clips"` \| `"stop"` (required)	play-arrangement: from startTime update-arrangement: set playhead/loop without playing play-scene: all clips in scene play-session-clips: by id(s) or path(s) stop-session-clips: by id(s) or path(s) stop-all-session-clips: all stop: session and arrangement
`startTime`	string	bar\|beat position in arrangement (song meter)
`startLocator` 🐘	string	locator ID or name for start position (e.g., locator-0 or Verse)
`loop`	boolean	arrangement loop?
`loopStart`	string	bar\|beat position (song meter)
`loopStartLocator` 🐘	string	locator ID or name for loop start
`loopEnd`	string	bar\|beat position (song meter)
`loopEndLocator` 🐘	string	locator ID or name for loop end
`id`	string	clip ID(s), comma-separated for multiple; for play-scene, a scene ID (or a clip ID in that scene)
`path`	string	clip slot(s) 't<track>/s<scene>', both 0-based, comma-separated (e.g., 't0/s1' or 't0/s1,t2/s3'); for play-scene, a scene 's<scene>' (e.g., 's3') or any position in it
`sceneIndex`	integer	0-based scene index for play-scene (or use path 's<scene>')

🐘 = large model only (hidden in small model mode)

Example output

Called with {"action":"play-scene","sceneIndex":0}:

json

{
  "playing": true,
  "currentTime": "5|1",
  "sceneIndex": 0,
  "sceneName": "Intro",
  "arrangementLoop": {
    "start": "1|1",
    "end": "9|1"
  }
}

🔧 Library (`ppal-library`)

Requires Live 12.4+

The library tools require Ableton Live 12.4 or later. On older versions they return an error explaining the requirement. Use the version of Max bundled with Live, or make sure your standalone Max is up to date. See Troubleshooting for details.

Search Live's browser library by name, tags, content kind, device kind, or source category (User Library, Pack, Built-in, Cloud, Plugin, or your sample folder)
Also includes the user-configured sample folder when set, with results merged and de-duplicated against Live's library
Sort by use_count (Live's persistent usage counter — surfaces what you actually use most), mod_date, or name
Enumerate available tags with action: "listTags" so the AI can discover the tag vocabulary on your machine, or browse Live's category taxonomy (Sounds, Drums, Genres, …) with action: "listCategories"
Run many filtered searches in one call with action: "searchBatch" — results grouped per query, so the AI can assemble a whole drum kit in one round trip
List the VST/VST3/AU plug-ins Live knows about with action: "listPlugins" (filter by query, vendor, format, device kind, or subcategory)
Rank samples by audio similarity to a seed sample with action: "findSimilar" — Live's own similarity index, not Producer Pal listening — or group library samples with identical audio (re-shipped duplicates) with action: "findDuplicates" — both can be narrowed with the search filters

Parameters

Parameter	Type	Description
`action`	`"search"` \| `"listTags"` \| `"listCategories"` 🐘 \| `"searchBatch"` 🐘 \| `"listPlugins"` 🐘 \| `"findSimilar"` 🐘 \| `"findDuplicates"` 🐘	search: filter library items (default) \| listTags: enumerate available tags \| listCategories: browse Live's category taxonomy (Sounds, Drums, Genres, …); pass category to drill into its tags \| searchBatch: run many filtered searches in one call (e.g. build a drum kit), results grouped per query \| listPlugins: list installed VST/VST3/AU plugins Live knows about (filter with query, vendor, format, deviceKind, subcategory) \| findSimilar: rank samples by audio similarity to a seed sample (similarTo); combine with the search filters to constrain candidates \| findDuplicates: group library samples with identical audio (re-shipped duplicates), scoped by the search filters
`queries` 🐘	array	searchBatch only: array of query objects, each with the same filters as a single search (query, tags, kind, type, deviceKind, source, inFolder, sort, limit, verifyPaths) plus an optional label; results are returned in order, grouped per query (capped at 20)
`query`	string	name substring (search: supports * as a multi-character wildcard, e.g. kick*acoustic; listPlugins: plain case-insensitive substring)
`tags`	string	comma-separated tag names; results must match ALL listed tags (search only)
`kind`	`"audio"` \| `"midi"` \| `"live-clip"` 🐘 \| `"preset"` \| `"device-group"` \| `"m4l-device"` 🐘 \| `"live-set"` 🐘 \| `"plugin"` 🐘 \| `"image"` 🐘 \| `"video"` 🐘 \| `"folder"` 🐘	content kind filter (search only; default: audio — the only kind loadable into clips/Simpler today, others are discovery-only). audio=.wav/.aif/.mp3/etc. samples \| midi=.mid files PLUS MIDI Live clips (.alc), so it covers all MIDI content — the right kind for melody/chord ideas \| live-clip=all .alc Ableton clips (MIDI+audio; each result reports subtype) \| preset=instrument/effect presets \| device-group=.adg device chains (racks) \| m4l-device=.amxd Max for Live devices \| live-set=.als project files \| plugin=VST/AU specs and presets \| image/video=media assets \| folder=directory entries (a DB row type, distinct from source:sampleFolder)
`type`	`"loop"` \| `"oneshot"` \| `"impulse-response"`	playback type filter (search only): loop=loops \| oneshot=one-shots (e.g. a kick) \| impulse-response=convolution IRs. Prefer oneshot for hits and loop for grooves. Also reported per result as `type`.
`category` 🐘	string	listCategories only: a top-level category name (from listCategories with no category) to drill into; returns its tag names, each usable as a tags filter
`similarTo` 🐘	string	findSimilar only: absolute path of a seed sample (e.g. a path from a prior search) to rank other samples by audio similarity. Combine with the search filters to constrain candidates — e.g. similarTo a kick + tags=Kick for 'more kicks like this one'. Each result carries a `similarity` score (-1 to 1, ~1 = very similar).
`deviceKind` 🐘	`"instrument"` \| `"audiofx"` \| `"midifx"`	device classification filter (search + listPlugins; for listPlugins only instrument/audiofx apply)
`vendor` 🐘	string	vendor/manufacturer substring, case-insensitive (listPlugins only)
`format` 🐘	`"VST"` \| `"VST3"` \| `"AU"`	plugin binary format filter (listPlugins only)
`subcategory` 🐘	string	subcategory substring filter, case-insensitive (listPlugins only; matches any of a plugin's genre/role tags, e.g. reverb, delay, synth). Also reported per result as `subcategories`.
`source`	`"sampleFolder"` \| `"user"` \| `"pack"` \| `"builtin"` \| `"cloud"` \| `"plugin"`	where the file lives (search only). sampleFolder=user-configured sample folder on disk (bypasses Live's DB) \| user=your User Library \| pack=installed Packs (factory + 3rd-party) \| builtin=Ableton's Core Library \| cloud=Cloud-stored items \| plugin=installed VST/AU/etc. plugins
`inFolder`	string	absolute folder path; returns only immediate children of that folder (search only). Composes with other filters. Case-insensitive (ASCII). Unresolvable paths return no results with a `reason` explaining the path wasn't found.
`sort` 🐘	`"use_count"` \| `"mod_date"` \| `"name"`	sort order (search only); defaults to use_count desc
`verifyPaths` 🐘	boolean	search only: stat each result's path and add pathExists (true/false) so you can skip files moved/deleted since Live last indexed. Off by default (one filesystem check per result).
`limit`	number	max results; defaults to 50 (search) or 200 (listTags)

🐘 = large model only (hidden in small model mode)

Example output

Called with {"query":"kick","limit":2}:

json

{
  "dbAvailable": true,
  "items": [
    {
      "name": "Kick Deep 01.wav",
      "path": "/Users/example/Music/Ableton/Factory Packs/Kick Deep 01.wav",
      "kind": "sample",
      "type": "oneshot",
      "tags": [
        "Kick",
        "Drums"
      ],
      "useCount": 12,
      "source": "builtin",
      "parentFolder": "One Shots"
    },
    {
      "name": "Bass Sub.adg",
      "path": "/Users/example/Music/Ableton/User Library/Bass Sub.adg",
      "kind": "instrument-rack",
      "tags": [
        "Bass"
      ],
      "useCount": 3,
      "source": "user",
      "parentFolder": "Instruments"
    }
  ]
}

🔧 Select (`ppal-select`)

Read current selection and view state (when no arguments)
- Returns only non-null fields: selected track, scene, clip, device
- Rich object shapes with IDs, types, and context (path, etc.)
Update selection and return only relevant fields
- Select any object by ID (auto-detects track/scene/clip/device)
- Select tracks by index/category, scenes by index
- Select by path: a clip slot (e.g., t0/s3), a track (t0), a return track (rt0), the master track (mt), a scene (s3), or a device (e.g., t0/d1)
- Switch between Session and Arrangement views
- Auto-switches to session view for scene/clipSlot selection
- Detail views auto-managed: clip detail opens on clip selection, device detail on device selection

Parameters

Parameter	Type	Description
`id`	string	select by ID (auto-detects track/scene/clip/device/chain/drum pad)
`trackIndex`	integer	0-based track index
`trackType`	`"return"` \| `"master"`	omit for audio/midi tracks, or: return, master
`sceneIndex`	integer	0-based scene index
`path`	string	select by path, 0-based: 't0/s3' a clip slot, 't0' a track, 'rt0' a return track, 'mt' the master track, 's3' a scene, 't0/d1' a device, 't0/d0/c1' a rack chain, 't0/d0/pC1' a drum pad
`openPluginWindow` 🐘	boolean	open (true) or close (false) a plug-in's (VST/AU) floating editor window; targets the device given by id or path
`view`	`"session"` \| `"arrangement"`	main view

🐘 = large model only (hidden in small model mode)

Example output

Called with {"path":"t0/s0"}:

json

{
  "view": "session",
  "selectedClip": {
    "id": "301",
    "path": "t0/s0"
  }
}

Action Tools

🔧 Delete (`ppal-delete`)

Remove tracks, return tracks, scenes, clips, devices, or drum pads
Bulk delete multiple objects

Parameters

Parameter	Type	Description
`id`	string	ID(s) to delete, comma-separated for multiple (must be same type)
`path`	string	path(s) to delete, comma-separated for multiple: session clips ('t0/s1'), devices ('t0/d1'), drum pads ('t1/d0/pC1'), one layer of a pad ('t1/d0/pC1/c1')
`type`	`"track"` \| `"scene"` \| `"clip"` \| `"device"` \| `"drum-pad"` \| `"chain"` (required)	type of objects to delete; 'chain' removes one chain from a Drum Rack pad

Example output

Called with {"id":"303","type":"clip"}:

json

{
  "id": "303",
  "type": "clip",
  "deleted": false
}

Warning appended to the result: delete: clip "303" still exists, so Live did not delete it

🔧 Duplicate (`ppal-duplicate`)

Copy tracks, scenes, clips, devices, or drum pads
Create multiple copies at once
Copy clips anywhere in the Session, Arrangement, or from Session to Arrangement
- Position in the Arrangement by bar|beat or locator
- Auto-tile clips to fill longer arrangement durations
Apply transforms to each duplicated clip (e.g. transpose copies, vary velocities) without a separate update step
Stack MIDI variations on take lanes with toPath: "t2/l+,t2/l+" + transforms — one lane per l+, auditioned at the same arrangement position
Copy devices to any track, return track, or rack chain
Copy a whole drum pad to another pad in the same rack, bringing its chain trim, pan, sends, choke group, and devices — a device-only copy leaves the chain (and its trim) behind
Route duplicated tracks to source instrument for MIDI layering

Note: Return tracks and devices on return tracks cannot be duplicated (Live API limitation).

Parameters

Parameter	Type	Description
`id`	string	id of the object to duplicate
`path`	string	source drum pad path instead of id, e.g. 't0/d0/pC1' (drum pads only)
`type`	`"track"` \| `"scene"` \| `"clip"` \| `"device"` \| `"drum-pad"` (required)	type of object to duplicate
`name`	string	name (comma-separated when duplicating multiple)
`color`	string	#RRGGBB (comma-separated when duplicating multiple, cycles)
`count` 🐘	integer	number of copies (tracks/scenes only, ignored for clips/devices)
`withoutClips` 🐘	boolean	exclude clips?
`withoutDevices` 🐘	boolean	exclude devices?
`arrangementStart`	string	arrangement bar\|beat position(s) for clips/scenes, comma-separated for multiple (e.g., '1\|1' or '1\|1,2\|1,3\|1'). Song meter
`locator` 🐘	string	arrangement locator ID(s) or name(s), comma-separated for multiple (e.g., 'locator-0' or 'Verse' or 'locator-0,Chorus')
`arrangementLength`	string	duration: Nbar (e.g., '4bar'), n<fraction> note value (e.g., 'n/4'), or Nbar+n<fraction> (e.g., '1bar+n/4'); song meter. Shorter than the source trims the copy; longer tiles copies to fill the span (many clips, not one) — for a single clip use ppal-update-clip with looping false and notes for the full length
`toPath`	string	destination(s), comma-separated for multiple. Clips: 't2/s1' = clip slot (track 2, scene 1), 't2' = track 2's arrangement (needs arrangementStart or locator, and a track matching the clip's MIDI/audio type), 't2/l0' = its first take lane and 't2/l+' appends a fresh one (MIDI only); omit for the source clip's own track. Devices: 't1/d0'. Drum pads: 't0/d0/pD1', required, and must be in the same rack as the source pad (id or path names the source). Cycles against arrangementStart when the lists differ in length
`routeToSource` 🐘	boolean	tracks only (errors otherwise): the copy gets no clips or devices of its own and plays the source track's instrument (for MIDI layering/polyrhythms)
`transforms` 🐘	string	transform expressions (broadcast across copies; clips only); newline-separated for multiple. Use clip.index / clipseq() for per-copy variation
`takeLaneName` 🐘	string	name for a take lane this call creates (toPath 't<track>/l+')

🐘 = large model only (hidden in small model mode)

Example output

Called with {"type":"clip","id":"301","toPath":"t0/s1"}:

json

{
  "id": "603",
  "path": "t0/s1"
}

Live Set Tools

🔧 Read Live Set (`ppal-read-live-set`)

Get complete Live project overview
View all tracks and scenes at once, with a clip count per track (clip contents come from Read Track, Read Scene, and Read Clip)
See tempo, time signature, and scale settings
View arrangement locators with times and names
Check what's playing and track states

Parameters

Parameter	Type	Description
`include`	array of: `"tracks"` \| `"scenes"` \| `"routings"` 🐘 \| `"mixer"` \| `"color"` \| `"locators"` 🐘 \| `"*"` 🐘	tracks, scenes = lists. routings, mixer, color = detail (use with tracks/scenes). locators = arrangement markers. "*" = all

🐘 = large model only (hidden in small model mode)

Example output

Called with {"include":["*"]}:

json

{
  "name": "Example Set",
  "tempo": 110,
  "timeSignature": "4/4",
  "scenes": [
    {
      "id": "201",
      "name": "Intro",
      "sceneIndex": 0,
      "color": "#FF4C4C",
      "clipCount": 1
    },
    {
      "id": "202",
      "name": "Verse",
      "sceneIndex": 1,
      "color": "#B87A35",
      "tempo": 96,
      "timeSignature": "6/8",
      "clipCount": 2
    }
  ],
  "isPlaying": true,
  "tracks": [
    {
      "id": "101",
      "type": "midi",
      "name": "Drums",
      "color": "#FF4C4C",
      "isArmed": true,
      "instrument": "Drum Rack",
      "gainDb": "0.0 dB",
      "pan": 0,
      "sends": [
        {
          "gainDb": "-inf dB",
          "return": "A Reverb"
        }
      ],
      "trackIndex": 0,
      "sessionClipCount": 1,
      "arrangementClipCount": 0,
      "deviceCount": 1,
      "playingSlotIndex": 0,
      "inputRoutingType": {
        "name": "Ext. In",
        "inputId": "17"
      },
      "inputRoutingChannel": {
        "name": "In 1",
        "inputId": "1"
      },
      "outputRoutingType": {
        "name": "Track Out",
        "outputId": "25"
      },
      "outputRoutingChannel": {
        "name": "Master",
        "outputId": "26"
      },
      "monitoringState": "auto"
    },
    {
      "id": "102",
      "type": "midi",
      "name": "Bass",
      "color": "#B87A35",
      "instrument": "Analog",
      "gainDb": "-3.0 dB",
      "pan": -0.25,
      "sends": [
        {
          "gainDb": "-12.0 dB",
          "return": "A Reverb"
        }
      ],
      "trackIndex": 1,
      "sessionClipCount": 1,
      "arrangementClipCount": 1,
      "takeLaneCount": 2,
      "deviceCount": 2,
      "inputRoutingType": {
        "name": "Ext. In",
        "inputId": "17"
      },
      "inputRoutingChannel": {
        "name": "In 1",
        "inputId": "1"
      },
      "outputRoutingType": {
        "name": "Track Out",
        "outputId": "25"
      },
      "outputRoutingChannel": {
        "name": "Master",
        "outputId": "26"
      },
      "monitoringState": "auto"
    },
    {
      "id": "103",
      "type": "audio",
      "name": "Vocals",
      "color": "#3DC300",
      "gainDb": "-6.0 dB",
      "pan": 0.5,
      "sends": [
        {
          "gainDb": "-6.0 dB",
          "return": "A Reverb"
        }
      ],
      "trackIndex": 2,
      "sessionClipCount": 1,
      "arrangementClipCount": 0,
      "deviceCount": 0,
      "state": "muted",
      "inputRoutingType": {
        "name": "Ext. In",
        "inputId": "17"
      },
      "inputRoutingChannel": {
        "name": "In 1",
        "inputId": "1"
      },
      "outputRoutingType": {
        "name": "Track Out",
        "outputId": "25"
      },
      "outputRoutingChannel": {
        "name": "Master",
        "outputId": "26"
      },
      "monitoringState": "auto"
    }
  ],
  "returnTracks": [
    {
      "id": "104",
      "type": "return",
      "name": "A Reverb",
      "color": "#7F7F7F",
      "gainDb": "0.0 dB",
      "pan": 0,
      "returnTrackIndex": 0,
      "sessionClipCount": 0,
      "arrangementClipCount": 0,
      "deviceCount": 0,
      "inputRoutingType": null,
      "inputRoutingChannel": null,
      "outputRoutingType": {
        "name": "Track Out",
        "outputId": "25"
      },
      "outputRoutingChannel": {
        "name": "Master",
        "outputId": "26"
      }
    }
  ],
  "masterTrack": {
    "id": "105",
    "type": "master",
    "name": "Master",
    "color": "#7F7F7F",
    "gainDb": "0.0 dB",
    "pan": 0,
    "sessionClipCount": 0,
    "arrangementClipCount": 0,
    "deviceCount": 0,
    "inputRoutingType": null,
    "inputRoutingChannel": null,
    "outputRoutingType": null,
    "outputRoutingChannel": null
  },
  "scale": "F Minor",
  "scalePitches": "F,G,Ab,Bb,C,Db,Eb",
  "locators": [
    {
      "id": "locator-0",
      "name": "Intro",
      "time": "1|1"
    },
    {
      "id": "locator-1",
      "name": "Verse",
      "time": "9|1"
    }
  ]
}

🔧 Update Live Set (`ppal-update-live-set`)

Change tempo, time signature, scale
Create, rename, or delete arrangement locators

Parameters

Parameter	Type	Description
`tempo`	number	BPM
`timeSignature`	string	N/D (4/4)
`scale`	string	"Root ScaleName" ("C Major", "F# Minor", "Bb Dorian"). Empty string disables scale
`locatorOperation` 🐘	`"create"` \| `"delete"` \| `"rename"`	Locator operation
`locatorId` 🐘	string	Locator ID for delete/rename (e.g. locator-0). Positional — shifts if locators are added/removed, so prefer locatorTime or locatorName
`locatorTime` 🐘	string	Bar\|beat position, song meter (required for create, alt ID for delete/rename)
`locatorName` 🐘	string	Name for create/rename, or name-match filter for delete

🐘 = large model only (hidden in small model mode)

Example output

Called with {"tempo":124,"scale":"F Minor"}:

json

{
  "id": "1",
  "tempo": 124,
  "scale": "F Minor",
  "$meta": [
    "Scale applied to selected clips and defaults for new clips."
  ],
  "scalePitches": [
    "F",
    "G",
    "Ab",
    "Bb",
    "C",
    "Db",
    "Eb"
  ]
}

Track Tools

🔧 Create Track (`ppal-create-track`)

Add MIDI, audio, or return tracks
Position tracks exactly where you want
Set initial mute/solo/arm states

Parameters

Parameter	Type	Description
`trackIndex`	integer	0-based index, -1 or omit to append
`count` 🐘	integer	number to create
`name`	string	name for all, or comma-separated for each
`color`	string	#RRGGBB for all, or comma-separated for each (cycles if fewer than count)
`type`	`"midi"` \| `"audio"` \| `"return"`	type
`mute` 🐘	boolean	muted?
`solo` 🐘	boolean	soloed?
`arm` 🐘	boolean	record armed?

🐘 = large model only (hidden in small model mode)

Example output

Called with {"trackIndex":3,"name":"Keys"}:

json

{
  "id": "601",
  "trackIndex": 3
}

🔧 Read Track (`ppal-read-track`)

Get detailed track information
View all clips in Session and Arrangement
List take lanes and their clips (with the arrangement-clips include)
See devices, routing options, and drum pad mappings
Check track states (muted, soloed, armed)
View mixer properties: gain, pan, panning mode, and send levels

Parameters

Parameter	Type	Description
`id`	string	provide this or trackType/trackIndex
`trackType`	`"return"` \| `"master"`	return or master (omit for audio/midi tracks, which have independent trackIndexes)
`trackIndex`	integer	0-based index
`include`	array of: `"session-clips"` \| `"arrangement-clips"` \| `"notes"` \| `"timing"` \| `"sample"` \| `"devices"` \| `"drum-map"` \| `"routings"` 🐘 \| `"available-routings"` 🐘 \| `"mixer"` \| `"color"` \| `"*"` 🐘	session-clips, arrangement-clips = clip lists (arrangement-clips also lists take lanes). notes, timing, sample = clip detail (use with clips). devices, routings, available-routings, mixer = track data. drum-map = the kit's actual pad pitches and names; read it before writing drums. color = track + clip color. "*" = all

🐘 = large model only (hidden in small model mode)

Example output

Called with {"trackIndex":0,"include":["*"]}:

json

{
  "id": "101",
  "type": "midi",
  "name": "Drums",
  "color": "#FF4C4C",
  "isArmed": true,
  "instrument": "Drum Rack",
  "gainDb": "0.0 dB",
  "pan": 0,
  "sends": [
    {
      "gainDb": "-inf dB",
      "return": "A Reverb"
    }
  ],
  "trackIndex": 0,
  "sessionClips": [
    {
      "id": "301",
      "name": "Kick + Hats",
      "color": "#FF4C4C",
      "playing": true,
      "path": "t0/s0",
      "timeSignature": "4/4",
      "looping": true,
      "start": "1|1",
      "end": "2|1",
      "length": "1bar",
      "notes": "v110 n/16 C1 1|1 v100 C1 1|2,4\nv70 Gb1 1|1.5x4@n/4\nv105 D1 1|3"
    }
  ],
  "arrangementClips": [],
  "devices": [
    {
      "id": "401",
      "path": "t0/d0",
      "type": "drum-rack",
      "name": "Kit"
    }
  ],
  "drumMap": {
    "C1": "Kick",
    "D1": "Snare"
  },
  "playingSlotIndex": 0,
  "inputRoutingType": {
    "name": "Ext. In",
    "inputId": "17"
  },
  "inputRoutingChannel": {
    "name": "In 1",
    "inputId": "1"
  },
  "outputRoutingType": {
    "name": "Track Out",
    "outputId": "25"
  },
  "outputRoutingChannel": {
    "name": "Master",
    "outputId": "26"
  },
  "monitoringState": "auto",
  "availableInputRoutingTypes": [
    {
      "name": "Ext. In",
      "inputId": "17"
    }
  ],
  "availableInputRoutingChannels": [
    {
      "name": "In 1",
      "inputId": "1"
    }
  ],
  "availableOutputRoutingTypes": [
    {
      "name": "Track Out",
      "outputId": "25"
    }
  ],
  "availableOutputRoutingChannels": [
    {
      "name": "Master",
      "outputId": "26"
    }
  ]
}

🔧 Update Track (`ppal-update-track`)

Change track gain (volume), panning, and send levels
Change mute, solo, arm, I/O routings, and monitoring state
Change track name and color
Update multiple tracks at once

Parameters

Parameter	Type	Description
`id`	string	track ID(s) to update, comma-separated for multiple
`name`	string	name for all, or comma-separated for each (extras keep existing name), ideally unique
`color`	string	#RRGGBB for all, or comma-separated for each (cycles if fewer than the tracks)
`gainDb`	number	track gain in dB
`pan`	number	pan: -1 (left) to 1 (right)
`panningMode` 🐘	`"stereo"` \| `"split"`	panning mode: stereo or split
`leftPan` 🐘	number	left channel pan in split mode (-1 to 1)
`rightPan` 🐘	number	right channel pan in split mode (-1 to 1)
`mute`	boolean	muted?
`solo`	boolean	soloed?
`arm`	boolean	record armed?
`inputRoutingTypeId` 🐘	string	from availableInputRoutingTypes, set before channel
`inputRoutingChannelId` 🐘	string	from availableInputRoutingChannels
`outputRoutingTypeId` 🐘	string	from availableOutputRoutingTypes, set before channel
`outputRoutingChannelId` 🐘	string	from availableOutputRoutingChannels
`monitoringState` 🐘	`"in"` \| `"auto"` \| `"off"`	input monitoring
`sendGainDb` 🐘	number	send gain in dB, requires sendReturn
`sendReturn` 🐘	string	return track: id, exact name (e.g., "A-Reverb"), or letter (e.g., "A")

🐘 = large model only (hidden in small model mode)

Example output

Called with {"id":"103","mute":false,"gainDb":-3}:

json

{
  "id": "103"
}

Scene Tools

🔧 Create Scene (`ppal-create-scene`)

Add new scenes at any position
Set scene name, color, tempo, and time signature
Scenes can follow song tempo or have their own
Ability to capture currently playing clips into a new scene

Parameters

Parameter	Type	Description
`sceneIndex`	integer	0-based index for new scene(s), shifts existing scenes. Required when capture=false, optional when capture=true
`count` 🐘	integer	number to create
`capture` 🐘	boolean	copy playing session clips instead of creating empty?
`name`	string	name for all, or comma-separated for each
`color`	string	#RRGGBB for all, or comma-separated for each (cycles if fewer than count)
`tempo` 🐘	number	BPM (-1 disables when capturing)
`timeSignature` 🐘	string	N/D (4/4) or "disabled" when capturing

🐘 = large model only (hidden in small model mode)

Example output

Called with {"sceneIndex":2,"name":"Chorus"}:

json

{
  "id": "602",
  "sceneIndex": 2
}

🔧 Read Scene (`ppal-read-scene`)

View scene details and all its clips
Check which clips are playing/triggered
See scene tempo and time signature

Parameters

Parameter	Type	Description
`id`	string	provide this or sceneIndex
`sceneIndex`	integer	0-based index
`include`	array of: `"clips"` \| `"notes"` \| `"sample"` \| `"timing"` \| `"warp"` 🐘 \| `"color"` \| `"*"` 🐘	clips = clip list. notes, sample, timing, warp = clip detail (use with clips). color = scene + clip color. "*" = all

🐘 = large model only (hidden in small model mode)

Example output

Called with {"sceneIndex":1,"include":["*"]}:

json

{
  "id": "202",
  "name": "Verse",
  "sceneIndex": 1,
  "color": "#B87A35",
  "tempo": 96,
  "timeSignature": "6/8",
  "clips": [
    {
      "id": "302",
      "type": "midi",
      "name": "Bass Line",
      "color": "#B87A35",
      "path": "t1/s1",
      "timeSignature": "4/4",
      "looping": true,
      "start": "1|1",
      "end": "3|1",
      "length": "2bar",
      "notes": "v100 n/4d F1 1|1\nv90 n/8 F1 1|3\nv85 n/4 C2 1|4\nv100 n/2 Eb1 2|1",
      "trackName": "Bass"
    },
    {
      "id": "303",
      "type": "audio",
      "name": "Vocal Take",
      "color": "#3DC300",
      "muted": true,
      "path": "t2/s1",
      "timeSignature": "4/4",
      "looping": true,
      "start": "1|1",
      "end": "3|1",
      "length": "2bar",
      "gainDb": -2.6,
      "sampleFile": "/Users/example/Music/Samples/Vocal Take.wav",
      "sampleLength": 352800,
      "sampleRate": 44100,
      "warping": true,
      "warpMode": "complex",
      "trackName": "Vocals"
    }
  ]
}

🔧 Update Scene (`ppal-update-scene`)

Change scene name, color, tempo, and time signature
Update multiple scenes at once

Parameters

Parameter	Type	Description
`id`	string	scene ID(s) to update, comma-separated for multiple
`name`	string	name for all, or comma-separated for each (extras keep existing name)
`color`	string	#RRGGBB for all, or comma-separated for each (cycles if fewer than the scenes)
`tempo`	number	BPM (-1 disables)
`timeSignature`	string	N/D (4/4) or "disabled"

Example output

Called with {"id":"202","name":"Verse A","tempo":96}:

json

{
  "id": "202"
}

Clip Tools

Parameters shown use the default notation

The notes parameter on Create Clip and Update Clip is rewritten to match the active notation. The tables below show it in bar|beat, the default — see MIDI Notation for how it reads under MIDI JSON and Stark.

🔧 Create Clip (`ppal-create-clip`)

Generate MIDI clips with notes, velocities, and timing using custom notation
Place clips in clip slots or the Arrangement timeline
Place arrangement clips on take lanes with a t0/l1 or t0/l+ path
Support for probability, velocity ranges, and complex rhythms
Apply transforms to shape notes with math expressions
Create audio clips from a sample file with sampleFile, and choose whether Live warps it with warping (see Audio Clips)
Auto-create scenes as needed

Parameters

Parameter	Type	Description
`path`	string	where the clip(s) go, comma-separated for multiple. 't<track>/s<scene>' is a clip slot; 't<track>' is that track's arrangement, which also needs arrangementStart; 't<track>/l<lane>' is a take lane on it and 't<track>/l+' appends a fresh one. All indices 0-based, so 't0/s0' is the first track's first scene (e.g., 't0/s0' or 't0/s0,t0/s2' or 't1' with arrangementStart)
`arrangementStart`	string	arrangement clip bar\|beat position(s), comma-separated for multiple (e.g., '1\|1' or '1\|1,2\|1,3\|3'). Song meter
`name`	string	name for all, or comma-separated for each (indexed: clip slots first, then arrangement)
`color`	string	#RRGGBB for all, or comma-separated for each (cycles if fewer than positions)
`timeSignature`	string	N/D (4/4), default: global time signature
`start`	string	bar\|beat position where loop/clip region begins (clip meter)
`length`	string	duration: Nbar (e.g., '4bar'), n<fraction> note value (e.g., 'n/4'), or Nbar+n<fraction> (e.g., '1bar+n/4'). Clip meter. MIDI only, default: next full bar after latest note. Audio clip length comes from the sample
`looping`	boolean	enable looping for the clip
`firstStart` 🐘	string	bar\|beat playback start (looping clips, when different from start; clip meter)
`notes`	string	MIDI in bar\|beat notation: v0-127 n<dur> [p0-1] note(s) bar\|beat(s) - MIDI clips only
`transforms` 🐘	string	transform expressions (parameter: expression per line)
`sampleFile`	string	absolute path to audio file - audio clips only
`warping`	boolean	audio clips only. Omit and Live decides per its Loop/Warp Short Samples setting, often time-stretching the file to the tempo. false = play the file as rendered. The settled state comes back as `warping`
`gainDb`	number	audio clip gain in decibels, 0 = unity (ignored for MIDI)
`pitchShift`	number	audio clip pitch shift in semitones, supports decimals (ignored for MIDI)
`warpMode`	`"beats"` \| `"tones"` \| `"texture"` \| `"repitch"` \| `"complex"` \| `"pro"`	audio clip warp mode (ignored for MIDI)
`auto` 🐘	`"play-scene"` \| `"play-clip"`	auto-play the new session clip(s) — worth setting whenever the user will want to hear what you made. play-scene launches the whole scene so the new clip stays in sync with the others (it restarts them; say so first). play-clip fires the clip alone
`takeLaneName` 🐘	string	name for a take lane this call creates (path 't<track>/l+')

🐘 = large model only (hidden in small model mode)

Example output

Called with {"path":"t1/s0","name":"Bass Fill","notes":"v100 n/8 F1 1|1 C2 1|2"}:

json

{
  "id": "603",
  "path": "t1/s0",
  "noteCount": 2,
  "length": "1bar"
}

🔧 Read Clip (`ppal-read-clip`)

Get detailed info about any clip in Session or Arrangement
Read MIDI notes in custom notation (C3, D#4, etc.)
Get audio clip gain, pitch, warp settings, and sample info

Parameters

Parameter	Type	Description
`id`	string	provide this or path
`path`	string	clip slot 't<track>/s<scene>', both 0-based (e.g., 't0/s3'). provide this or id
`include`	array of: `"sample"` \| `"notes"` \| `"color"` \| `"timing"` \| `"warp"` 🐘 \| `"*"` 🐘	notes = MIDI data. timing = loop/start/end markers. sample = audio file info (sampleFile, gainDb, pitchShift). warp = warp settings (sampleLength, sampleRate, warping, warpMode). color. "*" = all

🐘 = large model only (hidden in small model mode)

Example output

Called with {"id":"302","include":["*"]}:

json

{
  "id": "302",
  "type": "midi",
  "name": "Bass Line",
  "view": "session",
  "color": "#B87A35",
  "path": "t1/s1",
  "timeSignature": "4/4",
  "looping": true,
  "start": "1|1",
  "end": "3|1",
  "length": "2bar",
  "notes": "v100 n/4d F1 1|1\nv90 n/8 F1 1|3\nv85 n/4 C2 1|4\nv100 n/2 Eb1 2|1"
}

🔧 Update Clip (`ppal-update-clip`)

Change clip name, color, and loop settings
Add/remove MIDI notes using custom notation
Apply transforms to modify existing notes and audio properties (use clip.index/clipseq() for per-clip variation when updating multiple)
Change audio clip gain, pitch shift, and warp settings (see Audio Clips)
Move clips and change their length in the Arrangement
Split arrangement clips at specified positions
Update multiple clips at once

Parameters

Parameter	Type	Description
`id`	string	clip ID(s) to update, comma-separated for multiple
`path`	string	clip slot(s) to update instead of id, comma-separated (e.g., 't0/s1' or 't0/s1,t2/s3')
`name`	string	name for all, or comma-separated for each (extras keep existing name)
`color`	string	#RRGGBB for all, or comma-separated for each (cycles if fewer than the clips)
`timeSignature`	string	N/D (4/4)
`start`	string	bar\|beat position where loop/clip region begins (clip meter)
`length`	string	duration: Nbar (e.g., '4bar'), n<fraction> note value (e.g., 'n/4' = quarter), or Nbar+n<fraction> (e.g., '1bar+n/4'); clip meter
`looping`	boolean	enable looping for the clip
`duplicateLoop`	boolean	double the clip length and copy existing notes (and automation envelopes) into the new half (Live's Duplicate Loop). MIDI clips only. Composes with edits in a defined order: start/length/firstStart set the loop region first (select a portion to double; any content past that region is pushed later, not deleted), preTransforms edit the source, then the double; notes/transforms then apply across the full doubled clip
`firstStart` 🐘	string	bar\|beat playback start (looping clips, when different from start; clip meter)
`arrangementStart`	string	bar\|beat position (song meter) to move arrangement clip (arrangement clips only)
`arrangementLength`	string	duration: Nbar (e.g., '4bar'), n<fraction> note value (e.g., 'n/4'), or Nbar+n<fraction> (e.g., '1bar+n/4'). Arrangement clips only; song meter. Lengthening a looping clip tiles copies to fill the span (many clips, not one); for a single clip, set looping false and supply notes for the full length
`arrangementSplit` 🐘	string	comma-separated bar\|beat positions to cut clips at, on the song timeline like arrangementStart (e.g., '9\|1, 17\|1') - max 32 points. A position outside a clip is ignored, so one call can cut several clips at the same song position. Arrangement clips only; song meter
`toPath`	string	clip slot(s) to move the clip(s) to, 't<track>/s<scene>', comma-separated for multiple (e.g., 't2/s3' or 't2/s3,t2/s4'); session clips only. Paired 1:1 with the clips named by id/path, in order - destinations don't cycle, so name one slot per clip
`gainDb`	number	audio clip gain in decibels, 0 = unity (ignored for MIDI)
`pitchShift`	number	audio clip pitch shift in semitones, supports decimals (ignored for MIDI)
`warpMode`	`"beats"` \| `"tones"` \| `"texture"` \| `"repitch"` \| `"complex"` \| `"pro"`	audio clip warp mode (ignored for MIDI)
`warping`	boolean	audio clip warping on/off (ignored for MIDI). false resets the region to the whole file and turns looping off; looping:true forces warping back on
`notes`	string	MIDI notes in bar\|beat notation: v0-127 n<dur> [p0-1] note(s) bar\|beat(s) - MIDI clips only. MERGES into existing notes (overwrites at same pitch+start - restate a note to edit it in place). To delete/move existing notes or replace a region use preTransforms; don't rewrite the whole clip
`transforms` 🐘	string	transform expressions applied AFTER merging notes (broadcast across the clips); newline-separated for multiple. Use clip.index / clipseq() for per-clip variation
`preTransforms`	string	transform expressions applied to EXISTING notes BEFORE merging any new notes (broadcast across the clips); clear or edit notes already in the clip. 'delete' (alias 'v0') removes: a whole bar ('3\|: delete', \| wildcard avoids spilling onto the next downbeat), a span ('1\|1-2\|1: delete'), one pitch ('C1: delete'), a pitch range ('C1-C5: delete'), or all ('delete'); also remap a drum lane ('C1: C4'). Works with or without notes
`quantize`	number	quantize strength 0-1; default 1 (full snap) when quantizeGrid is set. Snaps note starts to quantizeGrid. MIDI clips only
`quantizeGrid`	`"1/4"` \| `"1/8"` \| `"1/8T"` \| `"1/8+1/8T"` \| `"1/16"` \| `"1/16T"` \| `"1/16+1/16T"` \| `"1/32"` \| `"n/4"` \| `"n/8"` \| `"n/12"` \| `"n/16"` \| `"n/24"` \| `"n/32"`	grid that note starts snap to: 1/16 (default), 1/8, 1/4, 1/8T, 1/16T, 1/32; n/N note values also accepted (n/12=1/8T, n/24=1/16T); mixed grids 1/8+1/8T and 1/16+1/16T are enum-only
`quantizePitch` 🐘	string	limit quantization to specific pitch (e.g., C3, D#4)

🐘 = large model only (hidden in small model mode)

Example output

Called with {"id":"302","name":"Bass Line A","transforms":"pitch += 12"}:

json

{
  "id": "302",
  "noteCount": 4,
  "transformed": 4
}

Audio Clips

A new audio clip's region comes from its sample, so start, length, firstStart, and looping are MIDI-only on Create Clip and are ignored (with a warning) alongside a sampleFile. timeSignature and the audio properties — gainDb, pitchShift, warpMode, warping — do apply. On Update Clip, start and length reshape an existing audio clip's region normally.

Warping. When you create an audio clip, Live decides for itself whether to warp the sample, following your Loop/Warp Short Samples preference — which no API can read, so the same call can land differently on two machines. Pass warping: false to play the file exactly as recorded or rendered. Omit it and Live still decides, but the result reports which way it went.

warping: false means the same thing on Create Clip and Update Clip: reset the region to the whole file and turn looping off, which is what Live does underneath. Two consequences on Update Clip:

It erases a start/length sent in the same call. Reshape the region in a follow-up call.
looping: true forces warping back on, so it vetoes a warping: false sent alongside it, and warns that it did.

Unwarped clips are measured against the sample. Live switches a clip's markers from beats to seconds when warping is off, and reports an unwarped session clip's length as though it were still warped. Producer Pal measures the region from the markers instead, so a 1.2-second one-shot reads as the beats it really occupies at your tempo rather than as 1.2 beats — which is also what keeps Duplicate from tiling copies over audio that's still sounding.

Device Tools

🔧 Create Device (`ppal-create-device`)

Add native Live devices (instruments, MIDI effects, audio effects)
Place devices on any track type: MIDI, audio, return, or master
Position devices at a specific index in the device chain
Create devices inside rack chains or drum pads using path notation
List the native Live devices
Load a sample into a Simpler instrument via params: [{name: "sample", value: "<path>"}], and set its level with {name: "gainDb", value: <dB>} (new in Live 12.4)

Parameters

Parameter	Type	Description
`deviceName`	string	device name, omit to list available devices
`path`	string	insertion path(s), required with deviceName, comma-separated for multiple (e.g., 't0' or 't0,t1,t0/d0/c0')
`name`	string	name for all, or comma-separated for each
`params`	array	applied after creation — array of {name, value}. name = param name or read-device id; value in display units (enum string, note name, number). For a Drum Rack, prefix the name with a pad path to address a pad's device, e.g. {name:'pC1/d0/sample', value:'<abs file path>'} loads a sample into pad C1 (auto-creates the pad's Simpler) — build a full kit in one call

Example output

Called with {"deviceName":"Saturator","path":"t1"}:

json

{
  "id": "604",
  "deviceIndex": 2
}

🔧 Read Device (`ppal-read-device`)

Get detailed info about any device, including inside rack chains and drum pad chains
List device parameter names and values (the state of knobs, dials, etc)
See a rack chain's own volume, pan, and sends when they're not at default

Parameters

Parameter	Type	Description
`id`	string	device or drum pad ID to read
`path`	string	path (e.g., 't1/d0', 't1/d0/c0', 't1/d0/pC1', 't1/d0/rc0')
`include`	array of: `"actions"` 🐘 \| `"chains"` \| `"drum-map"` \| `"drum-pads"` 🐘 \| `"params"` \| `"param-values"` \| `"return-chains"` 🐘 \| `"sample"` \| `"options"` \| `"*"` 🐘	chains, return-chains, drum-pads = rack contents (use maxDepth; a chain lists its own gainDb/pan/sends only when non-default). params, param-values = parameters. drum-map = pad names keyed by note (drum name in stark, MIDI number in midi-json). sample = Simpler sample file path (flat top-level field; gainDb and other sample params are in params). actions = device-specific actions for update-device (name, signature, description). options = valid pseudo-param values (paramOptions) + dynamic catalogs for specialized devices (IR files, sidechain sources, wavetables) + Wavetable mod routes. "*" = all
`maxDepth`	integer	Device tree depth for chains/drum-pads. 0=chains only with deviceCount, 1=direct devices, 2+=deeper
`paramSearch`	string	Filter parameters by case-insensitive substring match on name

🐘 = large model only (hidden in small model mode)

Example output

Called with {"id":"401","include":["*"]}:

json

{
  "id": "401",
  "path": "t0/d0",
  "type": "drum-rack",
  "name": "Kit",
  "parameters": [
    {
      "id": "4010",
      "name": "Device On",
      "value": "On",
      "min": 0,
      "max": 1
    },
    {
      "id": "4011",
      "name": "Macro 1",
      "value": "0.0 %",
      "min": 0,
      "max": 127
    },
    {
      "id": "4012",
      "name": "Decay (Macro 2)",
      "value": "50.4 %",
      "min": 0,
      "max": 127
    }
  ],
  "drumMap": {
    "C1": "Kick",
    "D1": "Snare"
  },
  "drumPads": [
    {
      "id": "408",
      "note": 36,
      "pitch": "C1",
      "name": "Kick",
      "chains": [
        {
          "id": "402",
          "path": "t0/d0/pC1/c0",
          "type": "Chain",
          "name": "Kick",
          "color": "#FF4C4C",
          "devices": [
            {
              "id": "403",
              "path": "t0/d0/pC1/c0/d0",
              "type": "instrument: Simpler",
              "name": "Kick"
            }
          ]
        }
      ]
    },
    {
      "id": "409",
      "note": 38,
      "pitch": "D1",
      "name": "Snare",
      "chains": [
        {
          "id": "404",
          "path": "t0/d0/pD1/c0",
          "type": "Chain",
          "name": "Snare",
          "color": "#FF4C4C",
          "devices": [
            {
              "id": "405",
              "path": "t0/d0/pD1/c0/d0",
              "type": "instrument: Simpler",
              "name": "Snare"
            }
          ]
        }
      ]
    }
  ]
}

🔧 Update Device (`ppal-update-device`)

Change device name
Change device parameter values (control knobs, dials, etc)
Update multiple devices at once
Move devices anywhere else in the Live Set, including into racks / wrapping in a new rack
Create, load, delete, revert, and randomize rack macro variations
A/B Compare with supported devices
Control chain and drum pad mute and solo state
Set a rack chain's own volume, pan, and send levels
Change the choke group and output MIDI note of drum chains
Move a drum pad to another pad, keeping its chain trim, choke group, and devices together
Load a sample into a Simpler instrument (see Create Device above)

Parameters

Parameter	Type	Description
`id`	string	ID(s) to update (device, chain, or drum pad), comma-separated for multiple
`path`	string	comma-separated path(s) (e.g., 't1/d0', 't1/d0/c0', 't1/d0/pC1')
`toPath`	string	move to path (e.g., 't2', 't0/d0/c1', 't0/d0/pD1'). To move a whole drum pad (chain trim, choke group and devices together), target the pad path (e.g. path 't0/d0/pC1', toPath 't0/d0/pD1') rather than its device; a pad move stays within one rack and layers onto an occupied destination rather than replacing it. Moving just a device carries its chain's trim only when the destination chain is empty and untouched, and warns otherwise
`name`	string	name for all, or comma-separated for each (extras keep existing name, not drum pads)
`params`	array	array of {name, value}. name = param name or read-device id; value in display units (enum string, note name, number). For a Drum Rack target, prefix the name with a pad path, e.g. {name:'pC1/d0/sample', value:'<abs file path>'} sets pad C1's sample (auto-creates the pad's Simpler)
`force`	boolean	Only when a sample write was skipped for replacing a pad's instrument: true replaces it anyway.
`actions` 🐘	array	Device-specific action(s), function-call syntax: bare name or name(args). E.g. "reverse", "warpAs(4)", "setModulation('Osc 1 Pos','Env 2',0.5)"
`macroVariation` 🐘	`"create"` \| `"load"` \| `"delete"` \| `"revert"` \| `"randomize"`	Rack only: create/load/delete/revert variation, or randomize macros. load/delete require macroVariationIndex. create always appends.
`macroVariationIndex` 🐘	integer	Rack only: variation index for load/delete operations (0-based)
`macroCount` 🐘	integer	Rack only: set visible macro count (0-16)
`abCompare` 🐘	`"a"` \| `"b"` \| `"save"`	AB Compare: switch to 'a' or 'b' preset, or 'save' current to other slot
`mute`	boolean	mute state (chains/drum pads only)
`solo`	boolean	solo state (chains/drum pads only)
`color`	string	#RRGGBB for all, or comma-separated for each (cycles if fewer than the chains; chains only)
`gainDb` 🐘	number	chain's own gain in dB (chains only; a pad path works unless the pad has layers, which take a layer path like 't0/d0/pC1/c1')
`pan` 🐘	number	chain's own pan, -1 (left) to 1 (right) (chains only; a pad path works unless the pad has layers, which take a layer path)
`sendGainDb` 🐘	number	chain's send level in dB, requires sendReturn (chains only)
`sendReturn` 🐘	string	rack return chain for sendGainDb: id, exact name (e.g. "a Reverb"), or letter (e.g. "a"); requires sendGainDb
`chokeGroup` 🐘	integer	choke group 0-16, 0=none (drum chains only)
`mappedPitch` 🐘	string	output MIDI note e.g. 'C3' (drum chains only)
`wrapInRack` 🐘	boolean	Wrap device(s) in a new rack (auto-detects type from device)

🐘 = large model only (hidden in small model mode)

Example output

Called with {"id":"406","params":[{"name":"Filter Freq","value":"0.6"}]}:

json

{
  "id": "406"
}

Advanced Tools

🔧 Live API (`ppal-live-api`)

Direct access to the Ableton Live Object Model for scripting and debugging.

Off by default. Producer Pal's specialized tools are tuned for reliable results across most models; the raw Live API is low-level and can give weaker results out of the box, so it's hidden rather than competing with them. It's a powerful escape hatch for scripting and advanced workflows, especially with capable coding agents. Enable it on the Setup tab of the Producer Pal Max for Live device, or programmatically via POST /config (the npx producer-pal MCP server also accepts a --live-api flag). See the REST API's Live API section for the full operation reference and examples.

Parameters

Parameter	Type	Description
`path`	string	Optional LiveAPI path (e.g., 'live_set tracks 0')
`operations`	array	Array of operations to execute (max 50)

Example output

Called with {"path":"live_set","operations":[{"type":"getProperty","property":"tempo"},{"type":"getChildIds","property":"tracks"}]}:

json

{
  "path": "live_set",
  "id": "1",
  "results": [
    {
      "operation": {
        "type": "getProperty",
        "property": "tempo"
      },
      "result": 110
    },
    {
      "operation": {
        "type": "getChildIds",
        "property": "tracks"
      },
      "result": [
        "id 101",
        "id 102",
        "id 103"
      ]
    }
  ]
}

Built-in Chat UI

Desktop Apps

Command Line

Web Apps

Choose by Provider

Advanced

Tool Reference

Core Tools

🔧 Connect (`ppal-connect`)

🔧 Context (`ppal-context`)

Session Tools

🔧 Playback (`ppal-playback`)

🔧 Library (`ppal-library`)

🔧 Select (`ppal-select`)

Action Tools

🔧 Delete (`ppal-delete`)

🔧 Duplicate (`ppal-duplicate`)

Live Set Tools

🔧 Read Live Set (`ppal-read-live-set`)

🔧 Update Live Set (`ppal-update-live-set`)

Track Tools

🔧 Create Track (`ppal-create-track`)

🔧 Read Track (`ppal-read-track`)

🔧 Update Track (`ppal-update-track`)

Scene Tools

🔧 Create Scene (`ppal-create-scene`)

🔧 Read Scene (`ppal-read-scene`)

🔧 Update Scene (`ppal-update-scene`)

Clip Tools

🔧 Create Clip (`ppal-create-clip`)

🔧 Read Clip (`ppal-read-clip`)

🔧 Update Clip (`ppal-update-clip`)

Audio Clips

Device Tools

🔧 Create Device (`ppal-create-device`)

🔧 Read Device (`ppal-read-device`)

🔧 Update Device (`ppal-update-device`)

Advanced Tools

🔧 Live API (`ppal-live-api`)

Tool Reference ​

Core Tools ​

🔧 Connect (ppal-connect) ​

🔧 Context (ppal-context) ​

Session Tools ​

🔧 Playback (ppal-playback) ​

🔧 Library (ppal-library) ​

🔧 Select (ppal-select) ​

Action Tools ​

🔧 Delete (ppal-delete) ​

🔧 Duplicate (ppal-duplicate) ​

Live Set Tools ​

🔧 Read Live Set (ppal-read-live-set) ​

🔧 Update Live Set (ppal-update-live-set) ​

Track Tools ​

🔧 Create Track (ppal-create-track) ​

🔧 Read Track (ppal-read-track) ​

🔧 Update Track (ppal-update-track) ​

Scene Tools ​

🔧 Create Scene (ppal-create-scene) ​

🔧 Read Scene (ppal-read-scene) ​

🔧 Update Scene (ppal-update-scene) ​

Clip Tools ​

🔧 Create Clip (ppal-create-clip) ​

🔧 Read Clip (ppal-read-clip) ​

🔧 Update Clip (ppal-update-clip) ​

Audio Clips ​

Device Tools ​

🔧 Create Device (ppal-create-device) ​

🔧 Read Device (ppal-read-device) ​

🔧 Update Device (ppal-update-device) ​

Advanced Tools ​

🔧 Live API (ppal-live-api) ​

Tool Reference

Core Tools

🔧 Connect (`ppal-connect`)

🔧 Context (`ppal-context`)

Session Tools

🔧 Playback (`ppal-playback`)

🔧 Library (`ppal-library`)

🔧 Select (`ppal-select`)

Action Tools

🔧 Delete (`ppal-delete`)

🔧 Duplicate (`ppal-duplicate`)

Live Set Tools

🔧 Read Live Set (`ppal-read-live-set`)

🔧 Update Live Set (`ppal-update-live-set`)

Track Tools

🔧 Create Track (`ppal-create-track`)

🔧 Read Track (`ppal-read-track`)

🔧 Update Track (`ppal-update-track`)

Scene Tools

🔧 Create Scene (`ppal-create-scene`)

🔧 Read Scene (`ppal-read-scene`)

🔧 Update Scene (`ppal-update-scene`)

Clip Tools

🔧 Create Clip (`ppal-create-clip`)

🔧 Read Clip (`ppal-read-clip`)

🔧 Update Clip (`ppal-update-clip`)

Audio Clips

Device Tools

🔧 Create Device (`ppal-create-device`)

🔧 Read Device (`ppal-read-device`)

🔧 Update Device (`ppal-update-device`)

Advanced Tools

🔧 Live API (`ppal-live-api`)