Skip to main content
Glama

Audacity 4.0 shipped with no scripting surface at all. mod-script-pipe is gone and nothing replaced it, so the automation that Audacity 3 users relied on simply does not exist.

Audacity4MCP puts one back. It connects any MCP-compatible AI assistant to Audacity 4 — editing, effects, VST3 plugins, labels, transcription and one-call mastering pipelines — over a local TCP bridge compiled into a companion fork of Audacity itself.

Everything runs locally. No cloud, no API keys for audio processing, no audio leaving your machine.

What It Does

You talk to your AI assistant; it drives Audacity.

"Clean up this podcast recording and get it ready to publish." Analyses the audio, picks the right pipeline, removes noise, evens out the levels, and lands it at broadcast loudness.

"Put a low cut at 80 Hz, a 3 dB dip at 400, and a gentle air shelf at 10k." Sets real parameters on a real VST3 EQ — FabFilter, Valhalla, whatever you have installed — while its own window is open, and you watch the curve move.

"Transcribe this and label each sentence." Local Whisper transcription, then every segment written back as a label in one call.

"Split this interview at the silences and export each answer as its own file." Silence detection, region labels, per-segment export.

The point is not that these are macros. The assistant can read the project back — track layout, clip boundaries, plugin parameters, measured loudness — and decide what to do next based on what it finds.

Related MCP server: Audacity MCP Server

Status

Early alpha, under active daily development. Expect gaps, and expect things to change.

This is the sibling of AudacityMCP for Audacity 3.x, which is mature and used in production. Audacity 4 is a full rewrite, so nothing ported directly — every command here was built against v4's actual internals and tested live against a running instance.

What that means in practice:

  • Every tool listed is implemented and registered, not aspirational. The count is taken from the code.

  • Each was verified against a real running Audacity, not just unit-tested against mocks. This has repeatedly caught bugs that mocks cannot — crashes, wrong parameter scales, effects landing at the wrong position.

  • Some things genuinely do not work yet. They are in Known Gaps rather than quietly missing.

  • There is no packaged installer. You build the companion fork yourself. Windows/MSVC is the only toolchain tested end to end so far.

Bugs found in Audacity itself

Driving Audacity headlessly surfaces bugs that ordinary use does not. Where they are not MCP-specific, they go upstream rather than staying patched in a fork:

  • VST3 plugin meters and analysers never animated. FabFilter Pro-L2, Pro-Q 3, TBProAudio dpMeter5 and mvMeter2 all showed a single frozen frame, because the host silently dropped every plugin message arriving from a non-UI thread. Measured on a playing track: 34 delivered, 4305 dropped — 6585 delivered and 4 dropped after the fix. Submitted as audacity/audacity#11992 against issue #8881. It affects Audacity 3 too; that code had not changed functionally since July 2022.

Quick Start

Both halves have to be running: the modified Audacity that hosts the bridge, and this Python server that talks to it.

1. Build the companion fork — see below. This is the long part; there is no prebuilt binary yet.

2. Install this server (Python 3.10+):

pip install audacity4-mcp

This half is plain Python and runs on Windows, macOS and Linux alike. On Debian, Ubuntu or Fedora the system Python will refuse the install (externally-managed-environment) — use a virtual environment or pipx, and see INSTALLATION.md.

Or from source, if you want to change it:

git clone https://github.com/xDarkzx/Audacity4-MCP.git
cd Audacity4-MCP
pip install -e .

3. Point your MCP client at it. For Claude Desktop / Claude Code:

{
  "mcpServers": {
    "audacity4": {
      "command": "audacity4-mcp"
    }
  }
}

That works when audacity4-mcp is on the PATH your MCP client sees. If you installed into a virtual environment it will not be, and the client fails to start the server with little explanation — give the absolute path instead (.../venv/Scripts/audacity4-mcp.exe on Windows, .../venv/bin/audacity4-mcp elsewhere). where audacity4-mcp / which audacity4-mcp prints it.

4. Launch the Audacity you built, open or create a project, and start talking to it.

Nothing else to configure — the auth token is generated by Audacity on first run and read from its profile directory automatically.

