read_automation
Read-onlyIdempotent
Sample a clip's automation envelope into evenly spaced values to inspect the curve, beat range, value range, and whether automation exists. Read automation data from Session clip parameters for verification.
Instructions
Sample a clip envelope into a list of values and report what it found.
Reads the curve by evaluating it at ``points`` positions, so the answer is a
sampling of the envelope rather than the breakpoints that define it.
Returns:
Dictionary with the sampled values, the beat range they cover, the value
range they span, and flags saying whether an envelope exists at all.
Note:
Automation lives in Session clips, so an Arrangement clip has none to read.
als_read is the way to see breakpoints in a saved project instead.
Use write_automation to lay a curve down and clear_automation to remove one.
A flat result with an envelope flag of false means nothing is automated on
that parameter, which is not the same as an envelope holding the parameter's
current value.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Last beat to sample, clip-local. Omit to sample to the end of the clip. | |
| slot | Yes | Clip slot index in track.clip_slots, counted from 0. A slot index is the scene the clip sits in, so slot 2 is the third scene down. | |
| start | No | First beat to sample, clip-local, where 0 is the clip start. Omit to start just past beat 0, which steps over the guard that keeps a sample off the envelope edge. | |
| track | Yes | Track index in song.tracks, counted from 0. | |
| points | No | How many evenly spaced samples to take across the range. Clamped to 2..512. This is the resolution of the answer, not of the stored envelope, which keeps whatever breakpoints it was written with. | |
| 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. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||