Get full project state: BPM, sample rate, playing status, track list, effects chain.

Control transport: play, stop, or toggle.

action: "play", "stop", or "toggle"

Set the playback position in beats.

Set the project tempo in BPM.

Set the playback loop region.

When enabled, playback loops between from_beat and to_beat. Set enabled=false to disable loop (region is kept but inactive).

from_beat: Loop start in beats. to_beat: Loop end in beats. enabled: Whether loop is active.

Add a timeline marker at a position.

Markers label song structure points (Verse, Chorus, Bridge, etc.). Visible on the timeline ruler.

position_beats: Position in beats. label: Marker text (e.g. "Verse 1", "Chorus", "Drop").

List all timeline markers with positions and labels.

Set the groove/shuffle (swing) amount for the project.

amount: 0.0 = straight (no swing), 1.0 = full swing. Typical values: 0.15 = light swing, 0.25 = moderate, 0.5 = strong triplet feel.

Set the A4 base frequency (concert pitch tuning).

frequency: A4 frequency in Hz. Default 440. Common alternatives: 432 (verdi), 415 (baroque), 466 (baroque organ).

Delete a timeline marker by index.

marker_index: Index from list_markers (0-based).

Move a timeline marker to a new position.

marker_index: Index from list_markers (0-based). position_beats: New position in beats.

Rename a timeline marker.

marker_index: Index from list_markers (0-based). label: New label text.

Set the repeat count on a timeline marker.

marker_index: Index from list_markers (0-based). repeat_count: 0 = infinite repeat, 1-16 = N repeats.

Set the project time signature (e.g. 4/4, 3/4, 6/8, 7/8).

numerator: Number of beats per bar (top number, e.g. 4, 3, 6, 7). denominator: Note value per beat (bottom number: 4=quarter, 8=eighth).

Add a time signature change at a specific position in the track.

Unlike set_time_signature (which sets the global default), this creates a SignatureEventBox on the timeline's signature track, allowing time signature changes mid-track (e.g. 4/4 → 3/4 → 4/4).

position_beats: Position in beats where the change occurs. numerator: Number of beats per bar (top number). denominator: Note value per beat (bottom number: 4=quarter, 8=eighth).

Returns the created signature event details.

Add a tempo (BPM) change at a specific position in the track.

Creates a ValueEventBox on the timeline's tempo track, allowing BPM automation mid-track (e.g. 120 BPM → 90 BPM → 140 BPM).

The tempo track uses normalized values (0..1) mapped to minBpm..maxBpm (default 60..240). This tool handles the conversion automatically.

position_beats: Position in beats where the tempo change occurs. bpm: Target BPM (60-240). interpolation: 'linear' for smooth transition, 'hold' for instant jump.

Returns the created tempo event and full tempo map.

List all tempo (BPM) changes on the timeline's tempo track.

Returns each tempo event with position (beats), BPM, and interpolation type. The tempo track uses normalized values mapped to minBpm..maxBpm (default 60..240).

List all time signature changes on the timeline's signature track.

Returns each signature event with position (beats), numerator, and denominator.

Delete a time signature change from the timeline.

Delete by position (closest match) or by index (0-based in sorted order). Pass index=-1 and position_beats=-1 to delete the last event.

position_beats: Position to match (closest event will be deleted). index: 0-based index in sorted order (-1 = use position match).

Returns updated signature event list.

Create a new audio track on the primary audio unit.

Create a new note/MIDI track on an audio unit.

unit_index: Audio unit index. Use -1 (default) for the primary audio unit, or specify an instrument AU index that contains a synth device (Vaporisateur, Nano, etc).

Rename an audio unit's instrument and optionally set its icon.

Instrument AUs have a label (display name) and icon (symbol) on their InstrumentBox. This sets both. The output AU (index 0) has no instrument and cannot be renamed.

unit_index: Audio unit index (must be >= 1, not the output AU). name: New display name (empty = skip). icon: New icon symbol (empty = skip, e.g. 'piano', 'guitar', 'drums').

Returns old and new name/icon.

Replace the instrument on an audio unit with a different MIDI instrument.