Full setup, including how to verify the connection: docs/INSTALLATION.md.

Building the Companion Fork

Audacity 4 has no scripting surface, so the bridge is compiled into a fork of it: Audacity4-Dev-MCP. Build it once, then run it instead of stock Audacity.

Windows/MSVC is the only toolchain tested. macOS and Linux should work — the code is portable and its POSIX paths are exercised in tests — but they have not been built end to end.

Prerequisites: Visual Studio 2022+ with "Desktop development with C++", Qt 6.8 or newer (tested on 6.10), CMake and Ninja on PATH. Audacity's own BUILDING.md covers installing those.

Qt components matter more than the version. The build requires several modules that the Qt installer leaves unticked by default, and a missing one fails at configure time with a find_package error rather than anything obvious:

  • Qt 5 Compatibility Module (Core5Compat)

  • Qt Shader Tools (ShaderTools)

  • Qt Network Authorization (NetworkAuth)

  • On Linux, Qt D-Bus

The rest come with a standard desktop install: Core, Gui, Widgets, Network, Qml, Quick, QuickControls2, QuickWidgets, Xml, Svg, PrintSupport. The authoritative list is muse/buildscripts/cmake/SetupQt6.cmake if you hit a component error not covered here.

Clone it — with submodules. Part of the bridge lives in the muse submodule, so a plain git clone produces a tree that cannot configure:

git clone --recurse-submodules https://github.com/xDarkzx/Audacity4-Dev-MCP.git
cd Audacity4-Dev-MCP
git checkout feature/mcp-audio-cleanup-pipelines
git submodule update --init --recursive

Already cloned without --recurse-submodules? The last line alone is enough. Cloned before the submodule URL was corrected? Run git submodule sync --recursive first.

Load the MSVC environment — once per terminal. cmake will not find the compiler without it:

"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"

(Adjust year/edition to match your install.)

Configure, build and install:

cmake --preset audacity-debug
cmake --build build/audacity-debug
cmake --install build/audacity-debug

Expect around 20 minutes for the first build, give or take depending on your machine. Later builds are incremental and much quicker.

The install step is the one that matters — the build directory does not contain a launchable app (there is no Audacity4.exe in it at all). Re-run cmake --preset whenever a CMakeLists.txt changes; an incremental build will not pick that up.

Run it:

src/app/bin/Audacity4.exe

That binary — not anything under build/. The mcp module has no visible UI; it starts listening on 127.0.0.1:2212 as soon as Audacity launches.

Two things worth knowing:

  • Close Audacity from its own window, never with Task Manager or taskkill /F. A force-kill corrupts session-recovery state and produces a recurring "convert project" prompt on every later launch.

  • LNK1168 on rebuild means Audacity is still running and holding the binary open. Close it first.

Features

159 tools across 12 categories. Full reference: docs/TOOLS.md.

Category

Tools

What it covers

Effects

29

Built-in effects, batched application, presets, parameter discovery

Edit

27

Cut, copy, paste, trim, split, join, silence, undo/redo, clip pitch & speed

Labels

21

Add, edit, batch-add, region cut/silence/export, chapters, import/export

Project

14

Open, save, import, export, metadata

Selection

12

Time ranges, tracks, clips, zero-crossings, cursor placement

Realtime / VST3

11

Non-destructive chains, live parameter control, effect discovery

Track

11

Add, remove, duplicate, mute, resample, colour, properties

Cleanup pipelines

9

One-call mastering and repair workflows — see below

Transport

8

Play, stop, record, pause, position

Transcription

7

Local Whisper, to labels, to SRT/VTT/TXT

Generate

6

Tone, noise, silence, chirp, DTMF, rhythm track

Analysis

4

Loudness, noise floor, clipping, content-aware recommendations

Real VST3 control

This is the part most audio automation cannot do. Plugins are addressed as themselves, not as opaque presets:

  • Discover every installed VST3 and its real parameters, ranges and units

  • Set parameters by value — with the plugin's own editor open, updating live

  • Batch a whole chain in a single call, so a chain never audibly passes through a half-configured state

  • Non-destructive realtime chains, adjustable and removable afterwards

