Generate an arpeggio over a chord. Returns notes for the given length. direction ∈ {up, down, up_down, down_up, random, octave_alternate}. rate ∈ {quarter, eighth, sixteenth, triplet}. octaves controls how many octaves the cycle spans.

Produce a section list for a song. genre selects characteristic form; target_length_seconds + tempo set total bars; energy_curve shapes the intensity pattern. Returns sections with bar counts, roles, and an energy 0..1 the composer can use to gate layers / set velocities.

Place an audio file as a clip on a track. warp_mode controls time-stretch behavior. Optional clip-level gain (dB), fade in/out (beats), and offset_in_source (beats — skip the first N beats of the source file, useful for trimming silent intros).

Compare two audio files: returns LUFS / peak / DR diffs and a per-band spectrum diff in dB. Positive numbers mean file_a is louder/brighter than file_b in that dimension.

Detect the musical key of an audio file. Returns root note + mode (major/minor) with confidence 0..1. Uses chromagram + Krumhansl-Schmuckler key profiles. Reliable on tonal pop/jazz; less reliable on percussion-heavy or atonal material.

Detect the BPM of an audio file via onset autocorrelation. bpm_range bounds the search (default 60..180). Returns a single BPM with confidence 0..1. Works well on EDM/pop loops with a kick on every beat; less reliable on free-tempo or sparse music.

Measure integrated LUFS, true peak (dBTP), and dynamic range (LRA) for an audio file using ffmpeg's loudnorm filter. Reference targets: Spotify -14 LUFS, Apple -16, broadcast -23. True peak should stay under -1.0 dBTP.

Return RMS energy per frequency band. bands defaults to a 10-band log-spaced layout (sub, low, low-mid, mid, hi-mid, presence, brilliance, air). Useful for 'compared to my reference, this song is 4 dB heavier in the low-mid region.'

Add an automation lane to a track. target ∈ {'volume', 'pan', 'plugin/<plugin_id>/'}. points = [{beat, value, curve?}]. Replaces any existing lane on the same target.

Remove all automation lanes from a track, or just the lane on a given target.

Convenience: ramp a target from start_value to end_value between start_beat and end_beat. shape ∈ {'linear', 'exp_in', 'exp_out', 'sine'}. exp_in starts slow then speeds up; exp_out is the inverse; sine is a smooth S-curve. Appends to an existing lane on the same target if one exists, otherwise creates a new lane.

List automation lanes on a track (or all tracks if track_id omitted).

Add an auxreturn plugin to a track so it receives audio from the given bus number (0..15). Pair with send_add(bus_num=N) on source tracks for parallel routing — e.g. drum tracks all send to bus 0, aux-return track applies a single reverb.

Generate a bassline under a chord progression. feel ∈ {pump, walking, half_time, sub, octave_jumps, dub}. Each chord lasts chord_duration_beats. Roots are the chord-root MIDI pitches (typically octave 2-3).

Create a submix / aux track other tracks can route to. kind ∈ {submix, folder}.

Route a track's output to a bus instead of master. Stack drums onto a 'Drum Bus' for one comp/EQ.

Clone a clip onto the same track at start_beats + offset_beats. Returns the new clip_id. Notes are deep-copied for MIDI clips.

List clips on a track (or all tracks). Returns id, kind, name, start, length, plus per-clip gain/fade/offset for audio clips.

Shorthand: change a clip's start_beats. Length unchanged.

Delete a clip by id.

Change a clip's length. anchor='start' (default) keeps start_beats fixed and moves the right edge. anchor='end' keeps the right edge fixed and moves start_beats so total duration changes from the left.

Modify any field on an existing clip. Pass only fields you want changed. For AudioClip: name, start_beats, length_beats, gain_db, fade_in_beats, fade_out_beats, offset_in_source_beats, warp_mode. For MidiClip: name, start_beats, length_beats, gain_db.

Dispatch one of jazz/synthwave/lofi generative composers AND revert in Waveform with one call. Avoids the compose-then-manually-revert dance during iteration.

Djent track using REAL VST3 instruments + amp/cab simulators (sforzando + Karoryfer Emilyguitar SFZ → The Anvil drive → Mercuriall Metal Area amp → TSC cab) instead of synthetic 4OSC. Returns a manual_step_required note explaining you must load the SFZ in sforzando once after opening the project — sforzando state isn't preserved in our .tracktionedit writer yet.

