Audio Tools Reference

Decode an audio file (MP3, WAV, FLAC) and create a new track in the session.

Example prompt: load /path/to/file.wav

Returns: track_id, duration_sec

Add a new empty track to the session.

Example prompt: add an empty track called "drums"

Returns: track_id

Remove a track. Does not delete the source file on disk.

Example prompt: remove track 2

Returns: node_id

Create an exact copy of a track (same clips, gain, pan, effects). The duplicate is appended after all existing tracks.

Example prompt: duplicate track 1

Returns: node_id

Rename a track.

Example prompt: rename track 2 to "guitar"

Returns: node_id

Mute or unmute a track. Muted tracks produce silence in the mix.

Example prompt: mute track 3

Returns: node_id

Solo or un-solo a track. When any track is soloed, only soloed tracks play in the mix.

Example prompt: solo the vocals

Returns: node_id

Set the stereo pan of a track. -1.0 = full left, 0.0 = centre, 1.0 = full right.

Example prompt: pan track 2 hard left

Returns: node_id

Move a track's clips forward or backward in time. Positive offset_sec moves later, negative moves earlier (clamped to 0).

Example prompt: move track 2 two seconds later

Returns: node_id

Offline-render the selected tracks together and add the result as a new mixed track. track_indices selects which tracks to include.

Example prompt: mix tracks 1 and 2 into a new track

Returns: node_id

Remove a time range. Audio after the cut point shifts left.

Example prompt: cut from 1:30 to 2:00 on track 1

Returns: node_id

Copy a time region to the clipboard.

Example prompt: copy the section from 0:30 to 1:00

Returns: duration_sec of copied region

Insert clipboard contents into a track. Audio shifts right at the insert point.

Example prompt: paste at 2:00 on track 1

Returns: node_id

Remove silence from the start and/or end of a track.

Example prompt: remove the silence at the start of track 1

Returns: node_id, trimmed_start_sec, trimmed_end_sec

Insert a gap of silence at a position. Audio shifts right.

Example prompt: add 2 seconds of silence at 0:30

Returns: node_id

Reverse a region (or the full track).

Example prompt: reverse track 1

Returns: node_id

Zero out audio samples between start_sec and end_sec on a track.

Example prompt: silence 0:10 to 0:12

Returns: node_id

Duplicate the audio region [start_sec, end_sec) on a track N additional times, \ appending copies after the original buffer.

Example prompt: repeat 0:00-0:04 three more times

Returns: node_id

Split a clip into two at the specified time position. Both resulting clips reference the same source file with adjusted offsets.

Example prompt: split track 1 at 1:30

Returns: node_id

Invert (negate) audio polarity on a track, optionally within a time range.

Example prompt: invert the polarity of track 2

Returns: node_id

Apply a static dB gain to a region of a track. Range: −60 to +12 dB.

Example prompt: boost the vocals by 3 dB

Returns: node_id

Set the overall gain level for an entire track.

Example prompt: set track 2 gain to -3 dB

Returns: node_id

Normalize a track to an integrated LUFS target or true peak limit.

Example prompt: normalize to -14 LUFS for Spotify

Returns: node_id, applied_gain_db

Common targets: −14 LUFS Spotify/YouTube, −16 LUFS Apple Podcasts, −23 LUFS broadcast.

Apply a fade-in or fade-out envelope. Curve options: linear, exponential, logarithmic.

Example prompt: add a 3-second fade-out

Returns: node_id

Set a per-clip volume automation curve. Provide (time_sec, gain_db) pairs and the engine linearly interpolates between them.

Example prompt: set a volume fade: track 0 clip 0, from 0s at -20dB to 2s at 0dB

Returns: node_id

Brick-wall limiter: hard-clip any samples exceeding ceiling_db. Prevents digital clipping.

Example prompt: limit track 1 to -1 dBFS

Returns: node_id