Uses ProjectApi.replaceMIDIInstrument — deletes the old instrument and creates a new one on the same AU. Only works for MIDI instruments (Nano, Vaporisateur, Soundfont, Apparat). Tape (audio player) cannot be replaced this way.

The AU must have a CaptureMidiBox (i.e. it was created as a synth/note instrument, not an audio track).

unit_index: Audio unit index (must be >= 1). new_instrument: Factory key — 'Vaporisateur', 'Nano', 'Soundfont', 'Apparat'.

Returns old and new instrument type.

Set volume of an audio unit in dB.

Uses VolumeMapper.decibel(-96, -9, +6) powerByCenter mapping. Range: -96 dB (mute) to +6 dB. 0 dB = raw 0.768.

Set panning of an audio unit. -1.0 = full left, 0.0 = center, 1.0 = full right.

Mute or unmute an audio unit.

Solo or unsolo an audio unit.

Download an audio file from a URL (e.g. Suno CDN) to local disk.

Bridges the gap between AI music generators (Suno, Udio) and the DAW: generate a track → get audio URL → download → import_audio_to_tracks. Without this, you need manual curl/wget outside the MCP pipeline.

Supports any HTTP(S) URL pointing to WAV/MP3/FLAC/OGG. Uses streaming download with timeout. Files saved to /tmp by default (or custom dir).

url: Direct URL to the audio file (e.g. Suno CDN audio_url from chirp_generate). filename: Output filename (default: derived from URL path). output_dir: Directory to save (default /tmp). Must exist.

Returns absolute file path, size, and suggested next step (import_audio_to_tracks).

Examples:

Download a Suno track

download_audio("https://cdn.suno.ai/abc123.wav")

Custom name

download_audio("https://cdn.suno.ai/abc123.mp3", filename="my_track.mp3")

Then import with stem splitting

import_audio_to_tracks("/tmp/my_track.mp3", mode="bs6")

Load an audio file (WAV/MP3/FLAC/OGG) into the DAW project.

file_path: Absolute path to the audio file on disk. If the file is inside the headless-daw/public/ directory, it will be fetched via URL (much faster for large files). Otherwise loaded via base64. name: Optional display name (defaults to filename).

Create a new instrument audio unit with a Tape device and an audio track.

This is required for audio playback — the Tape device reads audio regions and outputs sound. The instrument AU is connected to the output AU's bus.

name: Display name for the instrument (default "Tape"). Returns the unit_index and track_index for use with place_audio_region.

Create a new instrument audio unit with a synthesizer device and a note track.

Unlike create_instrument_track (which creates a Tape device for audio playback), this creates a MIDI synthesizer that responds to notes from create_note.

synth_type: 'vaporisateur' (subtractive synth, default), 'nano' (simple synth), 'soundfont' (SF2 player, needs sample), 'apparat' (FM synth). name: Display name for the instrument.

Returns unit_index and track_index for use with create_note.

Place a previously loaded audio sample as a region on a track.

sample_id: The ID returned by mcp_opendaw_load_audio. unit_index: Audio unit index (default 0). start_beat: Beat position to place the region. track_index: Track index within the audio unit (default 0).

NOTE: The audio unit must be an instrument AU with a Tape device. Use mcp_opendaw_create_instrument_track first if no instrument AU exists.

Start the audio engine (AudioWorklet) after setting up tracks and regions.

Call this AFTER loading audio, creating tracks, and placing regions — but BEFORE playback or effects. The engine serializes the current project state into the AudioWorklet processor, so all boxes must exist first.

List all available audio and MIDI effect types.

Add an audio effect to an audio unit's effect chain.

effect_type: One of the audio effect names from mcp_opendaw_list_effects: Compressor, Crusher, DattorroReverb, Delay, Fold, Gate, Maximizer, NeuralAmp (Tone3000), Reverb, Revamp, StereoTool, Tidal, Vocoder, Waveshaper, Werkstatt

Returns effect_index — use it with mcp_opendaw_set_effect_parameter.

Copy all effects from one audio unit to another, including parameter values.

Useful for applying the same vocal chain (EQ → compressor → reverb) to doubled vocal tracks.

src_unit: Source audio unit index. dst_unit: Destination audio unit index (effects appended to existing chain).

Returns list of cloned effects with their new indices.