Generate a progressive metal / djent instrumental in B minor. Form: intro → riffA → riffB → breakdown → riffA2 → buildup → solo (8 bars) → riffFinal → outro. Tracks: drums (polyrhythmic 3-3-2 kicks), bass, dual rhythm guitars panned hard L/R for the wall, lead solo over solo section, atmospheric pad. ~140 seconds at 110 BPM.

Build a song bottom-up from composition primitives — the recipe demonstrating arrangement_plan + progression_generate + voice_lead + drum_pattern + bassline_generate + arp_pattern + melody_generate + motif_develop wired together. Genre selects drum patterns, bass feels, and mix-balance reference. energy_curve drives velocity scaling per section.

Generate a jazz/jaunty track with authentic walking bass (7-pattern Paul Chambers vocabulary), Charleston-rhythm Rhodes comping, and Salamander Grand Piano lead treated like a vocal (call/response motifs, vocal range, dynamic phrasing). Drums comp for the soloist (ghost rim shots on piano off-beats, phrase-end fills, sparse ride on solo phrases). Section-wide ensemble dynamics and per-section bass feels (two-feel for heads, walking for blowing, anticipations into the bridge).

Generate a UNIQUE lofi track on every call. Unlike the old compose_lofi_track which hardcoded everything, this one uses progression_generate, arrangement_plan, drum_pattern, melody_generate, and bassline_generate primitives. Each seed produces a meaningfully different song: different chords, section layout, drum density, melody contour, bass feel, and tempo (within lofi range).

Generate a complete lofi track .tracktionedit file: 4 tracks (drums, bass, keys, pad), Fmaj7-Am7-Dm7-Cmaj7 progression, real 808 drum samples, master FX bus. Bass / keys / pad presets are configurable so you can A/B sounds without editing the composer. Saves to the given path.

Generate a rainstorm ambient .tracktionedit: continuous rain bed, tiled wind/breeze layer, occasional distant-muffled thunder rumbles (lowpass + EQ + low gain). 60 BPM (1 beat = 1 second). No music.

Generate a UNIQUE synthwave track on every call. Drives progression_generate / arrangement_plan / drum_pattern / melody_generate primitives with seed-driven variation across tempo (100-128 BPM), key, form, chord progression, drum density, melody contour, and bass feel. Different seeds = meaningfully different songs.

Generate a 64-bar synthwave instrumental .tracktionedit at 110 BPM in A minor. Properly developed song form: intro → verseA → chorus → verseB (variation) → chorus2 (with counter) → bridge (new chord set + walking bass + descending arp) → chorusFinal (peak) → outro (progressive instrument drop with pad chord ring-out). Per-section chord progressions, bass feels (verse=half-time, chorus=8th pump, bridge=walking), and arp themes (verse / verseB syncopated / chorus pump / bridge descending). Showcases the full MCP toolset.

Run a composer N times with different seeds, saving each output to a numbered file. Returns the list of paths so you can render all and pick the best.

Gentle bus 'glue' compressor. amount 0..1 (0=barely-there, 1=noticeable).

Aggressive parallel-style compressor for drum-bus / NY-style smash. No params — preset values.

Click at screen coordinates. Use desktop_screenshot first to know what's where. button ∈ {left, right, middle}.

Press a single key or chord. Examples: 'enter', 'esc', 'ctrl+s', 'ctrl+shift+n', 'f5'. Sent to whatever window currently has focus.

Move the mouse to (x, y) without clicking.

Capture the current screen (or a region) to a PNG file under state/screenshots/. Returns the path. Use this to verify that a UI action had the expected effect before sending the next.

Return current screen resolution.

Type a string of text into the focused window.

Sleep for seconds seconds. Use sparingly; prefer screenshot-then-act.

Generate drum notes for a section. (genre, role) selects from a library of 50+ named patterns. role ∈ {verse, chorus, fill, intro, breakdown, outro, buildup}. density 0..1 scales note count (0.5 drops half the hats; 1.0 is the full pattern). length_bars tiles the pattern. Returns notes ready to drop on a Sampler track.

List all available (genre, role) patterns in the library.

Create a new empty Edit (song). Sets tempo, time signature, and key. Replaces the in-memory Edit; does not write to disk until edit_save or flush.

