---
name: livepilot-devices
description: This skill should be used when the user asks to "load a device", "add an effect", "find a plugin", "device chain", "rack", "preset", "sound design setup", "load instrument", "find a synth", or wants to browse, load, and configure devices in Ableton Live.
---

# Device Loading and Configuration

Load instruments, effects, and plugins into Ableton Live tracks. Every device operation follows one discipline: search first, verify after.

## Primary Workflow — Atlas-Driven

The device atlas contains 1,305 devices with sonic descriptions, recipes, and recommendations. Always start here:

1. **Discover:** `atlas_search(query)` — find devices by name, sound character, or genre
2. **Learn:** `atlas_device_info(device_id)` — full parameters, recipes, gotchas, pairings
3. **Suggest:** `atlas_suggest(intent, genre)` — "I need a warm pad" → ranked device+recipe combos
4. **Chain:** `atlas_chain_suggest(role, genre)` — full device chain for a track role (instrument + effects)
5. **Load:** Use the URI from atlas results → `load_browser_item(uri)` or `find_and_load_device(name)`
6. **Recipe:** Apply starter recipe params → `batch_set_parameters(params)` from the atlas entry
7. **Verify:** `get_device_info(track_index, device_index)` — check health flags

If the atlas doesn't have a device (newly installed plugin, user sample), fall back to the browser workflow below.

## Browser Workflow — The Fallback Path

Use the browser workflow when the atlas doesn't have what you need:

1. **Search:** `search_browser(path, name_filter)` — returns a list of matching items with exact URIs
2. **Inspect:** Read the results. Confirm the item name, type, and path match what you need
3. **Load:** `load_browser_item(uri)` — pass the exact URI string from search results

Common search paths:
- `path="Instruments"` — synths, samplers, instrument racks
- `path="Drums"` — drum racks, drum kits, percussion
- `path="Audio Effects"` — reverb, delay, compressor, EQ, saturator
- `path="MIDI Effects"` — arpeggiator, chord, scale, random
- `path="Sounds"` — preset sounds organized by category
- `path="Samples"` — audio samples, one-shots, loops

Combine path with `name_filter` to narrow results. Example: `search_browser(path="Drums", name_filter="808 Kit")`.

NEVER invent device or preset names. A hallucinated name like "echomorph-hpf" or "Drift Pad Wonk" will crash the load. Always search first, then use the exact URI from results.

For the full URI grammar reference (the three forms — FileId, bare-name, path-style — failure modes, and discovery recipe), see `references/load_browser_item-uri-grammar.md`.

## find_and_load_device — The Shortcut

Use `find_and_load_device(name)` ONLY for these simple built-in effects:
- "Reverb"
- "Delay"
- "Compressor"
- "EQ Eight"
- "Saturator"
- "Utility"

For everything else — instruments, racks, presets, AU/VST plugins — use the browser workflow. The shortcut matches greedily and can load a sample file instead of a synth when names overlap (e.g., "Drift" matches "Synth Bass Drift Pad Wonk Bass.wav" before the Drift synthesizer).

## Plugin Health Verification

After loading any device, verify it actually works:

1. Call `get_device_info(track_index, device_index)` on the newly loaded device
2. Check `parameter_count` — if the device is an AU/VST plugin (`class_name` contains "PluginDevice") and `parameter_count` is 1 or less, the plugin is dead. The shell loaded but the DSP engine crashed.
3. Check `health_flags` for `opaque_or_failed_plugin` (dead or untweakable AU/VST) or `sample_dependent` (needs source audio)
4. Check `plugin_host_status` and `mcp_sound_design_ready`
5. If `mcp_sound_design_ready` is `false`: delete the device with `delete_device`, replace it with a native Ableton alternative, and report the failure to the user

Dead plugin recovery pattern:
```
get_device_info → parameter_count <= 1 on PluginDevice?
  → delete_device(track_index, device_index)
  → search_browser for native alternative
  → load_browser_item with replacement URI
  → report failure and substitution to user
```

## Rack Introspection

Use `walk_device_tree(track_index)` to see the full nested structure of racks on a track — Instrument Racks, Audio Effect Racks, and Drum Racks with all their chains and sub-devices.

