write_clip_notes
Destructive
Write MIDI notes into Ableton Live Session clips. Replace existing content or append notes, then verify the written result by reading it back.
Instructions
Write MIDI notes into a Session clip.
Returns:
Dictionary containing write confirmation, validation reports, and optional diff.
Note:
Times are in beats and clip-local, so beat 0 is the clip's own start. ``replace``
(the default) makes the clip match the list given; Live's own note writing appends,
so without it a second write duplicates a melody (measured: 63 + 23 = 86 notes). Ask
for ``append`` by name to layer onto an existing performance. An empty list with
``replace`` empties the clip but keeps its length, loop and envelopes; delete_clip
takes all of them.
A list straight from ``read_clip_notes`` can be written back: the keys in
:data:`~live_maestro.music.notes.TOLERATED_NOTE_KEYS`, such as Live's ``note_id``,
are dropped and reported as ``input_keys_ignored``, and every other unrecognised key
is an error. ``pitch``, ``start_time`` and ``duration`` are never defaulted, so a
list spelled with ``pos``/``dur`` is refused before anything is sent instead of
becoming sixteenths stacked on beat 0.
Times and durations do not come back bit-identical. They return with a deviation in
both directions, about 4e-7 relative and reproducible to every digit across runs: a
sent 0.29 reads back as 0.29000010406260407, a sent 0.18 as 0.17999994796869798 and
a ``start_time`` of 2.29 as 2.290000104062604, while a duration of 0.5 comes back
exactly. The cause is not established: it is neither a tick grid of 96, 192, 480
or 960 per quarter, nor a single float32 conversion (float32 of 0.29 is
0.28999999). At 124 BPM the error is around
50 nanoseconds, so it matters only for comparison: never test a note time for
equality. The diff run here uses a tolerance, which is why it reports ``0 changed``
for values that differ in the seventh decimal.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | 'replace' updates the clip content to match exactly this note list. 'append' adds to what is there, which layers new notes onto existing ones. | replace |
| 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. | |
| notes | Yes | The notes to write into the clip. Each item declares its own fields, and the item schema carries their units. | |
| 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. | |
| verify | No | True reads the notes back and reports the difference against what was asked for, at the cost of one extra read. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||