Analyze the current project's audio and recommend a cleanup pipeline. Selects all audio first, exports it to a temp WAV, measures it, and returns peak/noise/clipping/click/silence-gap/dynamic-range diagnostics plus a recommendation for which pipeline to run next.

Find beats in the selected audio and add a label at each one.

Adds labels to the project's label track (creating one if needed) - call label_list afterward to read the detected beat positions.

Args: threshold_percent: Sensitivity threshold, 5-100. Lower finds more beats. Default: 65

Detect sounds separated by silence and add a label for each one (or for each silence gap, depending on label_type).

Adds labels to the project's label track (creating one if needed) - call label_list afterward to read the detected regions.

Args: threshold_db: Level below which audio counts as silence, -100 to 0. Default: -30.0 measurement: How to measure level - "peak", "avg", or "rms". Default: "peak" min_silence_duration: Minimum silence length to count as a gap, in seconds. Default: 1.0 min_label_interval: Minimum spacing between labels, in seconds. Default: 1.0 label_type: "before"/"after" (point at sound edge), "around" (region around each sound), or "between" (region between sounds - i.e. the silences). Default: "between"

Export raw sample values from the selection to a text/CSV/HTML file.

Args: path: Absolute output path. Extension determines format (.txt, .csv, .html). limit: Maximum number of samples to export, 1-1000000. Default: 100 units: Measurement scale - "dB" or "Linear". Default: "dB"

SAFE CLEANUP: Remove noise and artifacts WITHOUT changing loudness or dynamics. Use this when audio levels are already good and you just want to clean it up. Runs in background - returns a job_id immediately. Use check_pipeline_status to monitor.

Pipeline: DC offset removal > noise reduction (opt) > click removal (opt). NO compression, NO normalize, NO LUFS. Just clean.

Args: remove_noise: Apply noise reduction using the first 0.5s as a noise profile. Default: True. IMPORTANT: the first 0.5s should be room tone/silence if this is True. remove_clicks: Remove clicks/pops (useful for vinyl/old recordings). Default: False.

ONE-CLICK PODCAST CLEANUP. Runs in background - returns a job_id immediately. Use check_pipeline_status to monitor.

Pipeline: DC offset > noise reduction (opt) > compress 4:1 > safe LUFS loudness (-16 LUFS, Apple Podcasts target) with clip-safe fallback.

Args: remove_noise: Apply noise reduction using the first 0.5s as a noise profile. Default: True. IMPORTANT: the first 0.5s should be room tone/silence if this is True.

ONE-CLICK AUDIOBOOK MASTERING: ACX/Audible compliant processing. Runs in background - returns a job_id immediately. Use check_pipeline_status to monitor.

Pipeline: DC offset > noise reduction (opt) > compression 2.5:1 > RMS -20dB (safe, clip-checked) > peak cap -3.5dB. Targets ACX requirements: RMS -23 to -18 dB, peaks below -3 dB (capped at -3.5 for safety margin), noise floor below -60 dB.

Args: remove_noise: Apply noise reduction using the first 0.5s as a noise profile. Default: True. IMPORTANT: the first 0.5s should be room tone/silence if this is True.

ONE-CLICK INTERVIEW CLEANUP: Light-touch processing for dialogue and multiple speakers. Runs in background - returns a job_id immediately. Use check_pipeline_status to monitor.

Pipeline: DC offset > noise reduction 8dB (opt) > compression 2.5:1 > safe LUFS loudness. Lighter than podcast - preserves natural conversation dynamics.

Args: remove_noise: Apply noise reduction using the first 0.5s as a noise profile. Default: True. IMPORTANT: the first 0.5s should be room tone/silence if this is True.

ONE-CLICK VOCAL CLEANUP: Professional processing for singing and studio vocals. Runs in background - returns a job_id immediately. Use check_pipeline_status to monitor.

Pipeline: DC offset > noise reduction 10dB (opt) > compression 3:1 > presence EQ (treble+3dB/bass-1dB) > safe LUFS loudness.

Args: remove_noise: Apply noise reduction using the first 0.5s as a noise profile. Default: True. IMPORTANT: the first 0.5s should be room tone/silence if this is True.

ONE-CLICK LIVE RECORDING CLEANUP: Aggressive processing for noisy/field recordings. Runs in background - returns a job_id immediately. Use check_pipeline_status to monitor.

Pipeline: DC offset > click removal > noise reduction 12dB (always on) > compression 5:1 > safe LUFS loudness. Designed for live performances, field recordings, and noisy environments.

IMPORTANT: The first 0.5 seconds MUST be room tone / ambient noise for noise profiling.

ONE-CLICK MUSIC MASTERING: Professionally master your music track with genre-tuned settings pushed toward a real, published genre loudness target (not just a peak ceiling). Runs in background - returns a job_id immediately. Use check_pipeline_status to monitor.