Two long-standing Audacity bugs had to be fixed in the fork before this worked reliably: writes made while a plugin's editor was open were silently discarded, and parameter metadata misreported continuous controls as dropdowns. Both are fixed and verified against FabFilter Pro-Q 3 and ValhallaVintageVerb — see Known Gaps.

Pipelines

One call, many steps, measured rather than guessed. Each analyses the audio first and adapts.

Pipeline

For

auto_analyze_audio

Measures the audio and recommends which pipeline to use. Start here.

auto_cleanup_audio

Safe cleanup — removes noise and artifacts without changing loudness

auto_cleanup_podcast

Podcast / voiceover, ending at broadcast loudness

auto_audiobook_mastering

Audiobook, targeting ACX/Audible compliance

auto_cleanup_interview

Dialogue and interviews, light touch

auto_cleanup_vocal

Singing and studio vocals

auto_cleanup_live

Live, field and noisy recordings — aggressive

auto_master_music

Music mastering with per-genre loudness targets

auto_lofi_effect

Creative vintage/lo-fi colouring

The long-running ones return a job_id immediately and report progress through check_pipeline_status, so a ten-minute master does not block the conversation.

auto_analyze_audio takes a content_type (speech, music or auto), because the same measurements mean different things for each — in continuous music the quietest passage is the music, so speech-tuned noise-floor advice would damage it.

Tool Profiles

159 tool schemas are sent to the model on every turn (~16k tokens). If you only need one workflow, load only that:

{
  "mcpServers": {
    "audacity4": {
      "command": "audacity4-mcp",
      "env": { "AUDACITY4_MCP_PROFILE": "cleanup" }
    }
  }
}

Profile

Tools

Tokens/turn

full (default)

159

~16,400

mastering

100

~10,900

cleanup

98

~10,800

editing

93

~6,400

transcription

61

~5,200

minimal

33

~2,300

Finer control via AUDACITY4_MCP_INCLUDE_MODULES / EXCLUDE_MODULES / INCLUDE_TOOLS / EXCLUDE_TOOLS. Check a profile without starting a session:

audacity4-mcp --profile-info --profile cleanup

Architecture

AI assistant (Claude, etc.)
      │  MCP (stdio)
      ▼
Audacity4MCP  (this repo — Python, FastMCP)
      │  TCP JSON-RPC, 127.0.0.1:2212, token-authenticated
      ▼
Audacity4-Dev-MCP  (C++ fork — src/mcp/ module)
      │  dispatcher / interface calls
      ▼
Audacity 4 engine (tracks, effects, VST3 hosting, ...)

The bridge is compiled into the fork: src/mcp/internal/audacitycommandscontroller.cpp registers each command against Audacity 4's real internal interfaces (ITrackeditProject, ISelectionController, IEffectsProvider, IRealtimeEffectService, IEffectParametersProvider). On this side, bridge_client.py is a plain asyncio TCP client.

Security

  • Every request is authenticated. Audacity generates a 256-bit token from the OS cryptographic source on first run and writes it to its own profile directory as an owner-only file. This client reads it from the same place, so there is nothing to configure. AUDACITY4_MCP_TOKEN overrides it for containers or remote setups.

  • Fails closed. With no token established, every request is refused rather than served unauthenticated. Comparison is constant-time.

  • HTTP requests are rejected. A web page can fetch() a localhost port with Content-Type: text/plain and no CORS preflight, and the request body is just another protocol line. That was verified to execute commands, then fixed.

  • Paths are validated in the C++ handlers, not only in this client — anything that can authenticate can call the bridge directly, so a check only the Python layer applies is not a check. Relative paths, null bytes and system directories are refused, with .. and symlinks resolved first.

