Find beats in the selected audio and add labels at beat positions.

Args: thres_val: Beat detection threshold (0-100, lower = more sensitive). Default: 65

Analyze the contrast between foreground and background audio. Select a region first. Useful for checking accessibility compliance (WCAG).

Find clipping in the selected audio and create labels at clipped regions.

Args: duty_cycle_start: Min number of consecutive clipped samples to detect (1-1000, default 3) duty_cycle_end: Min number of consecutive non-clipped samples to end a region (1-1000, default 3)

Automatically label regions of sound separated by silence.

A good starting point for segmenting a long recording: label every passage of sound, or with label_type="between" label the silences instead so they can be trimmed with label_delete_regions.

measurement, label_type, pre_offset, post_offset and label_text are new and not yet independently live-tested against a running Audacity — verified against the scripting reference and unit tests with mocked responses only. threshold_db/min_silence_duration/min_sound_duration predate this and are unaffected.

Args: threshold_db: Volume threshold to distinguish sound from silence (dB). Default: -30 min_silence_duration: Minimum duration of silence between sounds (seconds). Default: 0.5 min_sound_duration: Minimum duration of a sound region (seconds). Default: 0.1 measurement: How level is measured — peak, avg or rms. Default: peak label_type: What to label — before, after, around or between the sounds. Default: before pre_offset: Seconds to extend each label before the sound starts. Default: 0 post_offset: Seconds to extend each label after the sound ends. Default: 0 label_text: Text for each label. Default: Audacity's own default

Open the Plot Spectrum window for the selected audio. Select a region first.

Export raw sample data from the selected audio to TXT, CSV, or HTML.

Args: path: Absolute path for the output file limit: Maximum number of samples to export. Default: 100

Check pipe discovery and execute read-only GetInfo against Audacity.

Return local server/runtime information without contacting Audacity.

Analyze the current audio track and recommend the best pipeline to use. This is SYNCHRONOUS — it returns the analysis directly, no job_id needed.

Returns peak level, estimated noise floor, duration, clipping status, and a recommendation for which auto_ pipeline to use next.

IMPORTANT: Load your audio into Audacity before calling this.

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 > HPF 80Hz > noise reduction 12dB > compression 2.5:1 > RMS -20dB > peak cap -3.5dB Meets 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 first 0.5s as noise profile. Default: True

IMPORTANT: If remove_noise is True, the first 0.5 seconds should be room tone / silence. DO NOT call this again if a pipeline is already running — use check_pipeline_status instead.

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 > HPF 80Hz > noise reduction (opt) > click removal (opt) NO compression, NO normalize, NO LUFS. Just clean.

Args: remove_noise: Apply noise reduction using first 0.5s as noise profile. Default: True remove_clicks: Remove clicks/pops (useful for vinyl/old recordings). Default: False

IMPORTANT: If remove_noise is True, the first 0.5 seconds should be room tone / silence. DO NOT call this again if a pipeline is already running — use check_pipeline_status instead.

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 > HPF 80Hz > noise reduction 8dB > compression 2.5:1 > safe loudness check. Lighter than podcast — preserves natural conversation dynamics.

Args: remove_noise: Apply noise reduction using first 0.5s as noise profile. Default: True remove_silence: Truncate long silences. Default: False

IMPORTANT: If remove_noise is True, the first 0.5 seconds should be room tone / silence. DO NOT call this again if a pipeline is already running — use check_pipeline_status instead.

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 > HPF 100Hz > click removal > noise reduction 12dB > compression 5:1 > safe loudness check. Designed for live performances, field recordings, and noisy environments. Noise reduction is always on at 12dB — max safe level before artifacts appear.

IMPORTANT: The first 0.5 seconds MUST be room tone / ambient noise for noise profiling. DO NOT call this again if a pipeline is already running — use check_pipeline_status instead.

ONE-CLICK PODCAST CLEANUP: Professional broadcast-quality processing. Runs in background — returns a job_id immediately. Use check_pipeline_status to monitor. Safe for badly recorded audio — only reduces peaks if too hot, never boosts.

Pipeline: DC offset > HPF 80Hz > NR 12dB > compress 3:1 (30ms attack, 200ms release) > safe loudness check. Optional: noise reduction (on by default), silence truncation (off by default).

After the pipeline finishes, the user can manually apply LUFS normalization using the loudness_normalize tool if they want to hit a specific streaming target.