Pipeline: click removal > noise reduction (opt, off by default for produced music) > compression (genre-tuned) > bass/treble sweetening (genre-tuned) > safe loudness push toward the genre's real integrated- LUFS target (EDM -7.5, hip-hop -9.0, pop -9.5, rock -10.5, classical/ acoustic -14.0 - see _mastering_pipeline's docstring for sources), clip-checked first and falling back to a peak-only reduction if hitting the target would clip. NOTE: if your track was already louder than its genre target going in, this pipeline can make it measure QUIETER, not louder - it targets a specific published loudness level, not "as loud as possible."

Args: style: Genre preset - "edm", "hiphop", "rock", "pop", "classical", "acoustic". Default: "edm" noise_reduce: Apply gentle noise reduction. Default: False

CREATIVE LO-FI EFFECT: Apply a vintage/lo-fi sound to your audio. Runs in background - returns a job_id immediately. Use check_pipeline_status to monitor.

Pipeline: bass/treble warmth > compression 2:1 > safe peak ceiling. NOTE: currently warmth + compression only, not the full frequency-cutoff filtering v3 had (see auto_lofi_effect's result "note" field for why).

Args: intensity: "light" (subtle warmth), "medium" (classic lo-fi), "heavy" (extreme tape sound). Default: "medium"

Check the status of a running cleanup pipeline.

Args: job_id: The job ID returned by an auto_ pipeline tool.

Cut the selected audio to clipboard. Select tracks and a time range first.

Copy the selected audio to clipboard. Select tracks and a time range first.

Paste audio from clipboard at the start of the current selection. Select the destination position first with select_region (or cursor_set).

Delete the selected audio, closing the gap (does not copy to clipboard). Select tracks and a time range first.

Split the selected clip(s) at the selection boundaries (in place, no new track). Select tracks and a time range first.

Trim audio outside the selection (delete everything except the selected region). Select tracks and a time range first.

Replace the selected audio with silence. Select tracks and a time range first.

Duplicate the selected audio into a new track. Select tracks and a time range first.

Split the selected audio into a new track at the selection boundaries, leaving the original track unchanged. Select tracks and a time range first.

Cut the selected audio to clipboard WITHOUT closing the gap - leaves silence where the audio was. Select tracks and a time range first.

Delete the selected audio WITHOUT closing the gap - leaves silence where the audio was. Select tracks and a time range first.

Split the selected audio into separate clips at detected silences. Select tracks and a time range first.

Join the selected clips into one clip. Select tracks and a time range first.

Non-destructively change one clip's pitch, without processing any audio - purely a playback-time transform. Reversible via clip_reset_pitch, or bake it in permanently with clip_render_pitch_speed.

Args: key: The clip's key, in "trackId:itemId" format (from track_get_info). semitones: Pitch shift in semitones (can be negative).

Revert a clip's pitch change made via clip_set_pitch.

Args: key: The clip's key, in "trackId:itemId" format.

Non-destructively change one clip's speed, without processing any audio. Reversible via clip_reset_speed, or bake it in permanently with clip_render_pitch_speed.

CONFIRMED LIVE: speed is a DURATION multiplier, not a playback-rate multiplier - new_duration = original_duration * speed. speed=2.0 makes the clip take twice as long on the timeline (plays slower/stretched), speed=0.5 makes it half as long (plays faster/compressed) - the opposite of what "speed" implies in most other software.

Args: key: The clip's key, in "trackId:itemId" format. speed: Duration multiplier. 1.0 = unchanged, 2.0 = twice as long (slower), 0.5 = half as long (faster).

Revert a clip's speed change made via clip_set_speed.

Args: key: The clip's key, in "trackId:itemId" format.

Permanently bake a clip's pitch/speed changes into its audio - use once you're happy with a non-destructive preview from clip_set_pitch/clip_set_speed. Cannot be undone via clip_reset_pitch/ clip_reset_speed after this - use edit_undo instead if needed right away.

Args: key: The clip's key, in "trackId:itemId" format.

Revert both pitch and speed changes on a clip in one call.

Args: key: The clip's key, in "trackId:itemId" format.

Automatically split one specific clip into multiple clips at its detected silence boundaries. Unlike edit_disjoin (which acts on whatever's currently selected), this targets one clip directly by key.

Args: key: The clip's key, in "trackId:itemId" format.

Automatically split every clip on the selected track(s) within a time range at detected silence boundaries. Select tracks first with select_tracks.

Args: start: Start time in seconds. end: End time in seconds (>= start).

Trim a clip's left or right edge inward by a delta in seconds, discarding that audio.

CONFIRMED LIVE: positive delta_sec shrinks the clip inward from the given edge, for both "left" and "right" - e.g. side="left", delta_sec=1.0 moves the clip's start forward by 1 second.

Args: key: The clip's key, in "trackId:itemId" format. side: "left" or "right". delta_sec: Positive shrinks the clip inward from this edge; negative grows it back outward (same convention as clip_stretch). min_clip_duration: Minimum duration the clip must retain, in seconds. Default: 0.

Grow or shrink a clip's left or right edge, revealing previously- trimmed audio when growing (or time-stretching if none remains).

CONFIRMED LIVE: same delta_sec sign convention as clip_trim, despite the name suggesting the opposite - positive delta_sec SHRINKS the clip inward from the given edge, negative GROWS it outward. e.g. to restore 1 second previously trimmed off the right edge, call with side="right", delta_sec=-1.0, not +1.0.

Args: key: The clip's key, in "trackId:itemId" format. side: "left" or "right". delta_sec: Positive shrinks inward, negative grows/reveals outward. min_clip_duration: Minimum duration the clip must retain, in seconds. Default: 0.

Find the nearest zero-crossing time to a given timestamp, for precise, click-free edit points - independent of the current selection, unlike select_zero_crossing.

Args: time: Time in seconds to search near.

Set a clip's color tag for visual organization.

Args: key: The clip's key, in "trackId:itemId" format. color_index: 0 (no custom color, inherit from track) to 9.

Undo the last edit. Fails cleanly if there's nothing to undo.

Redo the last undone edit. Fails cleanly if there's nothing to redo.

List available effects/plugins actually installed in this Audacity - builtin, VST3, Nyquist, etc. Each result's "title" is the effect_id to pass to apply-effect (or any effect_* tool's underlying command) - that path resolves by title with a fallback. Its "id" is the real internal PluginID, which add_realtime_effect REQUIRES instead - confirmed live that passing a title there fails ("cannot load the effect"), since RealtimeEffectService::addRealtimeEffect has no title fallback.

IMPORTANT (confirmed live): "category" only works for Builtin/Nyquist effects - third-party VST3 plugins are NOT auto-categorized by Audacity's discovery (they all come back with category "None", even real reverbs/delays like Valhalla's whole lineup). To find VST effects, use family="VST3" combined with a search keyword (plugin name or vendor, e.g. search="valhalla" for reverb/delay VSTs) - category filtering will silently miss them.

