read_clip_notes
Read-onlyIdempotent
Read MIDI notes from a Session clip, filter them by beat range, or get a quick count for large clips without transferring every note.
Instructions
Read MIDI notes of a Session clip, query a specific window, or count notes.
Returns:
Dictionary containing notes, count, window parameters, and validation report.
Note:
Times and positions are expressed in clip-local beats. Muted notes are included
and carry ``mute: true``. ``time_span`` is a length in beats, not an end beat:
beats 24 to 32 is ``from_time=24, time_span=8``.
Windowing and counting keep a small question small. A single drum clip of 384
notes comes back as 57k characters, past the tool-result cap, so a survey across
59 clips cannot be a full read of each. The LOM has no ``note_count`` on ``Clip``
at all, so a count taken out here means transferring every note to measure it.
``count_only=True`` counts inside Live and carries back one integer.
With ``count_only`` there is nothing to validate, so ``check`` is ignored. With a
window, ``check`` sees the window and not the clip.
Returned notes are sorted by time, then pitch. Live hands its notes back ordered
by pitch, which is the one order a musical instruction never means: "the third
note", "every other note" and "the last note" are all about when a note sounds.
Four notes written at beats 0, 1, 2, 3 with pitches 72, 60, 67, 62 come back 60,
62, 67, 72, so taking every other entry off the raw list picks alternating pitches
rather than alternating beats, silently and plausibly. For Live's own order call
``get_notes_extended`` through ``lom_call``.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| check | No | True runs validation over the notes that came back and reports what it found. Ignored when count_only is true, since there are no notes to check. | |
| track | Yes | Track index in song.tracks, counted from 0. | |
| from_time | No | First beat of the window to read, clip-local, where 0 is the clip start. Omit to read from the beginning. | |
| time_span | No | Length of the window in beats, not the beat it ends on: beats 24 to 32 is from_time=24, time_span=8. Omit to read to the end. | |
| count_only | No | True counts the notes inside Live and returns the number without transferring them, which is the way to ask about a large clip. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||