transpose_clip
Shift the pitch of a MIDI or audio clip by a set number of semitones, with relative moves that keep repeated transpositions climbing. Handles out-of-range notes via error, clamp, or drop so the clip stays recoverable.
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 |
|---|---|---|---|
| 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. | |
| track | Yes | Track index in song.tracks, counted from 0. | |
| 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 | |||