Args: category: Category substring filter (case-insensitive), e.g. "reverb", "eq", "compression", "distortion", "pitch", "fading". Only matches Builtin/Nyquist effects - see note above. family: Exact family filter: "Builtin", "VST3", "Nyquist", "LV2", "AudioUnit", or "Extension". Default: no filter. search: Title substring filter (case-insensitive). limit: Max results to return, 1+. Default: 100. Check "totalMatched" in the response to see if results were capped.

Normalize the selected audio to a target peak level.

Args: peak_level_db: Target peak level in dB (-145 to 0). Default: -3.0 remove_dc: Remove DC offset before normalizing. Default: True stereo_independent: Normalize L/R channels separately. Default: False

Capture a noise profile from the currently selected audio region. IMPORTANT: Select a region of pure noise (e.g. 0.5-2 seconds of silence/background noise) before calling this. This profile is used by the noise_reduction tool.

Sets NoiseReductionEffect's GetProfile flag and runs it - the same call the "Get Noise Profile" button in Audacity's Noise Reduction dialog makes.

Apply noise reduction to the selected audio. You MUST call get_noise_profile first on a region of pure noise, then select the audio you want to clean, then call this.

Args: sensitivity: Detection sensitivity (0.01-24). Default: 6.0 noise_gain_db: Amount of noise reduction in dB (0-48). Default: 12.0 frequency_smoothing_bands: Frequency smoothing bands (0-12). Default: 3

Apply dynamic range compression to the selected audio.

Args: threshold_db: Level above which compression starts (dB). Default: -12 ratio: Compression ratio (e.g. 4.0 = 4:1). Default: 4.0 attack_ms: Attack time in milliseconds. Default: 3.0 release_ms: Release time in milliseconds. Default: 100.0 makeup_gain_db: Makeup gain applied after compression (dB). Default: -3.0 knee_width_db: Soft-knee width in dB. Default: 6.0

Apply a limiter to prevent audio from exceeding a ceiling.

Args: threshold_db: Level above which limiting starts (dB). Default: -6 makeup_target_db: Output ceiling (dB) - the industry-standard streaming ceiling is -1.0. Default: -1.0 release_ms: Release time in milliseconds. Default: 20.0 knee_width_db: Soft-knee width in dB. Default: 2.0

Normalize audio to a target LUFS loudness. DANGER: can boost quiet/badly recorded audio by 20-30dB causing clipping - measure levels with auto_analyze_audio first. Targets: -16 LUFS (Apple Podcasts), -14 LUFS (Spotify/YouTube), -11 LUFS (loud masters).

Args: lufs_level: Target loudness in LUFS (-145 to 0). Default: -16.0 stereo_independent: Normalize L/R channels independently. Default: False dual_mono: Treat mono as dual-mono for correct LUFS measurement. Default: True

Remove clicks and pops from the selected audio (e.g. vinyl recordings).

Args: threshold: Click detection threshold (0-900). Higher = fewer clicks removed. Default: 200 spike_width: Maximum width of a click in samples (0-40). Default: 20

Adjust bass and treble frequencies with a simple tonal shaping tool.

Args: bass: Bass adjustment in dB (-30 to 30). Default: 0 treble: Treble adjustment in dB (-30 to 30). Default: 0 gain: Output gain in dB (-30 to 30). Default: 0

Amplify (or attenuate) the selected audio by a linear ratio.