Reorder an effect within an audio unit's effect chain.

Chain order matters: EQ → Compressor → Reverb sounds different than Compressor → EQ → Reverb. Use this to move effects to the desired position.

unit_index: Audio unit index. from_index: Current effect position (0-based). to_index: Target effect position (0-based).

Effects between from and to shift accordingly.

Create a parallel FX send bus from an audio unit.

Creates a NEW AudioBusBox (FX bus) with its own AudioUnitBox, then sends a copy of src_unit's signal to that FX bus via AuxSendBox. The dry signal continues to the main output unchanged — this is a parallel send, not a redirect.

After creating the send, add effects (Reverb, Delay) to the FX bus unit using add_effect(fx_unit_index, effect_type). The FX bus unit index is returned.

src_unit: Source audio unit index (the instrument sending signal). name: Name for the FX bus (e.g. "Reverb Bus", "Delay Bus"). send_level_db: Send level in dB (-∞ to +12). -6dB is a good starting point. routing: 'pre' (pre-fader) or 'post' (post-fader, default).

Returns send_index on src AU, and fx_unit_index (the new FX bus AU index for adding effects).

Workflow: create_instrument_track → create_send → add_effect(Reverb on fx_unit_index)

Set the send level for an existing aux send.

src_unit: Source audio unit index. send_index: Send index on the source AU (from create_send return). level_db: Send level in dB.

List all aux sends on an audio unit.

unit_index: Audio unit index to inspect.

Returns list of sends with: send_index, target_bus_name, send_level_db, routing.

Remove an aux send from an audio unit.

unit_index: Source audio unit index. send_index: Send index to remove (from list_sends).

Set the routing mode for an aux send (pre-fader or post-fader).

unit_index: Source audio unit index. send_index: Send index on the source AU. routing: 'pre' (pre-fader, before volume/pan) or 'post' (post-fader, default).

List all audio buses in the project (primary output + FX buses).

Returns bus index, name, enabled state, and the associated audio unit index.

Set the stereo pan for an aux send (-1.0 = full left, 0.0 = center, 1.0 = full right).

unit_index: Source audio unit index. send_index: Send index on the source AU. pan: Pan value from -1.0 (left) to 1.0 (right).

Enable or mute an audio bus (FX bus A/B comparison).

bus_index: Bus index from list_audio_buses (0 = primary output). enabled: True to enable, False to mute.

Remove an FX audio bus and its associated audio unit.

Provide either bus_index (from list_audio_buses) or fx_unit_index (from create_send). Cannot remove the primary output bus (index 0).

bus_index: Bus index to remove (must be > 0, i.e. not primary). fx_unit_index: Alternative — the FX AU index returned by create_send.

List all parameters of an effect on an audio unit.

unit_index: Audio unit index. effect_index: Effect position in the chain (0-based, from add_effect return).

Returns parameter names, current values, units, and ranges.

Get full state of an effect: enabled, minimized, sidechain, all parameters.

More detailed than list_effect_parameters — includes enabled/bypass state, minimized state, sidechain connection, and full parameter dump.

unit_index: Audio unit index. effect_index: Effect position in the chain (0-based).

Returns complete effect state snapshot.

Set a parameter on an audio effect.

unit_index: Audio unit index. effect_index: Effect position in the chain (0-based). parameter_name: Parameter name from mcp_opendaw_list_effect_parameters (e.g. "inputGain", "mix", "equation"). value: Numeric value for float params. For string params (like Waveshaper equation), pass the string as parameter_name=value pair — use parameter_name="equation" and value as a special case.

Examples: set_effect_parameter(0, 0, "inputGain", 12.0) # Waveshaper +12dB input set_effect_parameter(0, 0, "mix", 1.0) # 100% wet set_effect_parameter(0, 0, "equation", 0) # Use string_value for equation

Set a boolean parameter on an audio effect.

Covers device-specific boolean fields not exposed through the generic float setter:

• Compressor: lookahead, automakeup, autoattack, autorelease

• Gate: inverse

• Maximizer: lookahead

• StereoTool: invertL, invertR, swap

• NeuralAmp: mono

• Delay: freeTimeSync (if available)

