transpose_clip
Transpose an entire MIDI or audio clip by a relative semitone offset, reporting affected notes and handling out-of-range notes with error, clamp, or drop.
Instructions
Transpose a MIDI clip by note pitch or an audio clip via pitch_coarse.
Relative on both paths, so calling it twice with 2 moves the clip by 4 and there
is no absolute target to aim at. A MIDI clip has every note pitch rewritten. An
audio clip is repitched as a whole instead.
Returns:
Dictionary reporting the transposition, the notes affected, and any that hit
the range limit.
Note:
When to use: Shift the overall pitch of an entire clip by a constant semitone offset.
When NOT to use: Do not use transpose_clip to edit melody contours, re-voice chords,
or correct scale degrees. Use write_clip_notes instead. Do not use it for timing or
groove changes, which are handled by quantize_clip.
An audio clip is transposed by writing clip.pitch_coarse. The write is relative
there too, because the current value is read first and the semitones added to it,
so repeated calls do keep climbing. Live documents the bound as -48 to 48 but that
figure is not from a probe here. The read-back in the answer is the evidence for
any one write.
``out_of_range='clamp'`` and ``'drop'`` both lose information that
transposing back will not return: clamped notes have collapsed onto one
pitch and dropped ones are gone. Keep the default 'error' unless the clip
has been read out with read_clip_notes first.
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. | |
| semitones | Yes | How far to move the pitch, in semitones. 12 is an octave up, -12 an octave down. Relative to where the clip is now, not absolute. | |
| out_of_range | No | What to do with a MIDI note pushed outside 0..127: 'error' refuses the whole call and changes nothing, 'clamp' pins the note to 0 or 127 and keeps it, 'drop' discards it. Only 'error' leaves the clip recoverable by transposing back. | error |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||