Args: ratio: Amplification ratio (e.g. 2.0 = +6dB, 0.5 = -6dB). Range: 0.003162-316.227766. Default: 1.0 allow_clipping: Allow the result to clip instead of being limited. Default: False

Apply a fade-in to the selected audio. Select the region to fade first.

Apply a fade-out to the selected audio. Select the region to fade first.

Apply reverb to the selected audio.

Args: room_size: Room size percentage (0-100). Default: 75 pre_delay: Pre-delay in ms (0-200). Default: 10 reverberance: Reverberance percentage (0-100). Default: 50 hf_damping: High frequency damping percentage (0-100). Default: 50 tone_low: Tone low percentage (0-100). Default: 100 tone_high: Tone high percentage (0-100). Default: 100 wet_gain: Wet signal gain in dB (-20 to 10). Default: -1.0 dry_gain: Dry signal gain in dB (-20 to 10). Default: -1.0 stereo_width: Stereo width percentage (0-100). Default: 100 wet_only: Output only the wet (reverb) signal. Default: False

Change the pitch of the selected audio without changing tempo.

Args: semitones: Number of semitones to shift (negative = lower, positive = higher) use_high_quality_stretching: Use the higher-quality SBSMS algorithm (slower). Default: False

Extreme time-stretch effect (creates ambient/drone textures). Select audio first.

Args: stretch_factor: How much to stretch (1.0 = no change, 10.0 = 10x longer). Default: 10.0 time_resolution: Time resolution in seconds - smaller = better quality, slower (>= 0.00099). Default: 0.25

Reverse the selected audio. Select a region first.

Invert (flip phase) the selected audio. Useful for phase cancellation.

Repair a very short damaged section of audio (a few dozen samples at most). Select the damaged region first - it must be extremely short, or the effect will refuse to run.

Change tempo and/or pitch gradually across the selection (sliding time stretch).

Args: rate_change_start: Tempo change at start in % (-90 to 500). Default: 0 rate_change_end: Tempo change at end in % (-90 to 500). Default: 0 pitch_change_start_semitones: Pitch change at start in semitones (-12 to 12). Default: 0 pitch_change_end_semitones: Pitch change at end in semitones (-12 to 12). Default: 0

Remove DC offset from the selected audio without changing its peak level.

v4's "Remove DC offset" is invoked here as Normalize with only the DC checkbox on and level-normalization off (ApplyVolume=0) - confirmed the same parameter set as the already-verified normalize() tool, just with volume application disabled. Takes no parameters.

Apply a customizable fade to the selected audio.

Requires a SINGLE-clip selection - confirmed live that a selection spanning multiple clips triggers an unguarded assert/crash (Au3SelectionController::rightMostSelectedClipEndTime). A clean single-clip selection was also confirmed live to work correctly (isError: false, no crash). Normalize has the same "single clip only" precondition but fails gracefully with a normal error instead of crashing when violated - this one does not, so get the selection right.

Args: fade_type: "Up", "Down", "SCurveUp", or "SCurveDown". Default: "Up" mid_fade_adjust_percent: Adjusts the fade curve's midpoint, -100 to 100. Default: 0.0 units: Interpret start_level/end_level as "Percent" (of original) or "dB" gain. Default: "Percent" start_level: Level at the start of the fade. Default: 0.0 end_level: Level at the end of the fade. Default: 100.0

Find and shorten runs of silence in the selected audio.

Args: threshold_db: Silence threshold in dB, -80 to -20. Default: -20.0 minimum_silence: Minimum silence duration to detect, in seconds, >= 0.001. Default: 0.5 truncate_to: Duration to truncate silence down to, in seconds. Default: 0.5 compress_ratio: Percent to compress the remaining silence by, 0-99.9. Default: 50.0 independent_channels: Detect silence independently per channel. Default: False

Repair clipped (distorted) peaks in the selected audio.

Args: threshold: Clipping threshold percent, 0-100. Default: 95.0 gain_db: Gain adjustment in dB, -30 to 0. Default: -9.0

Crossfade the overlap between two adjacent, overlapping clips. Select the overlapping region across both clips first. Takes no parameters.

Crossfade the selected region between two overlapping tracks.

Args: curve_type: 0=Constant Gain, 1=Constant Power (1), 2=Constant Power (2), 3=Custom Curve. Default: 0

Apply a smoother, more natural fade-out than effect_fade_out to the selected audio. Takes no parameters.

Apply a notch filter to remove a narrow frequency band (e.g. mains hum) from the selected audio.

Args: frequency_hz: Center frequency to notch out in Hz, > 0. Default: 60.0 q: Q (narrowness) of the notch, 0.1-1000. Default: 1.0

Apply a tremolo (amplitude modulation) effect to the selected audio.

Args: wave_type: 0=Sine, 1=Triangle, 2=Sawtooth, 3=Inverse Sawtooth, 4=Square. Default: 0 phase_degrees: LFO starting phase, -180 to 180. Default: 0 wet_percent: Wet mix percent, 1-100. Default: 40 lfo_hz: LFO rate in Hz, 0.001-1000. Default: 4.0

