als_write
Destructive
Modify Ableton Live .als project files on disk using sidechain, configure, attribute, or restore operations, requiring explicit confirmation before writing changes.
Instructions
Edit a saved .als project file on disk. Requires confirm=True.
Supported operations: 'sidechain', 'configure', 'attribute', 'restore'.
The target file must not be the one Live currently holds: Live writes its own
memory over the file when it next saves, without a conflict warning, and the
edit is gone. Live running on a different set is fine.
Returns:
Dictionary reporting write status, changes made, and verification report.
Note:
``sidechain`` is here for the set Live is not holding, someone else's project
wired on disk. Measured across the 174-project corpus (docs/limits.md section 9):
74 of 82 in the house/trance BPM window use sidechain compression, median 6
wirings each. For
the set on screen use ``lom_set`` and keep the read-back.
``configure`` fills a plugin's parameter strip, which no LOM call can do whatever
the strip currently holds. Two parameters written into an instance whose strip
held nothing came back on reopen with their real values, writable through
``lom_set`` with ``read_back: applied``. Live allocates 128 slots per instance and
leaves them all in the file, so nothing is inserted. Three fields of an existing
element are filled.
``attribute`` sets one attribute anywhere in the file, addressed by an
ElementTree expression. An expression matching more than one element is refused
unless ``index`` picks one, and ``index`` counts the matches of that expression
rather than tracks in the project: ``.//MidiTrack/Name/EffectiveName`` does not
see the audio tracks at all.
Where the expression comes from: ``als_read`` with ``locate='tempo'`` or
``locate='track_names'`` answers with the expression, the attribute and the
index for those fields, which are the ones usually edited on a file. For
anything else the expression is built by hand, and ``confirm=False`` resolves
it against the file first and reports what it selects, so a wrong one is
caught before it writes rather than after.
Choosing between the four: ``sidechain`` and ``configure`` for the two things
the LOM cannot do at all, ``attribute`` for anything else in the file, and
``restore`` to undo any of them. For
the set open in Live, none of these: use lom_set, set_parameter or set_mix
and keep the read-back.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tap | No | Where the sidechain listens on the source track: 'pre' before that track's own effects and fader, 'post' after them. Used by 'sidechain' only. | post |
| path | Yes | Filesystem path to the .als project to edit. A backup is written first and can be put back with the restore operation. | |
| index | No | Which match to edit when the expression selects more than one element, counted from 0. An ambiguous expression is refused rather than resolved to the first match, so this is how to disambiguate. | |
| value | No | For 'attribute', the new attribute value. For 'configure', the parameter strip assignment as '<index>=<name>; ...'. | |
| backup | No | Path to the backup file to put back. Required by the 'restore' operation and read by no other. | |
| create | No | True adds the attribute when the element does not already carry it. False refuses, which catches a misspelled attribute name instead of inventing a field Live will ignore. | |
| device | No | Device index within the target track chain, counted from 0. Used by 'sidechain' and 'configure'. | |
| confirm | No | True carries the edit out. False changes nothing and reports what the call requires, which is how to check the arguments first. | |
| attribute | No | Which attribute of the selected element to set. Live stores most numbers under 'Value'. Used by 'attribute' only. | Value |
| operation | Yes | What to do. 'sidechain' wires a compressor to a trigger track, 'configure' fills a plug-in parameter strip, 'attribute' sets one XML attribute anywhere in the file, 'restore' puts a backup back. Each one reads a different subset of the arguments below. | |
| expression | No | ElementTree path selecting the element to edit, e.g. './/MasterTrack/DeviceChain/Mixer/Tempo/Manual'. Used by 'attribute' only. Read the tree with als_read first. | |
| source_track | No | Name of the track the compressor should listen to, which is usually the kick. Used by 'sidechain' only. | |
| target_track | No | Name of the track carrying the device to edit, as it appears in Live. Used by 'sidechain' and 'configure'. | |
| allow_live_running | No | True permits the edit while Live is running at all. The check behind it looks for a running Live process and cannot tell which set that process holds, so it is not a guard against editing the open one: only you know that. What matters is the file, not the process. Live open on a different set is harmless. Live holding this file overwrites the edit from memory when it next saves. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||