Args: remove_noise: Apply noise reduction using first 0.5s as noise profile. Default: True remove_silence: Truncate long silences/dead air. Default: False

IMPORTANT: If remove_noise is True, the first 0.5 seconds should be room tone / silence. DO NOT call this again if a pipeline is already running — use check_pipeline_status instead.

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 > HPF 100Hz > noise reduction 10dB > compression 3:1 > presence EQ > safe loudness check. Tuned for singing — presence boost for clarity, higher HPF for plosive removal.

Args: remove_noise: Apply noise reduction using first 0.5s as noise profile. Default: True

IMPORTANT: If remove_noise is True, the first 0.5 seconds should be room tone / silence. DO NOT call this again if a pipeline is already running — use check_pipeline_status instead.

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: HPF > LPF > bass/treble warmth > compression 2:1 > safe loudness check Creates that warm, muffled, vintage sound by cutting highs and boosting low-mids.

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

DO NOT call this again if a pipeline is already running — use check_pipeline_status instead.

ONE-CLICK MUSIC MASTERING: Professionally master your music track with genre-tuned settings. Runs in background — returns a job_id immediately. Use check_pipeline_status to monitor.

Pipeline:

1. High-pass filter (remove sub-rumble)

2. Click removal (clean artifacts)

3. Noise reduction (optional, off by default for produced music)

4. Compression (genre-tuned, mastering-grade, no post-normalize)

5. Bass/treble sweetening (gentle, genre-tuned)

6. Safe loudness check (only reduces peaks if too hot, never boosts)

Args: style: Genre preset - "edm", "hiphop", "rock", "acoustic", "pop", "classical". Default: "edm" noise_reduce: Apply gentle noise reduction. Default: False DO NOT call this again if a pipeline is already running — use check_pipeline_status instead.

Check the status of a running pipeline. Call this after starting any auto_ pipeline to monitor progress. Poll every 15-30 seconds.

Args: job_id: The job ID returned by any auto_ pipeline tool

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

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

Apply dynamic range compression. Evens out volume differences.

For mastering, use ratio 1.5-2:1 with attack > 80ms to preserve transients. For podcasts/voice, use ratio 4-8:1 with use_peak=True for tighter control. Higher ratios (4:1+) and fast attacks are mixing tools, not mastering tools.

WARNING: normalize=True will re-peak your audio to 0 dB after compression, which can make loud audio even louder. Use loudness_normalize() instead for proper LUFS-based loudness control.

Args: threshold_db: Level above which compression starts (dB). Default: -12 noise_floor_db: Level below which audio is not boosted (dB). Default: -40 ratio: Compression ratio (e.g. 2.0 = 2:1). Default: 2.0 attack_time: How fast compressor engages (seconds). Default: 0.2 release_time: How fast compressor releases (seconds). Default: 1.0 normalize: Normalize to 0dB peak after compression. Default: False use_peak: Compress based on peaks instead of RMS (better for voice/podcast). Default: False

Move the cursor to a specific time position.

Args: time: Position in seconds

Move the cursor to the end of the project (last audio).

Move the cursor to the start of the project (time 0).

Move the cursor to the end of the selected track.

Move the cursor to the start of the selected track.

Copy the selected audio to clipboard. Select a region first.

Cut the selected audio to clipboard. Select a region first.

Delete the selected audio (does not copy to clipboard). Select a region first.

Split the selected audio at detected silences, creating separate clips.

Duplicate the selected audio into a new track.

Join selected clips into one clip.

Paste audio from clipboard at the cursor position.

Replace the selected audio with silence.

Split the clip at the cursor position or selection boundaries (in place, no new track).

Cut the selected audio without closing the gap (leaves silence where audio was).

Delete the selected audio without closing the gap (leaves silence where audio was).

Split the selected audio into a new track at the selection boundaries.

Trim audio outside the selection (delete everything except selected region).

Apply an adjustable fade with curve control.

Args: fade_type: 0=fade up (in), 1=fade down (out). Default: 0 curve: Curve shape (0=linear, positive=exponential, negative=logarithmic). Default: 0

Amplify the selected audio by a ratio. Select audio first.

Args: ratio: Amplification ratio (e.g. 1.5 = 150%, 0.5 = 50%). Must be > 0. Default: 1.0

Auto Duck: automatically reduce volume when audio is detected on another track. Place the control track (e.g. narration) above the track to duck (e.g. music). Select the track to duck before running.