Generate a tone. Fills the currently selected time range - call select_region first to control duration.

Args: waveform: "Sine", "Square", "Sawtooth", "Square, no alias", or "Triangle". Default: "Sine" frequency: Frequency in Hz (>= 1). Default: 440 amplitude: Amplitude (0-1). Default: 0.8

Generate a chirp (frequency sweep). Fills the currently selected time range - call select_region first to control duration.

Args: waveform: "Sine", "Square", "Sawtooth", "Square, no alias", or "Triangle". Default: "Sine" start_freq: Starting frequency in Hz (>= 1). Default: 440 end_freq: Ending frequency in Hz (>= 1). Default: 1320 start_amp: Starting amplitude (0-1). Default: 0.8 end_amp: Ending amplitude (0-1). Default: 0.1

Generate noise. Fills the currently selected time range - call select_region first to control duration.

Args: noise_type: "White", "Pink", or "Brownian". Default: "White" amplitude: Amplitude (0-1). Default: 0.8

Generate DTMF (telephone) tones. Fills the currently selected time range - call select_region first to control duration.

Args: sequence: Text to encode as DTMF tones. Default: "audacity" (Audacity's own default) duty_cycle: Tone vs silence ratio percentage (0-100). Default: 55 amplitude: Amplitude (0-1). Default: 0.8

Generate silence. Fills the currently selected time range - call select_region first to control duration. Takes no parameters.

Generate a metronome/click rhythm track.

Args: tempo_bpm: Tempo, 30-300 beats/minute. Default: 120.0 beats_per_bar: Time signature numerator, 1-20. Default: 4 swing: Swing amount, -1 to 1. Default: 0.0 num_bars: Number of bars to generate, 0-1000. Set to 0 to use duration_seconds instead. Default: 16 duration_seconds: Duration to fill, used only when num_bars is 0. Default: 0.0 start_offset: Silence before the first beat, in seconds. Default: 0.0 click_type: One of: Metronome, Ping (short), Ping (long), Cowbell, ResonantNoise, NoiseClick, Drip (short), Drip (long). Default: "Metronome" strong_beat_pitch: MIDI pitch of the strong (first) beat, 18-116. Default: 84 weak_beat_pitch: MIDI pitch of weak beats, 18-116. Default: 80

List all labels on the project's (first) label track, with key, text, and time range.

Create a new, empty label track.

Add a label at the current selection/playback position. Creates a label track automatically if none exists yet.

Args: text: Optional text for the new label.

Remove a label by its key.

Args: key: The label's key, in "trackId:itemId" format (from label_list/label_add).

Change the text of an existing label.

Args: key: The label's key, in "trackId:itemId" format. text: The new text for the label.

Edit an existing label's text and/or timing in one call. Only the fields you pass are changed.

Args: key: The label's key, in "trackId:itemId" format (from label_list). text: New label text. Default: unchanged. start: New start time in seconds. Default: unchanged. end: New end time in seconds. Default: unchanged.

Add a label at an exact time range, regardless of the current selection.

Composed from select_region + label_add (add-label places the new label at whatever is currently selected - confirmed in handleAddLabel's source comments). Changes the current selection as a side effect.

Args: start: Start time in seconds. end: End time in seconds (>= start). text: Optional text for the new label.

Add multiple labels in one call.

Args: labels: List of {"start": float, "end": float, "text": str (optional)}.

Import labels from a standard Audacity label text file (tab-separated start\tend\ttext per line; point labels have start == end).

There is no C++ import/export primitive for this in v4 (unlike v3's ImportLabels/ExportLabels scripting commands) - implemented here in pure Python instead, parsing the file directly and adding each label via the same primitives label_add_batch uses. Lines that don't parse as start/end/text are skipped and reported rather than failing the whole import.

Args: path: Absolute path to the labels text file.

Export all labels to a standard Audacity label text file (tab-separated start\tend\ttext per line) - the same format label_import reads back.

There is no C++ export primitive for this in v4 - implemented here in pure Python instead, formatting label_get_all's data directly.

Args: path: Absolute path for the output labels file. overwrite: Set true to replace an existing file. Default: False.

Export labels as a chapter/marker file.

Turns a label track into a standard marker file - chapter navigation for long-form audio, a track listing for a continuous mix, an index for a lecture or interview recording. Formats: "simple" (HH:MM:SS.mmm Title per line), "cue" (cue sheet), "podlove" (Podlove Simple Chapters JSON). Labels with no text become "Chapter 1", "Chapter 2" and so on.

Args: path: Absolute path for the output file. format: Chapter format - simple, cue or podlove. Default: simple. overwrite: Set true to replace an existing file. Default: False.

Export the audio under each label as its own mono WAV file.

Splits a long recording into per-segment audio files, named "01_Segment_Title.wav" and so on from the label text. ALWAYS tell the user which directory the files will be written to BEFORE calling this. Point labels (zero length) have no audio to export and are skipped. Existing files are never overwritten - they are skipped and reported. This can take a while for many or long segments.

Only mono WAV output is available - v4's underlying export-wav command (unlike v3's Export2) has no format/channel-count parameters yet.

Args: directory: Absolute path to the output directory.

Get all labels as structured data (key, text/title, start, end) rather than the raw MCP content blocks label_list returns.

Find labels whose text contains the given (case-insensitive) substring.

Args: query: Substring to search for in label text.

Add labels at regular intervals across a known duration.

There is no C++ primitive to query project/selection duration yet, so the caller must supply it explicitly (e.g. from project_export_audio's or an analysis tool's measured length) rather than this tool guessing.

Args: interval: Spacing between labels, in seconds (> 0). duration: Total duration to cover, in seconds (> 0). text_prefix: Text prefix for each label; each gets a "N" suffix, 1-based. Default: "Marker"

Delete the audio under a single label (by key), closing the gap.

Args: key: The label's key, in "trackId:itemId" format (from label_list).

Cut the audio under every label to the clipboard, closing the gaps.

Only the LAST cut survives on the clipboard (each cut overwrites it) - this collapses every labeled region but only the final one is recoverable via paste. Processes labels last-to-first so earlier label times stay valid as later regions are removed. Label track itself is unaffected.

Delete the audio under every label, closing the gaps.

Processes labels last-to-first so earlier label times stay valid as later regions are removed. Re-read label_list afterwards - the timeline shifted.

Replace the audio under every label with silence, keeping the timeline length.

Order doesn't matter - silencing doesn't shift anything. Labels stay put.

Split the audio clips at every label's start and end boundary.

Order doesn't matter - splitting doesn't shift anything. Labels stay put.

Join the audio clips across every labeled region back together.

The inverse of label_split_regions. Order doesn't matter. Labels stay put.

Get the default folder for exporting audio files. Returns the user's Music folder path (falling back to their home folder if Music doesn't exist). Use this when the user doesn't specify where to save.

Create a new project in the current window. Only works when no project is currently open - if one is open, close it first with project_close (after saving with project_save_as if needed), since replacing an open project here would open a whole separate application window instead.

Open an existing Audacity project file (.aup4 - Audacity 4's native format; .aup3 files are Audacity 3 format and will trigger an interactive conversion prompt in the app, which is not safe to trigger over MCP).

Args: path: Absolute path to the .aup4 project file

Import an audio file into the current project as a new track. Requires a project to already be open - use project_new or project_open first.

Args: path: Absolute path to the audio file (wav, mp3, ogg, flac, etc.)

Close the current project. Refuses if there are unsaved changes - save with project_save_as first, since closing a dirty project would otherwise require an interactive save-changes dialog that isn't safe to trigger over MCP.

Save the current project to a new .aup4 file. ONLY call when the user explicitly asks - do NOT auto-save after effects or pipelines.

Args: path: Absolute path for the new .aup4 file overwrite: Set true to replace an existing file at that path - refused by default

Export the full project's audio (all tracks, stereo, 44.1kHz WAV).

MANDATORY: ALWAYS tell the user where the file will be saved BEFORE exporting. NEVER save directly to the user's home folder root - use a subfolder like Music, Documents, or Desktop.

Args: path: Absolute path for the exported .wav file overwrite: Set true to replace an existing file at that path - refused by default

Export only the current selection's audio (mono, 44.1kHz WAV). Select a time range first with select_region or select_all.

MANDATORY: ALWAYS tell the user where the file will be saved BEFORE exporting. NEVER save directly to the user's home folder root - use a subfolder like Music, Documents, or Desktop.

Args: path: Absolute path for the exported .wav file overwrite: Set true to replace an existing file at that path - refused by default

Save the current project. Refuses if the project has never been saved before (has no file path yet) or has no unsaved changes - check the returned message for why, if isError is true.

List recently executed MCP commands with their id, timestamp, success, and result message. Useful for checking what an earlier command actually did, or finding a command's id to look up with command_status.

Look up the recorded result of a previously executed command by its id.

Args: command_id: The command id, as returned in a recent_commands entry.

Get project-wide info: path, display name, unsaved-changes state, duration, and a summary of every track (id, title, type, rate, mute/solo, clip count). Use a track's id with track_get_info for its full clip (or label) list.

Get project metadata tags: artist, track title, album, track number, year, comments. NOTE: a brand new project's "year" field is NOT empty - confirmed live it defaults to "2018" (a stale template default, not today's date).

Set one or more project metadata tags. Only the fields you pass are changed - pass an empty string to clear a field.

Args: artist: Artist name. track_title: Track title. album: Album title. track_number: Track number. year: Year. comments: Comments.

Find a good installed effect for a stated goal and add it as a realtime effect - the "pick the right plugin for me" workflow, so the user doesn't have to know which of their installed VSTs does reverb, compression, EQ, etc. Searches every actually-installed, realtime- capable effect (Builtin and VST3 alike) by matching category keywords against its title/vendor - VST3 plugins don't reliably self-report a usable category (confirmed live: they all come back "None"), so text matching is the only signal that works across formats. "Best" here is a soft preference among real matches (a few well-regarded vendors, see _PREFERRED_VENDORS), not an objective quality ranking - there isn't one. Returns the alternatives too, so the choice isn't a black box the user can't override.

Args: track_id: Track id, from project_get_info's track list. Use -2 for the Master bus. category: One of "reverb", "compressor", "eq", "delay", "limiter", "distortion", "gate", "chorus", "phaser", "flanger", "deesser".

Add a non-destructive realtime effect to a track's (or the Master bus's) effect chain. Unlike apply-effect/effect_* tools, this stays adjustable and removable afterward - the actual VST/plugin GUI can still be opened live in Audacity to tweak it, same as adding it by hand via the Realtime Effects panel.