unit_index: Audio unit index. effect_index: Effect position in the chain (0-based). parameter_name: Boolean field name (e.g. "lookahead", "automakeup", "inverse", "mono"). value: true or false.

Set an integer parameter on an audio effect.

Covers device-specific integer fields not exposed through the generic float setter:

• Vocoder: bandCount

• StereoTool: panningMixing

• Fold: overSampling

• Crusher: bits

• Delay: version (internal)

Note: device-specific tools (set_vocoder_band_count, set_fold_oversampling, etc.) are preferred when available. This is a generic fallback for any Int32Field.

unit_index: Audio unit index. effect_index: Effect position in the chain (0-based). parameter_name: Integer field name (e.g. "bandCount", "bits", "overSampling"). value: Integer value.

Set a string parameter on an audio effect (e.g. Waveshaper equation).

unit_index: Audio unit index. effect_index: Effect position in the chain. parameter_name: Parameter name (e.g. "equation"). string_value: String value (e.g. "hardclip", "tanh", "cubicSoft", "sigmoid", "arctan", "asymmetric").

Remove an audio effect from an audio unit's chain.

unit_index: Audio unit index. effect_index: Effect position to remove (0-based).

List all available MIDI effect types.

MIDI effects process note data before it reaches the instrument. They are inserted on the MIDI effect chain (au.midiEffects).

Add a MIDI effect to an audio unit's MIDI effect chain.

MIDI effects process note data before the instrument. They are chained on au.midiEffects (separate from audio effects on au.audioEffects).

effect_type: One of: Arpeggio, Pitch, Velocity, Zeitgeist, Spielwerk

unit_index: Audio unit index (must be an instrument AU, not output). Returns effect_index in the MIDI chain.

Remove a MIDI effect from an audio unit's MIDI chain.

unit_index: Audio unit index. effect_index: MIDI effect position to remove (0-based).

Get the MIDI effect chain for an audio unit.

unit_index: Audio unit index. Returns ordered list of MIDI effects with type, enabled state, and index.

List all parameters of a MIDI effect with current values.

unit_index: Audio unit index. effect_index: MIDI effect position in the chain (0-based).

Returns parameter names, values, units, and constraints.

Set a parameter on a MIDI effect.

unit_index: Audio unit index. effect_index: MIDI effect position in the chain (0-based). param_name: Field name (e.g. "semiTones", "rateIndex", "gate"). value: New value for the parameter. param_index: Alternative — set by field index instead of name (-1 = use name).

Returns old and new values.

Get full Vaporisateur synthesizer state: oscillators, LFO, noise, main params.

unit_index: Audio unit index (-1 = auto-detect Vaporisateur).

Returns:

• oscillators: [{index, waveform, volume, octave, tune}]

• lfo: {waveform, rate, sync, attack, decay, release}

• noise: {volume, attack, decay, release}

• main: cutoff, resonance, attack, release, filterEnvelope, decay, sustain, etc.

Set a parameter on a Vaporisateur oscillator.

osc_index: Oscillator index (0, 1). param_name: One of: waveform, volume, octave, tune. waveform: 0=Sine, 1=Triangle, 2=Saw, 3=Square volume: dB (-Infinity to +6) octave: integer offset tune: semitone offset (float) value: New value. unit_index: Audio unit index (-1 = auto-detect).

Returns old and new values.

List all parameters of the instrument connected to an audio unit.

unit_index: Audio unit index (-1 = auto-detect first non-master AU with an instrument).

Returns instrument type, all parameter fields with values, units, and constraints. Works with: Vaporisateur (cutoff/resonance/ADSR/etc), Tape (flutter/wow/noise/saturation), Nano (volume/release), Soundfont (presetIndex), MIDIOutput (channel), Playfield, Apparat.

Set a parameter on the instrument connected to an audio unit.

unit_index: Audio unit index (-1 = auto-detect first non-master AU with an instrument). param_name: Field name (e.g. "cutoff", "resonance", "attack", "flutter", "volume", "channel"). value: New value for the parameter. param_index: Alternative — set by field index instead of name (-1 = use name).

Works with any instrument type. Returns old and new values.

List all drum pads (samples) on a Playfield drum machine.

unit_index: Audio unit index (-1 = auto-detect Playfield).