Export a chord-chart text file from the markers + tempo of the current Edit. format ∈ {lead_sheet, nashville}. Markers should be named with section labels (e.g. 'verse', 'chorus').

Export all MIDI clips in the current Edit to a Standard MIDI File (.mid). One MIDI track per Edit MIDI track. Format-1 SMF with the Edit's tempo + time signature in track 0. Drop into any DAW for editing/printing/learning.

Detailed structural dump of the current Edit. Heavier than edit_summary — includes every plugin's params, clip gain/fade/offset, automation lane counts, master chain. Use after edit_open to understand a song before mutating it.

Load an existing .tracktionedit file from disk into the model.

Serialize the current Edit to a .tracktionedit file. Sets the flush target.

Save a stem-mix copy of the current Edit: only named tracks audible, all others muted. Pass track_ids or track_names (list). Use in a loop to produce per-track stems for rendering.

Change the project tempo. preserve_pitch is informational (audio clips don't get pitch-shifted by this tool).

Return a JSON summary of the current Edit (tracks, clips, markers, tempo).

Transpose every MIDI note in the Edit by semitones. Audio clips are NOT pitch-shifted.

Return per-section velocity multipliers for a sections_plan. Apply uniformly to drums, bass, keys, lead notes so the whole ensemble breathes together (quiet intro, building verses, peak chorus/bridge, soft outro).

Add a high-pass filter at freq Hz to a track. slope is dB/oct (12, 18, 24).

Add a lowpass filter at freq Hz to a track for darkening/muffling.

Single-knob bright/dark EQ. brightness -1=dark, 0=neutral, +1=bright.

Write the current Edit to the previously-opened/saved .tracktionedit path. Use this between batches of mutations so Waveform (when open) sees a single, coherent update instead of mid-edit flicker.

Set the project key.

Drop a loop onto a track. mode='fit' time-stretches to song tempo, 'original' uses natural tempo. start_beats defaults to end of existing clips on that track. Auto-detects file duration.

Search Waveform's loop library. Optional filters: tempo (BPM, with tolerance), name (substring), bars (exact), min_bars, max_bars.

Drop a marker (verse, chorus, drop, etc.) at a beat position.

Replace the master chain with a named template. template ∈ {clean_pop, loud_edm, lofi_warm, cinematic_dynamic, podcast_voice, no_processing}. Each is an EQ + Comp + Limiter chain tuned for its target use case.

Generate a melody from a scale and contour. Returns notes (pitch/start_beats/length_beats/velocity) ready to drop into a MIDI clip. contour ∈ {arch, descending, ascending, wave, question_answer, static}. density ∈ {sparse, medium, busy}. Notes are rhythmically diverse — quarter, eighth, dotted, with rests — humanized for natural feel.

Create an empty MIDI clip on a track.

Snap note start times in a clip to the nearest grid division. Grid is in beats: 0.25 = 16th notes, 0.5 = 8ths, etc. Strength 0..1.

Add notes to an existing MIDI clip. Pass an array of {pitch, start_beats, length_beats, velocity?, colour?}. Pitch is MIDI 0-127. Channel is per-clip, set when the clip is created (not per-note).

Remove all notes from a MIDI clip.

Set a track's volume_db (and optional pan) to the genre+role reference from the MIX_BALANCE table. Use this once per track after creating it instead of hand-tuning levels. Genres: synthwave, lofi, edm, pop, hip_hop, cinematic, ambient. Roles: drums, kick, snare, hat, bass, sub_bass, lead, pad, keys, arp, counter, melody, ambience, fx. Returns the dB value applied.

Compare a rendered file against a genre's reference spectrum and return a per-band diff in dB plus a plain-English diagnosis ('low end is +4 dB hot vs synthwave reference; consider HP filter on bass'). Use after render to inform mix adjustments.

Set track volume (dB), pan (-1..1), mute, solo. Pass only the fields to change.

Transform a motif (set of notes) into a variation. transformation ∈ {transpose, invert, retrograde, augment, diminish, sequence_up, sequence_down}. transpose: shift by semitones. invert: mirror around axis_pitch. retrograde: reverse note order. augment: stretch durations by factor. sequence_up/down: transpose by semitones AND repeat.

Tell the user (via the event stream / preview UI) what the agent is about to do, in plain English. Call this before a batch of mutations so the user can follow along.

Add a plugin to a track's chain. For built-ins, pass the type name (e.g. '4OSC', 'Wavetable'). For external VSTs, also pass preset_path.

Add a Sampler-backed drum kit to a track. pads is a list of {midi_note, sample_path, name?, gain_db?, pan?, decay?}. Each pad becomes one SOUND mapped to a single MIDI note. Replaces the manual Sampler+sounds boilerplate in compose_lofi_track.

Add a MacroParameter (single 0..1 knob) to a plugin. Macros are the canonical Tracktion way to expose a single control that drives multiple underlying params via assignments.

Add a TRACK-LEVEL modifier (LFO/envelope/random/step_lfo) and assign it to a plugin parameter. Real Tracktion schema — wires both on the track AND on the plugin. depth: 0..1 (modulation amount). rate: Hz when rate_type=0, beat multiplier when rate_type=1 (default = beat-synced). shape ∈ {sine, triangle, square, saw}.

Add a built-in reverb to a track. type ∈ {plate, natural, non_linear}. All other params are normalized 0..1: size, decay, mix (wet amount), pre_delay, diffusion, definition, high_damp, low_damp, high_cut. Defaults to a tasteful 25% wet plate.

List third-party VST/AU plugins Waveform has scanned. Optional filters: kind ('instrument'|'effect'), format ('VST3'|'VST'|'AU'), manufacturer (substring), name (substring). Use the returned uniqueId as the type arg to plugin_add for VST3 instantiation.

Return the curated list of built-in instruments and effects available by name.

Remove a plugin from a track's chain by id.

Set a named parameter on a plugin in a track's chain.

Apply a base64 VST state blob (from plugin_state_capture) to an existing plugin in the in-memory Edit. Lets you copy one configured VST onto every other instance.

Read a saved .tracktionedit file and extract a VST plugin's base64 state blob by plugin_name (substring match) or unique_id. Used to copy a manually-loaded plugin's configuration (e.g. an SFZ loaded into sforzando) for re-use programmatically.

Invent a chord progression in a key and mode. Returns a list of chord dicts ({roman, root_note, root_midi, chord_pitches, quality}). Constraints: end_cadence ∈ {authentic, plagal, deceptive, half}; allow_borrowed enables modal interchange (bIII/bVI/bVII in major, V/VII for minor); style ∈ {pop, jazz, modal, synthwave, sad, uplifting} biases the chord palette.

List all known reference songs in the curated database.

Look up musical hints for a song. Pass name (one of the keys in REFERENCE_SONGS) OR genre to list all references in that genre. Returns BPM, key, form, energy curve, signatures the composer can use as inputs.

Get the target spectral profile (RMS dB per log-spaced band) for a genre — a mastering-engineer-cheat-sheet target for what a well-mixed track in this genre should look like spectrally. Bands: 60 / 133 / 296 / 657 / 1460 / 3243 / 7204 / 16000 Hz.

Render the current Edit to a WAV file. NOT YET IMPLEMENTED — requires the wf-engine-helper binary which is not built. Use this tool to check status; it will return ok=False with a clear message so the agent can fall back to telling the user to render from inside Waveform.

Render the active edit to MP3, run the analyzer, and return both paths plus a balance/rhythm summary in one call. Replaces the manual revert→render→analyze chain.

Render per-track stems. NOT YET IMPLEMENTED.

Add an aux send (parallel routing) on a track. Tracktion routes via numbered buses 0..15 — pass bus_num explicitly, or pass dest_track_id to auto-pick a bus. Pair with aux_return_add on the receiving track. Emits a real element with proper slider position from amount_db.

List all saved snapshots in this session.

Restore a previously-saved snapshot as the active Edit.

Save the current Edit as a named snapshot for later A/B compare or recall.

Add a step clip (drum-machine grid) to a track. channels is a list of {midi_note, name?, velocity?} dicts — one per drum row. patterns is a list of pattern dicts: each pattern has rows parallel to channels, where each row has a pattern string of '0'/'1' steps and optional velocities list. step_length is duration of each step in beats (0.25 = 16th notes). Way cleaner than 80 individual MidiClip notes.

Set the project tempo in BPM (currently single global tempo; per-bar curves later).

Return arrangement layers: foundation, harmonic_glue, lead, counter_melody, atmosphere, ear_candy. Optional section returns per-section presence values for each layer (0..1) from LAYER_PRESENCE_BY_SECTION — drives the 'which layers should be active' decision.

Return the borrowed-chord (modal interchange) palette for major keys with usage notes.

Return cadence types — pattern, feel, and use. Optional name for one specific cadence.

Look up a named chord progression. Returns the Roman-numeral sequence + tags + examples. Without args, lists all 24 named progressions.

Return the 7 diatonic chords for a key/mode. Set sevenths=true for 7th-chord qualities (Imaj7, ii7, etc.) instead of triads (I, ii, etc.). Returns Roman numerals + the actual chord pitches (MIDI) for each.

Return genre conventions: BPM range, time signature, key tendency, instruments, form, hallmark progressions. Without args, lists all 22 genres.

Return the 13 songwriting heuristics (rule_of_3, contrast_required, etc.).

Return reference track-volume dB targets for a genre. Without args, returns the full table of (genre, role) → dB. With genre, returns the role→dB map for that genre. With genre AND role, returns the single dB value with a brief rationale. Roles: drums, kick, snare, hat, bass, sub_bass, lead, pad, keys, arp, counter, melody, ambience, fx. Genres: synthwave, lofi, edm, pop, hip_hop, cinematic, ambient.

List the 7 church modes with their characteristic degree, vibe, and typical use.

Return rhythm/meter info: time signatures, syncopation patterns, swing ratios. Pass time_sig for one specific time signature, syncopation for one pattern, or neither for the full reference.

Return the notes of a scale starting at a root. Returns MIDI numbers, note names, and interval pattern. mode is one of: major, natural_minor, harmonic_minor, melodic_minor_asc, ionian, dorian, phrygian, lydian, mixolydian, aeolian, locrian, major_pentatonic, minor_pentatonic, blues, whole_tone, half_whole_dim, whole_half_dim, chromatic, hungarian_minor, phrygian_dominant.

Search across all theory data by substring. Returns hits across scales, progressions, cadences, sections, forms, genres, heuristics. Useful for fuzzy questions like 'find anything related to lofi' or 'what mentions Phrygian'.

Return song section info: typical bar counts, role, dynamic level, valid next sections. Without args, lists all 15 section types (intro, verse, chorus, bridge, drop, etc.).

Return a macro song form layout. Without args, lists all 14 forms. With name, returns the section sequence, applicable genres, and total bar range.

Return the 7 surprise devices (truck_driver_modulation, deceptive_cadence, etc.).

Convert dynamic markings (ppp/pp/p/mp/mf/f/ff/fff) to MIDI velocity values, or look up all of them. Includes ACCENT_BUMP and GHOST_NOTE_MAX_VEL constants.

Return the 10 codified voice-leading rules + scoring guidance.

Return the last N tool calls made in this session for self-audit.

Add a new track. kind ∈ {audio, midi, folder, submix, automation}.

Delete a track by id.

Roll back the most recent mutation.

Voice the next chord with minimal voice motion from the previous voicing. Standard SATB-style voice leading: each voice moves the smallest interval to a target chord tone. Returns the new voicing as a list of MIDI pitches (same length as prev_voicing).

Bring Waveform's main window to the foreground. Required before desktop_key / desktop_type send keystrokes to the app.

Launch Waveform, optionally opening a .tracktionedit file. If Waveform is already running and a file path is provided, opens the file in the existing instance via OS file association (Waveform registers itself as the handler for .tracktionedit on install).

Find the installed Waveform binary on disk. Returns the path. Searches running processes first, then well-known install locations. Run this before launch/focus tools so the rest of the chain has a path to use.

Return the friendly-name → Tracktion-type-code map for built-in plugins. These codes are what the .tracktionedit XML expects in .

List available factory presets. Without args, returns the plugin category folders (4OSC, Compressor, etc.). With category, lists individual .trkpreset files in that category.

Read a .trkpreset XML and return its element contents — the type, parameters, and any nested elements. Use this to grab a known-good instrument or effect configuration to drop into a generated edit.

Politely close Waveform (sends WM_CLOSE to the main window).

Return the path to Waveform's settings directory (where Waveform.settings, knownPluginList64.settings, Templates/, etc. live). Useful for the planned settings-file editor surface.

Is Waveform currently running? Returns pid + exe path if so.