Args: duck_amount_db: How much to reduce volume in dB (-24 to 0). Default: -12 inner_fade_down_len: Inner fade down length in seconds (>= 0). Default: 0 inner_fade_up_len: Inner fade up length in seconds (>= 0). Default: 0 outer_fade_down_len: Outer fade down length in seconds (>= 0). Default: 0.5 outer_fade_up_len: Outer fade up length in seconds (>= 0). Default: 0.5 threshold_db: Threshold for duck trigger in dB (-100 to 0). Default: -30 maximum_pause: Maximum pause between ducking regions in seconds (>= 0). Default: 1.0

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

Change the pitch of the selected audio without changing tempo.

Args: semitones: Number of semitones to shift (negative = lower, positive = higher)

Change speed of the selected audio (changes both tempo and pitch together).

Args: percent: Percentage change (-99 to 4900, e.g. 100 = double speed)

Change the tempo of the selected audio without changing pitch.

Args: percent: Percentage change (-95 to 3000, e.g. 50 = 50% faster, -25 = 25% slower)

Attempt to repair clipped (distorted) audio by reconstructing peaks.

Args: threshold: Clipping threshold as percentage of max amplitude (0-100). Default: 95

Crossfade between two adjacent clips on the same track. Select the junction point between two clips first.

Crossfade between two overlapping tracks. Align the tracks so they overlap, select both, then run this effect.

Apply distortion effect to the selected audio.

Args: distortion_type: Type of distortion. Default: "Hard Clipping" threshold_db: Distortion threshold in dB (-100 to 0). Default: -6.0

Apply echo effect to the selected audio.

Args: delay: Delay time in seconds. Default: 0.5 decay: Decay factor (0-1, lower = faster decay). Default: 0.5

Apply EQ curve to the selected audio.

Args: curve_name: Name of the EQ preset curve. Default: "Default" length: Filter length (odd number, 21-8191). Default: 4001

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 a high-pass filter to remove low frequencies below the cutoff. Essential as step 1 in mastering chains to remove sub-rumble.

Args: frequency: Cutoff frequency in Hz. Default: 40 (removes sub-bass rumble) rolloff: Rolloff steepness - "dB6" (6 dB/octave) or "dB12" (12 dB/octave). Default: "dB12"

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

Apply a low-pass filter to remove high frequencies above the cutoff.

Args: frequency: Cutoff frequency in Hz. Default: 20000 rolloff: Rolloff steepness - "dB6" (6 dB/octave) or "dB12" (12 dB/octave). Default: "dB6"

Remove a specific frequency (e.g. 50/60Hz hum) with a notch filter.

Args: frequency: Center frequency to remove in Hz. Default: 60 (US mains hum) q: Q factor / sharpness of the notch (0.1-20). Higher = narrower notch. Default: 1.0

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). Default: 0.25

Apply phaser effect to the selected audio.

Args: stages: Number of phaser stages (2-24, even only). Default: 2 dry_wet: Dry/wet mix (0=dry, 255=wet). Default: 128 frequency: LFO frequency in Hz (0.01-40). Default: 0.4 phase: LFO start phase in degrees (0-360). Default: 0 depth: Modulation depth (0-255). Default: 100 feedback: Feedback percentage (-100 to 100). Default: 0

Repair a very short damaged section of audio (max 128 samples). Select the damaged region first — must be extremely short. Audacity will show an error popup if the selection is too long.

Repeat the selected audio a number of times.

Args: count: Number of times to repeat (1-128). Default: 1

