load_device
Destructive
Search Live's browser for a device and load it onto a track, returning search candidates or the load result.
Instructions
Search Live's browser and load a device onto a track: a search step, then a load step.
Returns:
Dictionary of search candidates and the selected track on the search step,
or the load result and the resulting device chain on the load step.
Note:
A load cannot be aimed inside a rack: measured 2026-09-07 against Live 12.4.5,
``rack.view.selected_chain`` read back as written and the device still landed on the
track. An effect is appended; an instrument replaces the one already there and
discards it silently, with its settings and the clip envelopes pointing at it: check
with get_devices first. Loading plug-ins in rapid succession can crash Live
(measured: a batch load during a plug-in rescan with a licence dialog open took Live
down), so load one at a time. A load also arms the target track and disarms every
other one (measured 2026-09-19 against Live 12.4.6: of two armed tracks and an
unarmed target, the target came back armed and the others disarmed), and nothing
here reports it. An instrument load renames a track that still has Live's default
name; an effect never renames.
Success means the call ran, not that the track sounds: a measured Drum Rack load
reported success on a silent track, and an empty rack is what that looks like, so
read ``song.tracks[N].devices[i].chains``, which get_devices does not report. A null
``selected_track_same``, ``displaced`` or ``configure_needed`` means the comparison
failed, not ``false``; the first compares name and track count, not identity.
``loaded_device_index`` is the position of the new device, computed only where
the two chains single out exactly one, and null otherwise.
``status: incomplete`` with no candidates means the walk stopped early, not that the
item is absent: retry ``unreached_roots``; only ``complete`` rules it out. The main
track has no index: write ``song.view.selected_track`` with ``{"__path__":
"song.master_track"}`` through lom_set, then load.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uri | No | The uri of one candidate from a previous search step, copied back verbatim to say which item to load. Resolving it walks the browser a second time, so pass root as well when the item sits deep; item_path avoids the walk altogether and is preferred. | |
| root | No | Browser category to search inside. Empty searches every category, which is slower and returns more near misses. These are the roots the Remote Script walks; there is no user_folders or legacy_libraries here, although the catalog carries rows for both. | |
| limit | No | How many search candidates to return. | |
| query | No | What to look for in the browser, matched against item names, e.g. 'Operator' or 'reverb'. Required for the search step; on the load step it can be dropped once uri or item_path is known. | |
| track | No | Track to load onto, counted from 0. -1 uses whatever is selected, which is what this did before the argument existed. Naming a track points the selection at it first, so a caller does not have to express the load as two steps and cannot load onto a track that happened to be selected. The selection stays there afterwards and is not put back: the LOM offers nothing to restore it to. 'aimed' reports where it went. | |
| confirm | No | False searches and loads nothing, reporting the candidates and which track is selected. True loads the item named by uri or item_path. | |
| item_path | No | The browser item as a LOM path rooted at app, e.g. 'app.browser.instruments.children[3]'. The reliable handle, and the one to prefer: unlike a uri it is not walked for again, so it cannot fail on the walk budget. Every search candidate carries one. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||