write_automation
Write an automation envelope into an Ableton Live Session clip and verify the stored curve via read-back.
Instructions
Write an automation envelope into a Session clip and verify the read-back.
Turns a handful of breakpoints into a written curve, then reads it back so the
result reports the stored envelope rather than the requested one.
Returns:
Dictionary reporting the write, how many points were laid down, and the
comparison between the stored curve and the generated one.
Note:
Automation lives in Session clips. There is no way to write an Arrangement
envelope directly here: write it into the Session clip and then copy the clip
onto the timeline with arrange, which carries the envelope with it.
A verified write proves the stored curve, never that it is audible. An
envelope on a parameter of a device that is switched off, or on a muted
track, reads back exactly as written and changes nothing anyone can hear.
With ``clear_first=False`` a repeated call layers points onto the ones
already there, so a retry after an unclear result can leave a curve that
matches neither attempt. Read it with read_automation before writing again.
To explicitly clear an envelope without writing new points, use clear_automation.
Playing the clip leaves the parameter at the value this curve last reached, and
stopping does not restore it. Capture the statics you care about before the first
playthrough: once a curve has run, nothing reports the value it covered.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | LOM path to a Session clip, song.tracks[N].clip_slots[M] with or without a trailing .clip, as an alternative to track and slot. A song.tracks[N].arrangement_clips[i] path is refused with code region_not_addressable. | |
| slot | No | Clip slot index in track.clip_slots, counted from 0, which is the scene the clip sits in. Give track and slot, or give path instead. These are Session coordinates; an Arrangement clip has none. | |
| track | No | Session track index in song.tracks, counted from 0. Give track and slot, or give path instead. These are Session coordinates; an Arrangement clip has none. | |
| points | Yes | The breakpoints, as [[beat, value], ...] in clip-local beats where 0 is the clip start. Values are in the parameter own normalised units, the same ones set_parameter takes, so read min and max with ``describe`` rather than assuming 0..1. | |
| verify | No | True samples the stored envelope back and compares it against the curve that was generated, at the cost of one extra read. | |
| exponent | No | How hard the non-linear shapes bend. 1.0 is effectively linear and higher is steeper. Ignored by 'linear' and 'hold'. | |
| parameter | Yes | LOM path to the DeviceParameter the envelope belongs to, e.g. 'song.tracks[0].mixer_device.volume' for track volume or 'song.tracks[0].devices[1].parameters[3]' for a device knob. | |
| resolution | No | Step in beats at which the curve is written out between breakpoints, so 0.0625 lays a point every sixteenth of a beat. Finer follows the shape more closely and writes more points; ignored for 'hold', which needs no intermediate points. | |
| clear_first | No | True resets the parameter envelope before writing, so the result matches ``points`` exactly. False overlays new breakpoints onto earlier points and mixes the two. | |
| interpolation | No | Shape between consecutive breakpoints. 'linear' ramps straight, 'hold' steps at each breakpoint and stays flat between them, and the other three bend the ramp using ``exponent``. | linear |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||