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.

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

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

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.

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

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.

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.

Roll back the most recent mutation.

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 new track. kind ∈ {audio, midi, folder, submix, automation}.

Delete a track by id.

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

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.

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

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

Set the project key.

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

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.

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

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.

Create an empty MIDI clip on a track.

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.

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.

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).

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

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.

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

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.

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

Delete a clip by id.

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

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

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

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

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.

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

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

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.

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.

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.

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 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}.

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.

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.

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 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.

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 per-track stems. NOT YET IMPLEMENTED.

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.

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

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).

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

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.

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.

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

Type a string of text into the focused window.

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

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

Return current screen resolution.

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

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.

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

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 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.

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 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.

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.

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.

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

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.

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

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

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 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 genre conventions: BPM range, time signature, key tendency, instruments, form, hallmark progressions. Without args, lists all 22 genres.

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.

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 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 10 codified voice-leading rules + scoring guidance.

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

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

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

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.

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'.

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

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.

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.

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.

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).

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.

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.

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.

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).

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.

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.

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.'

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 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.

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.

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.

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.

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.

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.

List all known reference songs in the curated database.

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

Restore a previously-saved snapshot as the active Edit.

List all saved snapshots in this session.

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

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

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.

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

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.

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').

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.

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

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 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 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).

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).