Known Gaps

  • VST3 realtime parameters — fixed. Writing a parameter while the plugin's own GUI was open reported success and then silently reverted, for continuous and discrete parameters alike. The parameter cache belongs to the plugin wrapper rather than to any one settings object, and the read-back and notification that follow every write drained it into a different one before it could be committed. Writes now stick with the editor open — verified on FabFilter Pro-Q 3 (15 parameters in one call, including the per-band Shape dropdowns this project once recorded as impossible to set) and ValhallaVintageVerb.

  • VST3 parameter metadata — fixed. Pro-Q 3's per-band Frequency reported "units": "Band 2" and "type": "Dropdown" despite being continuous. A VST3 unit is a grouping of parameters, not a unit of measurement, and the type classifier trusted the kIsList flag without checking anything was listable. 124 of Pro-Q 3's 492 parameters were dropdowns with no entries; that is now 0, and stepCount is reported.

  • VST3 factory presets are usually empty. list_effect_presets genuinely returns nothing for plugins (FabFilter, Valhalla) that keep presets in their own in-plugin browser rather than the standard VST3 host-preset API. This matches their behaviour in other DAWs — not an Audacity bug.

  • Some v3 tools have no v4 engine support yet and are deliberately not implemented rather than shipped broken: track_mix_and_render, track_stereo_to_mono, track_align_end_to_end, project_import_midi.

  • Some v3 effects do not exist in v4 builds. Echo, Phaser, Wahwah, Distortion, Repeat, ChangeTempo, ChangeSpeed, Equalization and AutoDuck have source in the tree but never link into the build — confirmed against the runtime plugin registry. Wrapping an effect that isn't there is worse than not having it.

Full history of what has been found and fixed: CHANGELOG.md.

Troubleshooting

"Could not read Audacity's MCP token" — Audacity has not been started yet, or was installed somewhere unexpected. It writes the token on first run. The error lists every path checked; set AUDACITY4_MCP_TOKEN to point at it directly if needed.

"Audacity rejected the connection as unauthorized" — the token no longer matches, usually after a profile reset. The client re-reads and retries automatically; if it persists, restart Audacity, or unset AUDACITY4_MCP_TOKEN if it points at a stale value.

"Could not reach Audacity" — the bridge only listens while Audacity is running. Check it is open, and that nothing else holds port 2212.

A command hangs, then reports a dialog — Audacity is showing a modal dialog that blocks its main thread, usually an effect refusing to run because its preconditions were not met (wrong track or clip selected). No client can dismiss it; check the Audacity window.

Your MCP client never starts the server — usually PATH. audacity4-mcp installed in a virtual environment is not on the PATH the client inherits. Use the absolute path to the executable in your config; where / which audacity4-mcp prints it.

cmake --preset fails with a Qt find_package error — a required Qt module is not installed, not a broken checkout. Qt 5 Compatibility Module, Qt Shader Tools and Qt Network Authorization are all unticked by default in the Qt installer. See INSTALLATION.md.

LNK1168 when rebuilding the fork — Audacity is still running and holding the binary. Close it from its own window.

A "convert project" prompt on every launch — session-recovery state was corrupted by a force-kill. Always close Audacity from its own window.

Works With

Any MCP-compatible client: Claude Desktop, Claude Code, and anything else that speaks the Model Context Protocol.

Contributing

Bug reports and pull requests welcome — see CONTRIBUTING.md. Security issues: SECURITY.md.

If you are reporting something audio-related, say which plugin and which Audacity build, and include what you measured rather than what it sounded like where you can. Most of the bugs fixed here were found that way.

License

Apache 2.0

Available Tools

156 tools
add_realtime_effectA

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

Inputs: track_id (required), effect_id (required).

analyze_beat_finderA

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

Inputs: threshold_percent.

analyze_label_soundsA

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"

Inputs: label_type, measurement, threshold_db, min_label_interval, +1 more.

analyze_sample_data_exportA

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"

Inputs: path (required), limit, units.

apply_effect_presetB

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.

Inputs: index (required), track_id (required), preset_id (required).

auto_analyze_audioA

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.

Inputs: no named parameters.

auto_audiobook_masteringA

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.

Inputs: remove_noise.

auto_cleanup_audioA

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.

Inputs: remove_noise, remove_clicks.

auto_cleanup_interviewA

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.

Inputs: remove_noise.

auto_cleanup_liveA

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.

Inputs: no named parameters.

auto_cleanup_podcastA

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.

Inputs: remove_noise.

auto_cleanup_vocalA

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.