Apply a noise gate: audio below threshold_db is silenced. attack_ms and release_ms control how fast the gate opens/closes.

Example prompt: gate anything below -45 dB

Returns: node_id

Apply dynamic leveling: normalise each short window to a target RMS level. Reduces variation between loud and quiet passages.

Example prompt: even out the levels on track 1

Returns: node_id

Reduce harsh sibilant 's' and 'sh' sounds. frequency_hz sets where sibilance detection begins (default 7000Hz); threshold_db is the compression trigger level.

Example prompt: take the harshness off the s sounds

Returns: node_id

Find and remove silent regions in a track. threshold_db is the silence floor; min_silence_ms is the minimum gap duration to remove.

Example prompt: remove the long pauses

Returns: node_id

Apply a parametric EQ to a track using a chain of biquad peak filters. Specify frequency, gain (dB), and Q for each band.

Example prompt: boost the highs on track 1 by 3 dB at 8 kHz

Returns: node_id

Apply a dynamic compressor with configurable threshold, ratio, attack, and release. Uses an envelope follower for smooth gain reduction.

Example prompt: compress track 1: threshold -18 dB, ratio 4:1

Returns: node_id

Remove broadband noise via spectral subtraction (realFFT + overlap-add). Estimates the noise floor from a silent region and subtracts it from the signal.

Example prompt: reduce background noise on track 1

Returns: node_id

Apply Freeverb algorithmic reverb. room_size (0-1) controls reverb length, damping (0-1) controls high-freq decay, wet (0-1) is the wet/dry blend.

Example prompt: add a small room reverb

Returns: node_id

Add a single echo (delay + decay). delay_ms is the echo offset in milliseconds; decay (0..1) is the echo amplitude.

Example prompt: add a 300 ms echo

Returns: node_id

Apply a phaser effect using an all-pass filter chain with LFO sweep. rate_hz controls LFO speed; depth is the wet blend; stages sets the filter chain length (2-12).

Example prompt: add a slow phaser

Returns: node_id

Apply tremolo (LFO amplitude modulation). rate_hz controls oscillation speed; depth (0..1) controls modulation depth.

Example prompt: add tremolo at 5 Hz

Returns: node_id

Apply soft-clip distortion (tanh waveshaper) followed by a tone filter. drive > 1 increases gain before clipping; tone (0=dark, 1=bright) controls the output filter.

Example prompt: drive track 2 a little

Returns: node_id

Widen or narrow the stereo field using M/S processing. width=0 collapses to mono, width=1 is original, width=2 doubles the stereo width. Requires stereo track.

Example prompt: widen the stereo image

Returns: node_id

Reduce center-panned vocals using L-R channel subtraction (Karaoke effect). Works on stereo tracks; results depend on how centrally the vocals are mixed.

Example prompt: take the vocals out

Returns: node_id

Remove clicks and pops by detecting sample spikes (via median filter) and replacing them with interpolated values. threshold is the amplitude deviation that triggers detection.

Example prompt: remove the clicks

Returns: node_id

Apply a Butterworth low-pass filter to a track, removing frequencies above cutoff_hz.

Example prompt: roll off everything above 8 kHz

Returns: node_id

Apply a Butterworth high-pass filter to a track, removing frequencies below cutoff_hz.

Example prompt: high-pass at 80 Hz

Returns: node_id

Apply a notch (band-reject) filter to a track, attenuating frequencies near center_hz. q controls the width: higher Q = narrower notch.

Example prompt: notch out the 50 Hz hum

Returns: node_id

Change the duration without changing the pitch.

Example prompt: stretch track 1 to 4 minutes

Returns: node_id, new_duration_sec

Change the pitch without changing the duration. Set preserve_formants on voices so a shift sounds like the same person singing higher, not a chipmunk. Range: −12 to +12 semitones.

Example prompt: shift the vocals up 2 semitones

Returns: node_id

Resample a track to change playback speed without pitch preservation. factor > 1 speeds up (shorter duration), factor < 1 slows down (longer).