Use `get_rack_chains(track_index, device_index)` to inspect individual rack chain contents. For Drum Racks, this reveals which pads have samples loaded and which chains exist. An empty Drum Rack (zero chains) produces silence.

Set chain volumes with `set_chain_volume(track_index, device_index, chain_index, volume)` to balance rack layers.

## Drum Rack Rule

NEVER load a bare "Drum Rack" — it is an empty container with zero chains and produces silence. Always load a kit preset through the browser:

```
search_browser(path="Drums", name_filter="Kit")
```

Pick a real kit from results: "909 Core Kit", "808 Core Kit", "Boom Bap Kit", "Lo-Fi Kit", etc. These come pre-loaded with samples on their pads.

After loading any Drum Rack preset, verify with `get_rack_chains` that chains exist and have named pads like "Bass Drum", "Snare", "Hi-Hat".

## Custom Drum Rack Construction (build a kit from one-shots)

When the user asks for a custom kit ("build me a minimal-techno kit", "make a Dilla-style boom-bap kit from these samples"), use `add_drum_rack_pad` — NOT repeated `load_browser_item` calls.

**Why this matters (BUG-2026-04-22 #1):** Calling `load_browser_item` repeatedly on a track that contains a Drum Rack does NOT add new pads. The first call creates a chain at note 36; every subsequent call REPLACES the existing chain instead of appending to the next pad. After 7 sequential drops you end up with exactly 1 chain — only the last sample. This is a Live API limitation, not something to work around with retry loops.

**The canonical workflow:**

```
# 1. Make sure a Drum Rack exists on the track. Either:
#    - Load a preset kit and clear it, or
#    - insert_device(track_index=N, device_name="Drum Rack") for an empty rack
# 2. For each sample:
add_drum_rack_pad(
    track_index=N,
    pad_note=36,                  # 36=Kick, 38=Snare, 42=Closed HH, 46=Open HH
    file_path="/abs/path/to/sample.wav",
)
```

`add_drum_rack_pad` does the full atomic build per pad: insert_rack_chain → set_drum_chain_note → insert empty Simpler into the chain → load sample via the native Live 12.4 replace_sample API with nested addressing. Returns `{ok, chain_index, pad_note, nested_device_index}` so you can verify and chain further calls.

Requires Live 12.4+ (uses native nested-sample loading). On older versions returns an error directing the caller to the legacy separate-tracks workaround.

For nested-Simpler operations on existing pads (e.g., adjust loop points after the kit is built), `replace_simpler_sample` and `load_sample_to_simpler` accept `chain_index` and `nested_device_index` for explicit deep addressing.

## Sample-Dependent Devices

These devices load "successfully" with many parameters but produce zero audio without source material. Since MCP tools cannot load samples into third-party plugin UIs, NEVER use these as standalone instruments:

- **Granular synths:** iDensity, Tardigrain, Koala Sampler, Burns Audio Granular
- **Bare samplers:** Simpler (empty), Sampler (empty) — always load a preset, never the empty shell
- **Sample players:** AudioLayer, sEGments

Use self-contained synthesizers instead — these produce sound immediately from MIDI input alone:
- **Wavetable** — versatile wavetable synthesis
- **Operator** — FM synthesis, 4 operators
- **Drift** — analog-modeled, warm and organic
- **Analog** — subtractive analog modeling
- **Meld** — MPE-ready, two engines
- **Collision** — physical modeling, mallet/resonator
- **Tension** — physical modeling, string/exciter

If granular textures are needed: use Wavetable with aggressive wavetable position modulation, Operator with FM feedback and short envelopes, or load a Simpler/Sampler **preset** (not the bare instrument) from the Sounds browser.

## Simpler Operations

For Simpler devices that already have samples loaded:

- `load_sample_to_simpler(track_index, device_index, file_path)` — load audio into Simpler
- `replace_simpler_sample(track_index, device_index, file_path)` — swap the current sample. Only works on Simplers that already have a sample loaded.
- `crop_simpler(track_index, device_index)` — trim sample to current start/end points
- `reverse_simpler(track_index, device_index)` — reverse the loaded sample
- `get_simpler_slices(track_index, device_index)` — retrieve auto-detected slice points (Slice mode)
- `set_simpler_playback_mode(track_index, device_index, playback_mode)` — switch modes: 0=Classic, 1=One-Shot, 2=Slice. Optional: `slice_by` (0=Transient, 1=Beat, 2=Region, 3=Manual), `sensitivity` (0.0-1.0, Transient only)
- `warp_simpler(track_index, device_index, beats)` — warp sample to fit N beats

### Slice Workflow

For slice-based production, use `plan_slice_workflow`:
1. `plan_slice_workflow(file_path=..., intent="rhythm")` — generates a complete workflow with Simpler setup, slice mapping, and MIDI notes
2. Intents: `rhythm`, `hook`, `texture`, `percussion`, `melodic`
3. The tool returns a step-by-step plan — execute each tool call in sequence

Manual slice workflow: load sample → `set_simpler_playback_mode(playback_mode=2)` → `get_simpler_slices` → program MIDI notes targeting slice indices (C3 = slice 0, C#3 = slice 1, etc.)

### New Device Operations (12.3+)

- `insert_device(track_index, device_name)` — insert native device by name (10x faster than browser, 12.3+)
- `insert_rack_chain(track_index, device_index)` — add chain to Instrument/Audio/Drum Rack
- `set_drum_chain_note(track_index, device_index, chain_index, note)` — assign MIDI note to Drum Rack chain
- `add_drum_rack_pad(track_index, pad_note, file_path)` — atomic single-pad build (chain + note + Simpler + sample). 12.4+. Use this for custom kit construction; see the "Custom Drum Rack Construction" section above.
- `move_device(track_index, device_index, new_index)` — reorder devices on a track

### Plugin Deep Control

- `get_plugin_parameters(track_index, device_index)` — all AU/VST plugin parameters
- `map_plugin_parameter(track_index, device_index, parameter_index)` — map for automation
- `get_plugin_presets(track_index, device_index)` — list plugin presets

## Parameter Name Quirks (BUG-2026-04-22 #10)

Ableton's parameter names are inconsistent across devices. When `set_device_parameter` or `batch_set_parameters` errors with "Parameter 'X' not found," the response already lists the first 20 available names — read it and pick the right one. Common surprises:

| You'd expect | Actual name | Where |
|---|---|---|
| `Width` | `Stereo Width` | Utility |
| `Cutoff` | `Filter Freq` / `Frequency` | Various filters — check per-device |
| `Resonance` | `Filter Resonance` / `Q` | Same |
| `Drive` | `Drive` (Saturator) but `Drive Amount` (some racks) | Saturator vs racks |
| `Mix` | `Dry/Wet` | Almost every native effect |
| `Volume` | `Volume` (mixer) but `Sample Volume` / `Out Volume` | On certain devices |

When in doubt, call `get_device_parameters(track_index, device_index)` first — it returns the exact `name` of every parameter and the `name` field is what `set_device_parameter` accepts.

## Effect Chain Best Practices

After loading any effect, verify its key parameters are not at pass-through defaults:
- **Reverb:** `Dry/Wet` should be > 0 (typically 20-40% for subtle, 60-100% for creative)
- **Delay:** `Dry/Wet` > 0, `Feedback` set appropriately
- **Compressor:** `Threshold` below signal level, `Ratio` > 1:1
- **EQ Eight:** At least one band with non-zero gain
- **Saturator:** `Drive` > 0 dB
- **Utility:** `Gain` at target value, `Width` as needed

Use `get_device_parameters` to read current values, then `set_device_parameter` or `batch_set_parameters` to configure. Use `toggle_device` to bypass/enable devices for A/B comparison.

## Device Presets

- `get_device_presets(track_index, device_index)` — list available presets for the loaded device
- `get_plugin_parameters(track_index, device_index)` — see all AU/VST plugin parameters
- `get_plugin_presets(track_index, device_index)` — list presets for AU/VST plugins
- `map_plugin_parameter(track_index, device_index, parameter_index)` — map a plugin parameter for automation

## Device Atlas Reference

Consult `references/device-atlas/` in the livepilot-core skill for the full corpus of 280+ instruments, 139 drum kits, and 350+ impulse responses. The atlas contains real browser URIs, preset names, and sonic descriptions. Use it as your lookup table before loading any device — never guess a name that is not in the atlas or in browser search results.