Inputs: remove_noise.

auto_lofi_effectA

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"

Inputs: intensity.

auto_master_musicA

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

Inputs: style, noise_reduce.

bass_and_trebleB

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

Inputs: bass, gain, treble.

check_pipeline_statusA

Check the status of a running cleanup pipeline.

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

Inputs: job_id (required).

check_transcription_statusA

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

Inputs: job_id (required).

click_removalA

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

Inputs: threshold, spike_width.

clip_render_pitch_speedA

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.

Inputs: key (required).

clip_reset_pitchA

Revert a clip's pitch change made via clip_set_pitch.

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

Inputs: key (required).

clip_reset_pitch_speedA

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

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

Inputs: key (required).

clip_reset_speedA

Revert a clip's speed change made via clip_set_speed.

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

Inputs: key (required).

clip_set_colorA

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.

Inputs: key (required), color_index (required).

clip_set_pitchA

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

Inputs: key (required), semitones (required).

clip_set_speedA

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

Inputs: key (required), speed (required).

clip_split_at_silencesA

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.

Inputs: key (required).

clip_stretchA

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.

Inputs: key (required), side (required), delta_sec (required), min_clip_duration.

clip_trimA

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.

Inputs: key (required), side (required), delta_sec (required), min_clip_duration.

command_statusA

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.

Inputs: command_id (required).

compressorA

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

Inputs: ratio, attack_ms, release_ms, threshold_db, +2 more.

cursor_setA

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

Args: time: Position in seconds

Inputs: time (required).

cursor_to_project_endA

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

Inputs: no named parameters.

cursor_to_project_startA

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

Inputs: no named parameters.

cursor_to_track_endA

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.

Inputs: track_id (required).

cursor_to_track_startA

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.

Inputs: track_id (required).

edit_copyA

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

Inputs: no named parameters.

edit_cutB

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

Inputs: no named parameters.

edit_deleteA

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

Inputs: no named parameters.

edit_disjoinA

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

Inputs: no named parameters.

edit_duplicateA

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

Inputs: no named parameters.

edit_joinA

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

Inputs: no named parameters.

edit_pasteA

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

Inputs: no named parameters.

edit_redoA

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

Inputs: no named parameters.

edit_silenceA

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

Inputs: no named parameters.

edit_splitA

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

Inputs: no named parameters.

edit_split_cutA

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

Inputs: no named parameters.

edit_split_deleteA

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

Inputs: no named parameters.

edit_split_newA

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

Inputs: no named parameters.

edit_trimA

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

Inputs: no named parameters.

edit_undoA

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

Inputs: no named parameters.

effect_adjustable_fadeA

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

Inputs: units, end_level, fade_type, start_level, +1 more.

effect_amplifyA

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

Inputs: ratio, allow_clipping.

effect_change_pitchB

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

Inputs: semitones, use_high_quality_stretching.

effect_clip_fixA

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

Inputs: gain_db, threshold.

effect_crossfade_clipsA

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

Inputs: no named parameters.

effect_crossfade_tracksA

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

Inputs: curve_type.

effect_fade_inA

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

Inputs: no named parameters.

effect_fade_outA

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

Inputs: no named parameters.

effect_invertA

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

Inputs: no named parameters.

effect_notch_filterA

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

Inputs: q, frequency_hz.

effect_paulstretchA

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

Inputs: stretch_factor, time_resolution.

effect_remove_dc_offsetA

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.

Inputs: no named parameters.

effect_repairA

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.

Inputs: no named parameters.

effect_reverbB

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

Inputs: dry_gain, tone_low, wet_gain, wet_only, +6 more.

effect_reverseA

Reverse the selected audio. Select a region first.

Inputs: no named parameters.

effect_sliding_stretchA

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

Inputs: rate_change_end, rate_change_start, pitch_change_end_semitones, pitch_change_start_semitones.

effect_studio_fade_outA

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

Inputs: no named parameters.

effect_tremoloA

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

Inputs: lfo_hz, wave_type, wet_percent, phase_degrees.

generate_chirpA

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

Inputs: end_amp, end_freq, waveform, start_amp, +1 more.