Example prompt: speed track 1 up by 10%

Returns: node_id

Resample a track to a different sample rate using linear interpolation. Common rates: 22050, 44100, 48000, 96000.

Example prompt: resample track 1 to 44.1 kHz

Returns: node_id

Detect BPM, musical key, integrated loudness (LUFS), true peak, and transient count.

Example prompt: analyze track 1

Returns: bpm, key, loudness_lufs, peak_dbfs, transient_count

Warp a track in time so its beats land on a target grid, without changing the pitch. Each segment between beats is stretched by its own ratio in one pass, so there is no seam at the beats. Get source_beats from analyze_track.

Example prompt: find the beats, then warp this onto a steady grid

Returns: node_id

Compute the FFT magnitude spectrum of a track region.

Example prompt: show me the spectrum of track 1

Returns: frequency/magnitude data

Analyse a track and return the time ranges of silent regions.

Example prompt: where are the silent bits?

Returns: list of {start_sec, end_sec}

Run Demucs stem separation on-device. Produces 4 tracks: vocals, drums, bass, other. Model: htdemucs (~80 MB). Processing: ~45 sec/min audio on CPU.

Example prompt: separate the stems on track 1

Returns: node_id, stem track IDs

First use downloads the model automatically. htdemucs_6s adds guitar and piano stems at ~2× the processing time.

Transcribe spoken audio using Whisper large-v3 on-device. Stores word-level timestamps in the session. Model: ~1.5 GB. Processing: ~4–8 min per 60 min on CPU.

Example prompt: transcribe track 1

Returns: node_id, word_count, language

First use downloads the model automatically. CoreML (macOS) and CUDA significantly reduce processing time.

Synthesize a tone (sine, square, sawtooth, or triangle wave) and add it as a new track.

Example prompt: generate a 440 Hz sine for 5 seconds

Returns: track index

Generate a noise track (white, pink, or brown/Brownian noise) and add it as a new track.

Example prompt: generate 3 seconds of pink noise

Returns: track index

Convert a stereo (or multi-channel) track to mono by averaging all channels.

Example prompt: make track 1 mono

Returns: node_id

Convert a mono track to stereo by duplicating the channel to both L and R.

Example prompt: make track 1 stereo

Returns: node_id

Fork the current node to create an independent branch. The fork becomes the new head.

Example prompt: fork the session and call it "take-2"

Returns: node_id

Move the session head to an earlier node. Does not delete any nodes.

Example prompt: revert to before the reverb

Returns: node_id

Generate a diff between two nodes: tracks added/removed, gain changes.

Example prompt: compare the current version with the one before normalization

Returns: tracks_added, tracks_removed, tracks_changed

Apply a computed diff from compare_nodes to the current session.

Example prompt: (used internally by the agent)

Returns: node_id

Set a human-readable label on the current head node.

Example prompt: name this state "final mix"

Returns: node_id

Add a named point marker or region annotation to the timeline.

Example prompt: mark the chorus at 1:05

Returns: annotation_id

Import Audacity-format label text into the session as annotations. Format: each line is 'start_sec TAB end_sec TAB name'.

Example prompt: import these Audacity labels

Returns: node_id

Export session annotations as Audacity-format label text (start_sec TAB end_sec TAB name, one per line).

Example prompt: export the markers as labels

Returns: label text

Render the full session to WAV, FLAC or MP3. FLAC is lossless — identical audio, roughly half the size. MP3 is lossy but plays anywhere; bitrate defaults to 192 kbps.

Example prompt: export to /Users/me/Desktop/final.wav

Returns: path, duration_sec, peak_dbfs, sample_rate

Render a preview WAV to a temp file. Valid for the current app session.

Example prompt: (used internally for playback)

Returns: path

Export selected tracks as individual WAV files to a directory.

Example prompt: export tracks 1 and 2 as separate files

Returns: list of exported paths