Apply reverb effect 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 (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. Default: -1.0 dry_gain: Dry signal gain in dB. Default: -1.0 stereo_width: Stereo width (0-100). Default: 100 wet_only: Output only the wet signal. Default: False

Reverse the selected audio. Select a region first.

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

Args: rate_change_start: Tempo change at start in % (-99 to 3000). Default: 0 rate_change_end: Tempo change at end in % (-99 to 3000). Default: 0 pitch_change_start: Pitch change at start in semitones (-12 to 12). Default: 0 pitch_change_end: Pitch change at end in semitones (-12 to 12). Default: 0

Apply a professional studio-quality fade out to the selected audio. Uses a specially shaped curve that sounds more natural than a linear fade.

Apply tremolo (volume oscillation) effect to the selected audio.

Args: frequency: Tremolo speed in Hz (1-1000). Default: 5 depth: Tremolo depth as percentage (0-100). Default: 40 waveform: 0=Sine, 1=Triangle, 2=Sawtooth, 3=InverseSawtooth, 4=Square. Default: 0

Vocal Reduction and Isolation: remove or isolate vocals from a stereo track.

Args: action: 0=Remove Vocals, 1=Isolate Vocals, 2=Remove Vocals (Mono), 3=Isolate Vocals (Mono), 4=Remove Center, 5=Isolate Center. Default: 0 low_cutoff: Low frequency cutoff in Hz. Default: 120 high_cutoff: High frequency cutoff in Hz. Default: 9000 strength: Effect strength (0-50). Default: 1.0

Apply wahwah effect to the selected audio.

Args: frequency: LFO frequency in Hz (0.1-4.0). Default: 1.5 phase: LFO start phase (0-360). Default: 0 depth: Modulation depth (0-100). Default: 70 resonance: Resonance (0.1-10). Default: 2.5 offset: Frequency offset (0-100). Default: 30

Generate a chirp (frequency sweep).

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

Generate DTMF (telephone) tones.

Args: sequence: DTMF characters (0-9, A-D, *, #). Default: "0123456789" duty_cycle: Tone vs silence ratio percentage (0-100). Default: 55 amplitude: Amplitude (0-1). Default: 0.8 duration: Total duration in seconds. Default: 1.0

Generate noise.

Args: noise_type: "White", "Pink", or "Brownian". Default: "White" amplitude: Amplitude (0-1). Default: 0.8 duration: Duration in seconds. Default: 1.0

Generate a click/rhythm track.

Args: tempo: Tempo in BPM (30-300). Default: 120 beats_per_bar: Beats per bar (1-32). Default: 4 number_of_bars: Number of bars to generate (1-1000). Default: 4 rhythm_pattern: "Uniform" or "Swing". Default: "Uniform"

Generate a tone signal.

Args: waveform: Wave type - "Sine", "Square", "Sawtooth", or "Square (no alias)". Default: "Sine" frequency: Frequency in Hz (1-20000). Default: 440 amplitude: Amplitude (0-1). Default: 0.8 duration: Duration in seconds. Default: 1.0

Get the default folder for exporting audio files. Returns the user's Music folder path. Use this when the user doesn't specify where to save.

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.

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.

How it works: The first call to NoiseReduction without an existing profile captures the selection as the noise profile. The next call applies reduction.

Add a label at the current cursor position or selection.

Args: text: Label text. Default: empty

Add a label at a specific time range.

Args: start: Start time in seconds end: End time in seconds text: Label text. Default: empty

Add many labels at once — a whole marker list in one call.

Each item is {"start": seconds, "end": seconds (optional, defaults to start for a point label), "text": string (optional)}. Every item is validated before anything is sent to Audacity, so a bad item fails the whole call rather than leaving a half-written list behind.

Args: labels: List of {"start", "end", "text"} label definitions

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

Acts on labeled regions within the current selection on the SELECTED AUDIO TRACKS — select the audio tracks and time range first. Because the timeline closes up, the labeled regions collapse rather than surviving unchanged — re-read label_list afterwards to see what remains.

Not yet independently live-tested against a running Audacity, unlike label_delete_regions/label_silence_regions/label_split_regions/ label_join_regions.

Delete a single label without touching the audio.

Get the index from label_list. Audacity has no scripting command for deleting one label, so this selects the label's own span on its own label track and split-deletes it — audio tracks are never in the selection, and nothing downstream shifts in time.

Other labels on the same track that sit entirely inside the deleted label's span would be removed as collateral, so they are re-added afterwards. A label that only partially overlaps the span may be trimmed to the boundary; check label_list afterwards if labels on that track overlap each other.

To delete a label and the audio under it, use label_delete_audio_at.

Args: index: Flat label index from label_list

Delete the audio under ONE label, picked by index — not label_delete (marker only) or label_delete_regions (every label in the current selection, no index).

This is a custom, composite operation built for podcast/transcript-based editing, not a 1:1 wrapper over a single Audacity scripting command — unlike label_cut_regions/label_delete_regions/label_silence_regions/ label_split_regions/label_join_regions, which each call exactly one Audacity command. Audacity has no "delete this one labeled take" command, so this orchestrates several: SelAllTracks, then SelectTime, then Delete/SplitDelete, then clears the leftover marker.

By default the gap closes and everything after shifts left, exactly as label_delete_regions does. Pass close_gap=False to leave silence of the same length instead, keeping the timeline length and everything after it in place.

All tracks are selected first, so label tracks ripple along with the audio and later labels stay aligned with it.

Deleting the audio does NOT remove the label — it collapses to a zero-length marker sitting where the audio used to be. This tool clears that leftover marker too, matching what clicking a label and pressing Delete does in Audacity: the audio and the label both go. Pass delete_label=False to keep it as a marker of where the cut was made. Use label_delete instead to remove a label without touching any audio.

Args: index: Flat label index from label_list close_gap: Close the gap and shift later audio left. Default: True delete_label: Also remove the label left behind. Default: True

Delete the audio under every label, closing the gaps.

Label every unwanted stretch — bad takes, dead air, noise bursts — then remove them all in one pass. Use label_delete_audio_at for a single label. Acts on labeled regions within the current selection on the SELECTED AUDIO TRACKS — select the audio tracks and time range first. Because the timeline closes up, the labeled regions collapse rather than surviving unchanged — re-read label_list afterwards to see what remains.

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

Get the index from label_list. Renaming a label is label_edit(index, text="..."); moving one of its boundaries is label_edit(index, start=...).

Args: index: Flat label index 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

Export all labels to a text file.

Args: path: Absolute path for the output labels file

Export the audio under each label as its own 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.

Not yet independently live-tested against a running Audacity — verified against the scripting reference and unit tests with mocked responses only.

Args: directory: Absolute path to the output directory format: Audio format — wav, mp3, ogg, flac, aiff, mp4. Default: wav num_channels: 1 for mono, 2 for stereo. Default: 2

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.

Not yet independently live-tested against a running Audacity — verified against the scripting reference and unit tests with mocked responses only.

Args: path: Absolute path for the output file (must not already exist) format: Chapter format — simple, cue or podlove. Default: simple

Find labels whose text contains a search string (case-insensitive).

Useful for locating a specific marker in a long recording without reading through every label.

Args: query: Text to search for within label text

Get all labels in the project as Audacity's raw GetInfo response.

Prefer label_list — it returns the same labels already parsed, with the index each one needs for label_edit and label_delete.

Import labels from a text file.

Args: path: Absolute path to the labels text file

Join the audio clips across every labeled region back together.

The inverse of label_split_regions. Acts on labeled regions within the current selection on the SELECTED AUDIO TRACKS — select the audio tracks and time range first. The labels themselves stay where they are.

List every label with its index, timing and text.

Returns labels sorted by Audacity's own flat index, which is what label_edit and label_delete take. Call this first whenever you need to modify a specific label, rather than guessing an index.

Create labels at regular time intervals across the selection or project.

Args: interval: Time between labels in seconds. Default: 30 adjust: Adjust interval to fit selection evenly. Default: False label_text: Text for each label (labels will be numbered). Default: empty

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

Use when the material must not get shorter — redacting a name, muting a noise burst in a take that has to stay in sync. Acts on labeled regions within the current selection on the SELECTED AUDIO TRACKS — select the audio tracks and time range first. The labels themselves stay where they are.

Split the audio clips at every label boundary.

Prepares segment boundaries for separate handling without removing anything. Acts on labeled regions within the current selection on the SELECTED AUDIO TRACKS — select the audio tracks and time range first. The labels themselves stay where they are.

Apply a limiter to prevent audio from exceeding a threshold. Use after compression.

Default ceiling is -1.0 dB, the industry standard for streaming platforms.

Args: limit_db: Maximum output level (dB). Default: -1.0 hold_ms: Hold time in milliseconds. Default: 10.0 makeup_gain: Apply makeup gain ("Yes" or "No"). Default: "No" limiter_type: "SoftLimit", "HardLimit", "SoftClip", "HardClip". Default: "SoftLimit" gain_left: Input gain for left channel (dB). Default: 0.0 gain_right: Input gain for right channel (dB). Default: 0.0

Normalize audio to a target perceived loudness in LUFS.

DANGER — READ BEFORE USING: This tool can DESTROY audio if used incorrectly. It boosts OR reduces audio to hit the target LUFS. On quiet or poorly recorded audio, it may boost by 20-30 dB, causing severe clipping and distortion that ruins the file.

DO NOT use this tool:

• Right after a pipeline (pipelines already handle loudness safely)

• On raw/unprocessed audio (clean it up first)

• Without first running auto_analyze_audio to check current levels

• If the audio peaks below -20 dB (it's too quiet — use normalize first to gently raise levels)

ONLY use this tool when the user EXPLICITLY asks for LUFS normalization AND the audio has already been processed and has healthy levels (peaks between -6 dB and -1 dB).

Targets (only use these values):

• -16 LUFS: Podcast, broadcast, Apple Music

• -14 LUFS: Spotify, YouTube, most streaming

• -11 LUFS: Loud masters (hip-hop/EDM)

Args: lufs_level: Target loudness in LUFS (-50 to -5). 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

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.

WARNING: Values above 20 dB risk audible artifacts (warbling, metallic sound). Use 6-12 dB for gentle cleanup, 12-20 dB for moderate noise. Only exceed 20 dB for extremely noisy recordings where some artifact trade-off is acceptable.

Args: noise_reduction_db: Amount of noise reduction in dB (0-48). Default: 12 sensitivity: How sensitive the detection is (0-24). Default: 6 frequency_smoothing: Number of frequency smoothing bands (0-12). Default: 3

Normalize the selected audio to a target peak level.

WARNING: This boosts OR reduces audio to hit the target. If audio peaks at -30 dB and you normalize to -1 dB, it will BOOST by 29 dB — potentially blowing out the audio. ALWAYS check current audio levels first (use project_get_info) before normalizing.

Guidelines — choose your target based on what comes next:

• -3 dB (default): Safe general-purpose level with headroom for further processing

• -6 dB: Conservative, good for unknown or problematic audio

• -1 dB: ONLY as a final ceiling on already-mastered audio (never on raw audio)

• -12 dB or lower: For very quiet audio that needs gentle boosting

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

Close the current Audacity project.

Open the metadata editor dialog to view/edit track metadata (title, artist, etc.). This opens a modal dialog in Audacity — the command waits until the user closes it.

Export the project audio to a file. Format is determined by file extension.

MANDATORY: ALWAYS tell the user where the file will be saved BEFORE exporting. Example: "I'll save your audio to C:\Users\Name\Music\file.mp3"

NEVER save directly to the user's home folder (e.g. ~/file.mp3 or C:\Users\Name\file.mp3). ALWAYS save to a subfolder. If the user doesn't specify a path, call get_default_export_folder to get their Music folder and save there. Acceptable locations:

• Music folder: ~/Music/file.mp3

• Documents folder: ~/Documents/file.mp3

• Desktop: ~/Desktop/file.mp3 NEVER save to the home folder root — this clutters the user's home directory.

Args: path: Absolute path for exported file. Extension determines format (wav, mp3, ogg, flac, aiff). num_channels: Number of channels (1=mono, 2=stereo). Default: 2

Export all labels to a text file.

Args: path: Absolute path for the exported labels file

Get information about the current project.

Args: info_type: Type of info to retrieve. One of: Tracks, Clips, Envelopes, Labels, Boxes, Commands

Import an audio file into the current project. Creates a new track.

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

Import a MIDI file into the current project.

Args: path: Absolute path to the MIDI file (.mid, .midi)

Create a new empty Audacity project.

Open an existing Audacity project file (.aup3).

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

Save the current Audacity project. ONLY call this when the user explicitly asks to save. Do NOT auto-save after effects or pipelines — the user controls when to save.

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

Args: path: Absolute path for the new .aup3 file

About: Display information about Audacity. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ApplyMacro: Apply a defined macro to the project. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

BeatsandMeasures: Set timeline format to beats and measures. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ChangeAudio: Open the audio host/interface selection dialog. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

CheckDeps: Check dependencies for the current project. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

CompareAudio: Compare audio regions between tracks. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

CrashReport: Generate a support report for troubleshooting. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

CursorLeft: Move the cursor left by one unit. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

CursorLongJumpLeft: Move the cursor 15 seconds left. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

CursorLongJumpRight: Move the cursor 15 seconds right. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

CursorRight: Move the cursor right by one unit. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

CursorShortJumpLeft: Move the cursor 1 second left. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

CursorShortJumpRight: Move the cursor 1 second right. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Delay: Apply a delay effect. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

DeviceInfo: Show technical information about audio devices. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Drag: Simulate a mouse drag for UI interactions. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

EditLabels: Open the Label Editor dialog. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Exit: Close all project windows and exit Audacity. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ExportAudio: Export audio files in various formats. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

FirstTrack: Focus the first track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

GetPreference: Retrieve a preference value. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

GraphicEq: Apply a graphic equalizer effect. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Help: Get help information for a command. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ImportAudio: Import an audio file as a new track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ImportRaw: Import raw audio data without headers. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

InputDevice: Open the recording device selection dialog. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Karaoke: Display the karaoke window. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

LastTrack: Focus the last track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Log: Open the Audacity log window. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ManageAnalyzers: Open the analyzers plugin manager. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ManageMacros: Create or edit macros. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ManageTools: Open the tools/effects/generators manager. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Manual: Open Audacity's manual in the default web browser. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Message: Send a test message to Audacity. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

MidiDeviceInfo: Show information about MIDI devices. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

MinutesandSeconds: Set timeline format to minutes and seconds. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

MixerBoard: Switch to the mixer board view. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

NextFrame: Move focus forward from toolbars to tracks. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

NextTrack: Focus the next track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

NextWindow: Navigate to the next window. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Nyquist: Open the Nyquist scripting prompt. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Open: Open an audio file, list of files, or project. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

OutputDevice: Open the playback device selection dialog. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

PasteNewLabel: Paste text from the clipboard into a new label. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Paulstretch: Apply an extreme time-stretch effect. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

PlayStop: Toggle playback on and off. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

PlayStopSelect: Play/Stop and update cursor position. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Pluck: Generate a plucked tone effect. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

PrevFrame: Move focus backward from toolbars to tracks. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

PrevTrack: Focus the previous track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

PrevWindow: Navigate to the previous window. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Print: Print all waveforms in the current project. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

PunchAndRoll: Start punch and roll recording. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

QuickHelp: Display a brief help message. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Record2ndChoice: Start recording on a new track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Redo: Redo the most recent undone action. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

RissetDrum: Generate a continuously evolving drum sound. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Save: Save the current project. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SaveAs: Save the current project under a new name. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SaveCompressed: Save a compressed copy of the project. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SaveCopy: Save a lossless copy of the project. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Screenshot: Capture a screenshot of Audacity (short format). Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Scrub: Scrub through audio. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Seek: Jump to a specified position in the audio. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SelCursorStoredCursor: Select audio from current cursor to stored position. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Select: Modify selection based on parameters. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SelEnd: Set selection from cursor to end of track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SelStart: Set selection from cursor to start of track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SetClip: Modify properties (color, start time) of a clip. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SetEnvelope: Adjust the envelope value at a specified time. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SetPreference: Set a preference value (with optional reload). Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SetProject: Change project window properties (size, position, caption). Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SetTrackAudio: Set audio properties (mute, solo, gain, pan) for a track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ShiftDown: Move focus downward and select the next track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ShiftUp: Move focus upward and select the previous track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ShowClipping: Toggle display of clipping in the waveform. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ShowExtraMenus: Toggle extra menus display. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SnapToNearest: Snap selections to the nearest time unit. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SnapToOff: Disable snapping for selections. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SnapToPrior: Snap selections to the previous time unit. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SoundActivation: Toggle sound-activated recording. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

SoundActivationLevel: Set the threshold level for sound-activated recording. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

StoreCursorPosition: Store current cursor position for later selection. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TimerRecord: Open Timer Record dialog. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Toggle: Toggle focus on the current track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackClose: Close the focused track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackGain: Open the gain dialog for the focused track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackGainDec: Decrease the gain on the focused track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackGainInc: Increase the gain on the focused track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackMoveBottom: Move the focused track to the bottom. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackMoveDown: Move the focused track down one position. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackMoveTop: Move the focused track to the top. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackMoveUp: Move the focused track up one position. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackMute: Toggle mute on the focused track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackPan: Open the pan dialog for the focused track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackPanLeft: Pan the focused track to the left. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackPanRight: Pan the focused track to the right. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TrackSolo: Toggle solo on the focused track. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

TypeToCreateLabel: Create a label by typing (if enabled). Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Undo: Undo the most recent editing action. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

UndoHistory: Display the undo history window. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Updates: Check for updates for Audacity. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ZoomIn: Zoom in horizontally. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ZoomNormal: Reset zoom to the default view. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ZoomOut: Zoom out horizontally. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ZoomSel: Zoom to fill the current selection. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

ZoomToggle: Toggle between two preset zoom levels. Static no-argument Audacity action. May open a dialog or change project state; inspect the command name first.

Select all audio in all tracks. Selects both tracks and time range.

Select the clip under the cursor.

Select from the current cursor position to the end of the track.

Deselect all audio.

Select a time region in the current track(s). Many effects operate on the selection.

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.

Add a new empty label track to the project.

Add a new mono audio track to the project.

Add a new stereo audio track to the project.

Align selected tracks end-to-end (sequentially). Select the tracks first.

Get information about all tracks in the project (names, types, rates, etc.).

Mix and render selected tracks into a single track. Select tracks first.

Mix and render selected tracks into a new track, keeping the originals. Select tracks first.

Mute or unmute a track.

Args: track: Track index (0-based) mute: True to mute, False to unmute

Mute all tracks in the project.

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

Resample the selected track to a new sample rate.

Args: rate: Target sample rate in Hz (e.g. 44100, 48000, 96000). Must be > 0.

Select a track by index. Many operations require selecting a track first.

Args: track: Track index (0-based)

Set properties of a track by index.

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

Convert the selected stereo track to mono. Select the track first.

Unmute all tracks in the project.

[EXPERIMENTAL] Transcribe the entire project audio using faster-whisper (local, offline). Requires separate setup — see installation guide. If this fails, tell the user transcription is experimental and point them to the Transcription Setup docs.

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

Do NOT call transcription_set_model first — this handles model loading automatically.

After transcription completes, TELL the user where the transcript was saved or offer to save it. Always tell the user the file location so they can find it.

Language auto-detection can occasionally misidentify the language (background music, noise, a short/ambiguous clip) and transcribe genuinely-English audio in the wrong script entirely. If you already know the audio's language from context, pass language explicitly (e.g. "en") instead of relying on auto-detect, or set task="translate" to force English output regardless of the spoken language. If a result comes back in an unexpected language/script, just retry with THIS SAME tool and the corrected language/task.

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 — see installation guide.

Runs in BACKGROUND — returns a job_id immediately. Use check_transcription_status to monitor progress.

Select a region first, then call this tool.

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

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 export to a subtitle or text file. Requires separate setup — see installation guide.

ALWAYS tell the user where the file will be saved BEFORE starting. If user doesn't specify a path, call get_default_export_folder to get a real path. NEVER guess paths like /home/user/... — always use absolute Windows paths like C:\Users\Name\Documents\transcript.srt

Runs in BACKGROUND — returns a job_id immediately. Use check_transcription_status to monitor progress.

Language auto-detection can occasionally misidentify the language (background music, noise, a short/ambiguous clip) and transcribe genuinely-English audio in the wrong script entirely. If you already know the audio's language from context, pass language explicitly (e.g. "en"), or set task="translate" to force English output regardless of the spoken language. Retry with THIS SAME tool and the corrected language/task — use a new path since an existing file at the same path is rejected below.

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] Transcribe audio and add Audacity labels at each segment timestamp. Requires separate setup — see installation guide.

Runs in BACKGROUND — returns a job_id immediately. Use check_transcription_status to monitor progress.

Language auto-detection can occasionally misidentify the language (background music, noise, a short/ambiguous clip) and transcribe genuinely-English audio in the wrong script entirely. If you already know the audio's language from context (the user said so, or the labels came back in an unexpected script), don't guess — pass language explicitly (e.g. "en"), or set task="translate" to force English output regardless of the spoken language. Retry with THIS SAME tool and the corrected language/task; there's no need to switch to a different transcription tool to fix a bad language guess.

If labels from a previous attempt need clearing first: track_select 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] 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. Requires separate setup — see installation guide.

Runs in BACKGROUND — returns a job_id immediately. Use check_transcription_status to monitor progress.

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"

Get the current playback position in seconds.

Toggle pause during playback or recording.

Start playback from the current cursor position.

Play a specific time region.

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

Start recording on a new track.

Set the playback cursor position.

Args: time: Position in seconds

Stop playback or recording.

Truncate or compress silence in the selected audio. Great for removing dead air.

Args: threshold_db: Volume below this is considered silence (dB). Default: -40 min_duration: Minimum silence duration to act on (seconds). Default: 0.5 truncate_to: Truncate silence to this duration (seconds). Default: 0.3 compress_percent: Compress silence by this percentage (only for Compress action). Default: 50 action: "Truncate" or "Compress". Default: "Truncate"