generate_dtmfA

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

Inputs: sequence, amplitude, duty_cycle.

generate_noiseB

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

Inputs: amplitude, noise_type.

generate_rhythm_trackA

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

Inputs: swing, num_bars, tempo_bpm, click_type, +5 more.

generate_silenceA

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

Inputs: no named parameters.

generate_toneA

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

Inputs: waveform, amplitude, frequency.

get_default_export_folderA

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.

Inputs: no named parameters.

get_default_transcription_folderA

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.

Inputs: no named parameters.

get_noise_profileA

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.

Inputs: no named parameters.

label_addA

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.

Inputs: text.

label_add_atA

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.

Inputs: end (required), start (required), text.

label_add_batchB

Add multiple labels in one call.

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

Inputs: labels (required).

label_add_trackA

Create a new, empty label track.

Inputs: no named parameters.

label_cut_regionsA

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.

Inputs: no named parameters.

label_delete_audio_atB

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

Inputs: key (required).

label_delete_regionsA

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.

Inputs: no named parameters.

label_editA

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.

Inputs: key (required), end, text, start.

label_exportA

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.

Inputs: path (required), overwrite.

label_export_audio_segmentsA

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.

Inputs: directory (required).

label_export_chaptersA

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.

Inputs: path (required), format, overwrite.

label_findA

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

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

Inputs: query (required).

label_get_allA

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

Inputs: no named parameters.

label_importA

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.

Inputs: path (required).

label_join_regionsA

Join the audio clips across every labeled region back together.

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

Inputs: no named parameters.

label_listA

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

Inputs: no named parameters.

label_regular_intervalsA

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"

Inputs: duration (required), interval (required), text_prefix.

label_removeA

Remove a label by its key.

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

Inputs: key (required).

label_silence_regionsA

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

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

Inputs: no named parameters.

label_split_regionsA

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

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

Inputs: no named parameters.

label_update_textB

Change the text of an existing label.

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

Inputs: key (required), text (required).

limiterA

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

Inputs: release_ms, threshold_db, knee_width_db, makeup_target_db.

list_effect_parametersA

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.

Inputs: index (required), track_id (required).

list_effect_presetsA

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.

Inputs: index (required), track_id (required).

list_effectsA

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.

Inputs: limit, family, search, category.

list_realtime_effectsA

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.

Inputs: track_id (required).

loudness_normalizeA

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

Inputs: dual_mono, lufs_level, stereo_independent.

nearest_zero_crossingA

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.

Inputs: time (required).

noise_reductionA

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

Inputs: sensitivity, noise_gain_db, frequency_smoothing_bands.

normalizeA

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

Inputs: remove_dc, peak_level_db, stereo_independent.

project_closeA

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.

Inputs: no named parameters.

project_export_audioA

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

Inputs: path (required), overwrite.

project_export_selectionA

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

Inputs: path (required), overwrite.

project_get_infoA

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.

Inputs: no named parameters.

project_get_metadataA

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

Inputs: no named parameters.

project_import_audioA

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

Inputs: path (required).

project_newA

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.

Inputs: no named parameters.

project_openA

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

Inputs: path (required).

project_saveA

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.

Inputs: no named parameters.

project_save_asA

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

Inputs: path (required), overwrite.

project_set_metadataA

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.

Inputs: year, album, artist, comments, +2 more.

recent_commandsA

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.

Inputs: no named parameters.

remove_realtime_effectA

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.

Inputs: index (required), track_id (required).

select_allA

Select all tracks and all audio data in the project.

Inputs: no named parameters.

select_clipA

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.

Inputs: key (required).

select_cursor_to_track_endA

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.

Inputs: track_id (required).

select_noneA

Deselect all tracks and clear the time selection.

Inputs: no named parameters.

select_regionA

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

Inputs: end (required), start (required).

select_tracksA

Select one or more tracks by index.

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

Inputs: track (required), count.

select_zero_crossingA

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

Inputs: no named parameters.

set_effect_parameterA

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.

Inputs: index (required), value (required), track_id (required), parameter_id (required).

set_realtime_effect_activeA

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.