Args: track_id: Track id, from project_get_info's track list. Use -2 for the Master bus. effect_id: The real PluginID, from list_effects' "id" field - NOT "title". Confirmed live: passing a title here fails with "cannot load the effect" (this path has no title fallback, unlike apply-effect).

List the realtime effect chain on a track or the Master bus, with each effect's index (for remove_realtime_effect/set_realtime_effect_active), name, and active state.

Args: track_id: Track id, from project_get_info's track list. Use -2 for the Master bus.

Remove one effect from a track's (or the Master bus's) realtime effect chain by index.

Args: track_id: Track id, from project_get_info's track list. Use -2 for the Master bus. index: Position in the chain, from list_realtime_effects.

Enable or bypass one effect in a track's (or the Master bus's) realtime effect chain, without removing it.

Args: track_id: Track id, from project_get_info's track list. Use -2 for the Master bus. index: Position in the chain, from list_realtime_effects. active: True to enable, False to bypass.

List a realtime effect's real, plugin-reported parameters - name, units, min/max/default/current value, and a human-formatted current value string. Works uniformly across Builtin/VST3/LV2/AudioUnit plugins via Audacity's own parameter-extraction layer - no need to guess a plugin's parameter names or ranges (e.g. a reverb's actual "Mix"/"Decay"/"Size" parameters, a compressor's "Threshold"/"Ratio").