Returns list of pads with MIDI note, enabled state, and effects.

Enable/disable a drum pad on a Playfield drum machine.

sample_index: Pad index (0-based). enabled: true to enable, false to mute the pad. unit_index: Audio unit index (-1 = auto-detect Playfield).

Add a drum pad to a Playfield drum machine.

midi_note: MIDI note number for this pad (36=C1, 38=D1, 42=F#1, etc). sample_name: Name for the sample slot. duration_seconds: Duration hint for the sample slot. unit_index: Audio unit index (-1 = auto-detect Playfield).

Returns the new pad index and MIDI note.

Delete an entire audio unit with all its tracks, effects, and sends.

Uses ProjectApi.deleteAudioUnit() — proper cleanup of all connected boxes. The primary output AU (index 0) cannot be deleted.

unit_index: Audio unit to delete (must be >= 1, as index 0 is the master output).

Get the full effect chain for an audio unit.

unit_index: Audio unit index.

Returns ordered list of effects with their type, enabled state, and index.

Create a MIDI note on a note track.

pitch: MIDI note number (60 = C4, 69 = A4). start_beat: beat position. duration_beats: note length in beats. velocity: 0.0-1.0. unit_index: Audio unit index (-1 = search all AUs for note tracks). track_index: Note track index within the AU.

If no clip exists on the track yet, one is auto-created. Notes are added to the first clip on the track.

Import a MIDI file and create note events on a note track.

Parses standard MIDI (.mid) files and creates note regions with all notes. Supports format 0 and 1. Ticks are converted to openDAW PPQN (960/quarter).

file_path: Path to .mid file (absolute or relative to MCP server). unit_index: Audio unit index with a note track (-1 = search all AUs). track_index: Note track index within the AU. offset_beats: Offset in beats to shift all notes (e.g. start at bar 2 = 4.0).

Returns note count and time range.

Transpose all notes by a number of semitones.

semitones: Positive = up, negative = down (e.g. +12 = octave up, -5 = perfect fourth down). unit_index: Audio unit index (-1 = all AUs with note tracks). track_index: Specific note track (-1 = all note tracks on the AU). region_index: Specific region index (-1 = all regions on the track).

Returns count of notes transposed and notes skipped (out of MIDI range 0-127).

Copy notes from one track/region to another track — MIDI layering and doubling.

Copies all notes from a source region to a destination track's first region. Optional transpose (semitones), time offset (beats), and velocity scaling.

Use cases:

• Layer drums: copy drum track to second track with different instrument

• Create harmony: copy melody +12 (octave) or +7 (fifth)

• Call-and-response: copy with time_offset to create echo

• Doubles: copy to same track position with slight transpose for thickening

source_unit_index: Source AU index. source_track_index: Source note track index. dest_track_index: Destination note track index. source_region_index: Source region (-1 = first region). dest_unit_index: Destination AU index (-1 = same as source). transpose: Semitone offset (-127 to 127, 0 = same pitch). time_offset: Beat offset for copied notes (0 = same position, 2 = two beats later). velocity_scale: Multiply velocity of copied notes (1.0 = same, 0.7 = quieter layer).

Returns count of notes copied.

Example:

Layer drums — copy track 0 to track 2

copy_notes_to_track(0, 0, 2)

Create octave harmony — copy melody +12

copy_notes_to_track(0, 3, 4, transpose=12, velocity_scale=0.7)

Echo effect — copy 2 beats later at half velocity

copy_notes_to_track(0, 0, 1, time_offset=2, velocity_scale=0.5)

Move notes from a source region to another track — copy + delete.

Copies notes from source region to destination track (auto-creating a region or appending to an existing one), then optionally deletes the originals. Useful for splitting material across tracks, reorganising arrangements, or moving a section to a different instrument.

Args: source_unit: Source audio unit index source_track: Source note track index source_region: Source region index dest_unit: Destination audio unit index dest_track: Destination note track index time_offset: Shift all moved notes by N ticks (0 = keep positions) transpose: Transpose all moved notes by N semitones (0 = no change) velocity_scale: Multiply velocity of moved notes (1.0 = unchanged, 0.8 = quieter, 1.2 = louder, clamped to 0-1) delete_source: If True (default), delete notes from source after copy. If False, behaves like copy_notes_to_track. dest_region: Destination region index (-1 = auto-create or append to last)

Returns: JSON with notes_moved, notes_deleted, source_region_cleared, and destination region info.

Double a melody at a parallel interval — thickening and harmonization.

Creates a copy of every note in the region shifted by the specified interval. Unlike copy_notes_to_track (chromatic transpose only), this supports named musical intervals and diatonic transposition (stays in key).

Same-region doubling (dest_track_index=-1) thickens the melody in place. Cross-track doubling (dest_track_index set) creates a separate layer — useful for assigning a different instrument to the doubled line.

Intervals (chromatic mode):

• octave: +12 semitones (classic doubling)

• double_octave: +24 semitones (organ/pipe effect)

• fifth: +7 semitones (power chord, open sound)

• fourth: +5 semitones (suspended, ambiguous)

• third: +4 semitones (major third — use diatonic for correct quality)

• sixth: +9 semitones (wide, romantic)

• unison: +0 semitones (thickening only, velocity difference)

Diatonic mode (diatonic=True): Uses scale-degree offsets instead of fixed semitones. A diatonic third in C major is +2 scale steps (C→E, D→F, E→G), producing the correct quality (major or minor third) depending on the scale degree. Requires root+scale.

velocity_scale: Doubled line velocity (0.8 = slightly quieter, classic). time_offset: Delay the doubled line (0 = parallel, 0.25 = slight delay).

unit_index: Source AU index. track_index: Source note track index. interval: Named interval (octave/double_octave/fifth/fourth/third/sixth/unison). region_index: Source region (-1 = first region). diatonic: If True, use scale-degree offset (requires root+scale). root: Scale root note (C, C#, D, ... B). scale: Scale name (major, minor, dorian, phrygian, etc.). velocity_scale: Velocity multiplier for doubled notes (0-2). dest_track_index: Destination track (-1 = same region, thickening in place). dest_unit_index: Destination AU (-1 = same as source). time_offset: Beat offset for doubled notes (0 = parallel).

Returns count of notes doubled.

Example:

Octave doubling — thickens melody in place

double_melody(0, 3, "octave", velocity_scale=0.7)

Diatonic thirds on separate track — classic harmony

double_melody(0, 3, "third", diatonic=True, root="C", scale="major", dest_track_index=4, velocity_scale=0.8)

Power-chord doubling

double_melody(0, 3, "fifth", velocity_scale=0.9)

Reverse the order of notes in a region — retrograde variation.

Swaps note positions so the last note becomes first and vice versa. Durations and velocities are preserved; only positions are mirrored.

unit_index: AU index. track_index: Note track index. region_index: Region index (-1 = all regions on the track).

Returns count of notes reversed.

Invert melody around a pitch axis — mirror reflection.

Each note's pitch is reflected around the axis: newPitch = 2*axis - oldPitch. Example: with axis=60 (C4), C4(60)→C4(60), D4(62)→Bb3(58), E4(64)→Ab3(56).

unit_index: AU index. track_index: Note track index. region_index: Region index (-1 = all regions on the track). axis: Pivot pitch for inversion (default 60 = C4). Notes equidistant from axis on opposite sides swap. Use the first note's pitch for tonal inversion.

Returns count of notes inverted and notes skipped (out of MIDI range).

Augment or diminish note durations — the fourth classical transformation.

Multiplies note durations by a factor. Combined with transpose, reverse, and invert, this completes the set of four fundamental motivic transformations used by Bach, Beethoven, and every composition teacher since.

• factor > 1.0: augmentation (longer notes, slower feel). 2.0 = double duration.

• factor < 1.0: diminution (shorter notes, faster feel). 0.5 = half duration.

• factor = 1.0: no change (useful for testing).

Think Beethoven 5th: the opening G-G-G-Eb motif returns augmented (twice as slow) in the recapitulation. Or Bach fugues where the subject appears in diminution (twice as fast) in the finale.

factor: Duration multiplier (0.25-4.0). 2.0 = augmentation, 0.5 = diminution. unit_index: AU index. track_index: Note track index. region_index: Region index (-1 = all regions on the track). mode: How to handle note positions — "scale" (default): multiply both duration AND position relative to region start. The entire phrase slows down or speeds up — notes stay in sequence. "stretch": multiply only duration, leave positions unchanged. Notes become longer/shorter but don't move — may overlap or leave gaps.

Returns count of notes augmented and notes skipped (duration too short/long).

Delete a note region from the timeline.

unit_index: Audio unit index (-1 = search all AUs). track_index: Note track index within the AU. region_index: Region index to delete (0-based).

Delete an audio region from the timeline.

unit_index: Audio unit index. track_index: Audio track index within the AU (type=2). region_index: Region index to delete (0-based).

List all note regions with position, duration, and note count.

unit_index: Audio unit index (-1 = all AUs). track_index: Specific note track (-1 = all note tracks).

Returns list of regions with: region_index, unit_index, track_index, position_beats, duration_beats, label, note_count.

List all audio regions with file name, position, and duration.

unit_index: Audio unit index. track_index: Specific audio track (-1 = all audio tracks).

Returns list of regions with: region_index, track_index, position_beats, duration_seconds, file_name.

Set fade in/out on an audio region.

Audio regions have a Fading object with four params:

• in: fade-in duration in seconds (0 = no fade-in)

• out: fade-out duration in seconds (0 = no fade-out)

• inSlope: fade-in curve (0.5 = linear, 0.75 = fast start, 0.25 = slow start)

• outSlope: fade-out curve (0.5 = linear, 0.25 = fast end, 0.75 = slow end)

Pass -1.0 for any parameter to skip changing it (keep current value).

unit_index: Audio unit index. track_index: Audio track index. region_index: Region index within the track. fade_in: Fade-in duration in seconds (-1 = skip). fade_out: Fade-out duration in seconds (-1 = skip). in_slope: Fade-in curve 0-1 (-1 = skip). out_slope: Fade-out curve 0-1 (-1 = skip).

Returns updated fade values.

Set gain (in dB) on an audio region.

Audio regions have a per-region gain control (Float32Field, decibel). Use this for trim automation or balancing clips within a track.

unit_index: Audio unit index. track_index: Audio track index. region_index: Region index within the track. gain_db: Gain in dB (0 = unity, -6 = half volume, +6 = double).

Returns updated gain value.

Quantize note positions to a grid division.

Snaps each note's start position to the nearest grid line.

division: Grid division — '1/4', '1/8', '1/16', '1/32', or '1/64'. unit_index: Audio unit index (-1 = all AUs). track_index: Specific note track (-1 = all note tracks). strength: 1.0 = full quantize, 0.5 = 50% (keeps some groove).

Returns count of notes quantized.

Duplicate a note region to a new position.

Copies the region and all its notes to offset_beats after the original. Useful for repeating patterns (e.g. duplicate 1-bar loop to bar 2).

unit_index: Audio unit index (-1 = search all AUs). track_index: Note track index within the AU. region_index: Region to duplicate (0-based). offset_beats: How far to shift the copy (in beats, e.g. 4.0 = next bar in 4/4).

Returns new region index.

Split a note region into two at a given beat position.

Creates a new region starting at split_beat containing all notes from that position onward. The original region's duration is trimmed to split_beat. Notes that straddle the split point are kept in the original region (they will play their full duration even if they extend past the trimmed region boundary — this matches DAW behaviour).

Use cases:

• Divide a long region into sections (e.g. split at bar 8 for verse/chorus)

• Cut silence off the end of a region

• Create variations: split, then modify one half

• Prepare for arrangement edits (move one half elsewhere)

unit_index: AU index. track_index: Note track index. region_index: Region to split (0-based). split_beat: Absolute beat position to split at (must be within region range).

Returns original and new region details.

Example:

Split region 0 at bar 8 (beat 32 in 4/4)

split_note_region(0, 0, 0, 32)

Merge two note regions on the same track into one.

Copies all notes from region B into region A's note collection, adjusting positions so they remain at their original absolute timeline position. Region A's duration is extended to cover both regions. Region B is deleted.

The regions do not need to be adjacent — if there's a gap between them, the merged region spans the full range (with silence in the gap).

Use cases:

• Join verse + chorus into one continuous region

• Consolidate split regions back together

• Merge separately-recorded MIDI takes

• Simplify arrangement before export

unit_index: AU index. track_index: Note track index. region_index_a: First region (keeps its identity, absorbs B's notes). region_index_b: Second region (deleted after merge).

Returns merged region details.

Example:

Merge regions 0 and 1 into one

merge_note_regions(0, 0, 0, 1)

Duplicate all notes within a region, shifting them after the last note.

Creates copies of every note in the region, shifted by (max(position+duration) - min(position)). This mirrors the DAW's native "duplicate notes" feature.

unit_index: Audio unit index (-1 = search all AUs). track_index: Note track index within the AU. region_index: Region whose notes to duplicate (0-based).

Returns count of duplicated notes and shift in beats.

List all note events within a region.

Returns each note with position (beats), duration (beats), pitch (MIDI 0-127), velocity (0-1), cent, and chance (0-100).

unit_index: Audio unit index (-1 = search all AUs). track_index: Note track index within the AU. region_index: Region to list notes from (0-based).

Returns list of notes sorted by position.

Edit properties of a single note within a region.

Pass -1 for any parameter to skip changing it (keep current value). Use list_notes first to find the note_index.

note_index: Index of the note in the region (0-based, sorted by position). unit_index: Audio unit index (-1 = search all AUs). track_index: Note track index within the AU. region_index: Region containing the note (0-based). position_beats: New position in beats (-1 = skip). duration_beats: New duration in beats (-1 = skip). pitch: New MIDI pitch 0-127 (-1 = skip). velocity: New velocity 0-1 (-1 = skip). cent: New cent offset in cents (-1 = skip). chance: New chance 0-100 (-1 = skip).

Returns updated note properties.

Delete a single note from a region.

note_index: Index of the note to delete (0-based, as returned by list_notes). unit_index: Audio unit index (-1 = search all AUs). track_index: Note track index within the AU. region_index: Region containing the note (0-based).

Returns remaining note count.

Delete a region from a track.

Removes the region and all its contents (notes for note regions, audio reference for audio regions, automation events for value regions).

track_index: Track index within the AU. region_index: Region to delete (0-based). unit_index: Audio unit index (-1 = search all AUs). region_type: 'note', 'audio', or 'value' (for filtering).

Returns remaining region count on the track.

Move a region to a new position on the timeline.

position_beats: New position in beats (e.g. 4.0 = start of bar 2 in 4/4). region_type: 'note' or 'audio'. unit_index: Audio unit index (-1 = search all AUs). track_index: Track index within the AU. region_index: Region to move (0-based).

Set the duration of a region.

duration_beats: New duration in beats (e.g. 4.0 = 1 bar in 4/4).

Mute or unmute a specific region without deleting it.

mute: true to mute, false to unmute.

Rename a region's label (display name).

label: New label text. unit_index: Audio unit index (-1 = search all AUs). track_index: Track index within the AU. region_index: Region to rename (0-based).

Set the color (hue) of a region or clip.

Regions and clips use an Int32Field 'hue' for color. The hue is an integer that maps to a color in the HSL spectrum (0-360). Use this to visually distinguish sections (e.g. red for choruses, blue for verses).

track_index: Track index within the AU. region_index: Region/clip to color (0-based). hue: Color hue (0-360, e.g. 0=red, 120=green, 240=blue). unit_index: Audio unit index (-1 = search all AUs).

Returns old and new hue values.

Get a quick project overview: BPM, time signature, track/AU/effect counts, total duration.

Single-call summary — lighter than get_project_state (no per-track detail).

Remove empty tracks from an audio unit (or all AUs).

Calls ProjectApi.compactTracks() — removes tracks with no regions. Useful cleanup after deleting regions or editing.

unit_index: Audio unit index (-1 = all AUs).

Set loop parameters for a note region.

Looping repeats the note pattern within the region. The region duration can be longer than the loop, causing the notes to repeat.

loop_beats: Loop length in beats (e.g. 4.0 = 1 bar in 4/4). Set to 0 to disable loop. loop_offset_beats: Offset within the event collection where the loop starts. event_offset_beats: Offset added to all note positions. unit_index: Audio unit index (-1 = search all AUs). track_index: Track index within the AU. region_index: Region to modify (0-based).