Inputs: index (required), active (required), track_id (required).

split_range_at_silencesA

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

Inputs: end (required), start (required).

suggest_and_add_effectA

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

Inputs: category (required), track_id (required).

track_add_monoA

Add a new mono audio track to the project.

Inputs: no named parameters.

track_add_stereoA

Add a new stereo audio track to the project.

Inputs: no named parameters.

track_duplicateA

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

Inputs: no named parameters.

track_get_infoA

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.

Inputs: track_id (required).

track_muteA

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

Inputs: track (required), mute.

track_mute_allA

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

Inputs: no named parameters.

track_removeA

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

Inputs: no named parameters.

track_resampleA

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.

Inputs: rate (required).

track_set_colorA

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.

Inputs: color_index (required).

track_set_propertiesA

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

Inputs: track (required), pan, gain, mute, +2 more.

track_unmute_allA

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

Inputs: no named parameters.

transcribe_audioA

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

Inputs: task, language, model_size.

transcribe_selectionA

[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"

Inputs: task, language, model_size.

transcribe_to_fileA

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

Inputs: path (required), task, format, language, +1 more.

transcribe_to_labelsA

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

Inputs: task, language, model_size.

transcription_set_modelA

[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"

Inputs: model_size.

transport_get_play_positionA

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

Inputs: no named parameters.

transport_pauseB

Pause playback.

Inputs: no named parameters.

transport_playA

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.

Inputs: no named parameters.

transport_play_regionB

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)

Inputs: end (required), start (required).

transport_play_stopA

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

Inputs: no named parameters.

transport_recordA

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.

Inputs: no named parameters.

transport_rewind_startA

Move the playback cursor to the start of the project.

Inputs: no named parameters.

transport_stopA

Stop playback.

Inputs: no named parameters.

truncate_silenceA

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

Inputs: truncate_to, threshold_db, compress_ratio, minimum_silence, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 156 tools

    Disambiguation3/5

    The strong prefix families (edit_, clip_, label_, track_, project_) keep most tools distinct, but several clusters genuinely overlap: effect_fade_out vs effect_studio_fade_out, normalize vs loudness_normalize, clip_trim vs clip_stretch (whose own descriptions admit the confusing convention), edit_delete vs edit_split_delete vs edit_silence, and transport_play vs transport_play_stop. The eight auto_* pipelines are differentiated mainly by scenario keywords. Detailed descriptions help, but misselection risk is real.

    Naming Consistency4/5

    The toolset follows a strong snake_case family-prefix pattern (edit_, clip_, effect_, generate_, label_, project_, track_, select_, cursor_, transport_, auto_, transcribe_) that is highly predictable. However, notable deviations exist: basic effects like normalize, compressor, limiter, noise_reduction, click_removal, and bass_and_treble lack the effect_ prefix their siblings have, and transcription_set_model breaks the transcribe_ family. Still, ~83% consistency makes the pattern legible.

    Tool Count1/5

    156 tools is extreme by any measure, tripling the 50+ threshold for a severe count mismatch. While Audacity is a full-featured DAW, much of this bloat is redundant: eight near-duplicate auto_* one-click pipelines could be one parameterized tool, twenty label_* tools include many composable variants, and fourteen edit_* tools cover microscopic variations. The scope is broad, but the count is disproportionate.

    Completeness4/5

    Coverage is impressively thorough: full project lifecycle (new/open/save/close/import/export), track and clip CRUD, destructive effects plus realtime effect chains with parameter/preset control, label management with batch/import/export/region operations, transport, generation, analysis, and transcription. Minor gaps include WAV-only export at fixed sample rates, no dedicated parametric EQ tool, and no clip-level gain control — workable limitations but not a fully closed surface.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to control Audacity for real-time local audio editing, mastering, and transcription through over 90 specialized tools. It allows users to perform complex audio processing tasks like noise reduction and podcast cleanup using natural language commands.
      144
      136
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      This MCP server enables AI assistants to control a live REAPER DAW instance, including transport, tracks, FX, MIDI, media, markers, rendering, and project state, with an escape hatch for arbitrary ReaScript commands.
      40
      MIT