Args: track_id: Track id, from project_get_info's track list. Use -2 for the Master bus. index: Position in the chain, from list_realtime_effects.

Set one real-time parameter on a realtime effect to an exact value - e.g. the actual wet/dry mix or decay time of a reverb, not just add/remove/bypass the whole effect.

Args: track_id: Track id, from project_get_info's track list. Use -2 for the Master bus. index: Position in the chain, from list_realtime_effects. parameter_id: Parameter id, from list_effect_parameters' "id" field. value: New value within [minValue, maxValue] from list_effect_parameters. CONFIRMED LIVE: for VST3 plugins this range is typically normalized 0-1, NOT real display units, even though list_effect_parameters' currentValueString shows a real unit (e.g. "21.26 s") - after setting, re-read currentValueString to see the actual resulting value, don't assume the input scale matches it.

List a realtime effect's real factory presets (e.g. a reverb's named room/hall presets), if the plugin format exposes any. Not every plugin has factory presets - an empty list is a normal result, not an error.

Args: track_id: Track id, from project_get_info's track list. Use -2 for the Master bus. index: Position in the chain, from list_realtime_effects.

Apply one of a realtime effect's factory presets by id.

Args: track_id: Track id, from project_get_info's track list. Use -2 for the Master bus. index: Position in the chain, from list_realtime_effects. preset_id: Preset id, from list_effect_presets.

Select all tracks and all audio data in the project.

Deselect all tracks and clear the time selection.

Select a time region. Applies to whichever tracks are currently selected - call select_tracks or select_all first if needed.

Args: start: Start time in seconds end: End time in seconds

Select one or more tracks by index.

Args: track: Starting track index (0-based) count: Number of tracks to select

Adjust the current selection boundaries to the nearest zero crossings. Useful before cuts to avoid audible clicks at edit points.

Move the playback cursor / edit point to a specific time.

Args: time: Position in seconds

Move the cursor to the very start of the project (t=0).

Move the cursor to the end of the project (its total duration).

Move the cursor to the start of a track's earliest clip.

Args: track_id: The track's id, from project_get_info's track list.

Move the cursor to the end of a track's latest clip.

Args: track_id: The track's id, from project_get_info's track list.

Select a specific clip by key - selects its track, the clip itself, and the time range spanning it.

Args: key: Clip key "trackId:itemId", from track_get_info's clip list.

Select from the current cursor position to the end of a track's latest clip.

Args: track_id: The track's id, from project_get_info's track list.

Add a new mono audio track to the project.

Add a new stereo audio track to the project.

Remove the currently selected track(s). Select tracks first with select_tracks.

Set one or more properties of a track by index. Only the properties you pass are changed - omit any you don't want to touch.

Args: track: Track index (0-based) name: New track name gain: Track gain in dB (-36 to 36) pan: Track pan (-1.0=left to 1.0=right) mute: Mute the track solo: Solo the track

Duplicate the currently selected track(s). Select tracks first with select_tracks.

Resample the selected track(s) to a new sample rate. Select tracks first with select_tracks.

Args: rate: Target sample rate in Hz (e.g. 44100, 48000, 96000). Must be 1-384000.

Get detailed info about one track: title, type, rate, mute/solo, and its full clip list (start/end/title per clip), or label list for a label track.

Args: track_id: The track's id, from project_get_info's track list. NOT the same as track_set_properties'/track_resample's 0-based "track" index - use the "id" field from project_get_info.

Mute or unmute a track by index. Convenience wrapper over track_set_properties' mute parameter.

Args: track: Track index (0-based) - same convention as track_set_properties, NOT the "id" field from project_get_info/track_get_info. mute: True to mute, False to unmute. Default: True

Mute every track in the project, including any not currently selected.

Uses a dedicated C++ command that iterates the real track list by id - NOT composed from track_set_properties' index-based addressing, which would silently hit the wrong track whenever a label track sits before an audio track (project_get_info's track list excludes label tracks, but the raw index space includes them).

Unmute every track in the project, including any not currently selected.

Set the color tag for the currently selected track(s), for visual organization. Select tracks first with select_tracks.

Args: color_index: 0 (no custom color, inherit default) to 9.

Get the default folder for saving transcription files. Returns the user's Documents folder. Call this when the user doesn't specify where to save.

[EXPERIMENTAL] Check the status of a running transcription job. Call this after starting transcribe_audio, transcribe_to_labels, or transcribe_to_file. Poll every 10-15 seconds until status is 'complete' or 'error'.

Args: job_id: The job ID returned when you started the transcription.

[EXPERIMENTAL] Transcribe the entire project audio using faster-whisper (local, offline). Requires separate setup (pip install faster-whisper).

Runs in BACKGROUND - returns a job_id immediately. Use check_transcription_status to monitor progress. Poll every 10-15 seconds.

Language auto-detection can occasionally misidentify the language. If you already know the audio's language, pass language explicitly (e.g. "en"), or set task="translate" to force English output regardless of the spoken language.

Args: model_size: Whisper model - "tiny", "base", "small", "medium", "large-v3". Default: "small" language: ISO language code (e.g. "en", "fr") or None for auto-detect task: "transcribe" or "translate" (translate converts any language to English)

[EXPERIMENTAL] Transcribe only the currently selected audio region. Requires separate setup (pip install faster-whisper).

Runs in BACKGROUND - returns a job_id immediately. Select a region first, then call this tool.

Args: model_size: Whisper model - "tiny", "base", "small", "medium", "large-v3" language: ISO language code or None for auto-detect task: "transcribe" or "translate"

[EXPERIMENTAL] Transcribe audio and add Audacity labels at each segment timestamp. Requires separate setup (pip install faster-whisper).

Runs in BACKGROUND - returns a job_id immediately.

If labels from a previous attempt need clearing first: select_tracks the label track, then track_remove, before re-running this.

Args: model_size: Whisper model - "tiny", "base", "small", "medium", "large-v3" language: ISO language code (e.g. "en") or None for auto-detect task: "transcribe" (labels in the spoken language) or "translate" (labels always in English, regardless of the spoken language)

[EXPERIMENTAL] Transcribe audio and export to a subtitle or text file. Requires separate setup (pip install faster-whisper).

ALWAYS tell the user where the file will be saved BEFORE starting. If user doesn't specify a path, call get_default_transcription_folder for a real path.

Runs in BACKGROUND - returns a job_id immediately.

Args: path: Absolute path for the output file (e.g. "C:/Users/You/Documents/transcript.srt") format: Output format - "srt", "vtt", or "txt" model_size: Whisper model - "tiny", "base", "small", "medium", "large-v3" language: ISO language code (e.g. "en") or None for auto-detect task: "transcribe" (spoken language) or "translate" (always English)

[EXPERIMENTAL] Pre-download a whisper model. ONLY call this if the user explicitly asks to download or change the model. Do NOT call this before transcribe_audio - transcription tools handle model loading automatically.

Runs in BACKGROUND - returns a job_id immediately.

Model sizes:

• tiny: ~75MB (fastest, least accurate)

• base: ~150MB (good balance for most use cases)

• small: ~500MB (better accuracy, recommended)

• medium: ~1.5GB (high accuracy)

• large-v3: ~3GB (best accuracy, slowest)

Args: model_size: Model to load - "tiny", "base", "small", "medium", "large-v3"

Start playback from the current cursor position, unconditionally - unlike transport_play_stop (a toggle), this never stops playback that's already running. There is no dedicated "always play" action in v4 (only a play/stop toggle and play-selection, which requires an actual selection); composed here by checking transport_get_play_position first and only toggling if not already playing.

Toggle playback of the current project (play if stopped, stop if playing).

Pause playback.

Stop playback.

Move the playback cursor to the start of the project.

Start recording on a new track. Requires a working audio input device - if none is configured, this dispatches without error but recording won't actually engage. Use transport_stop to stop recording.

Get the current playhead position, whether playback is active, and the current time selection (start/end).

Select a time region and play it, starting from the region's beginning.

Args: start: Start time in seconds end: End time in seconds (>= start)