audacity-toolkit

---

A Python toolkit for automating, extending, and integrating with Audacity on Windows. Built for developers, audio engineers, and researchers who need programmatic control over Audacity's workflow — from batch file processing to audio analysis pipelines.

Audacity is a powerful, open-source, cross-platform audio editor widely used for recording, editing, and analyzing audio files. This toolkit wraps Audacity's scripting interface and file formats into a clean, Pythonic API so you can build automated audio workflows without leaving your terminal.

---

✨ Features

• 🎛️ Audacity Scripting Bridge — Send commands directly to a running Audacity instance on Windows via its named pipe interface (mod-script-pipe)
• 📁 Batch File Processing — Automate repetitive tasks like noise reduction, normalization, and format conversion across hundreds of files
• 📊 Audio Data Extraction — Read and parse Audacity project files (.aup3) to extract track metadata, labels, and clip boundaries
• 🔊 Waveform Analysis — Compute amplitude statistics, silence detection, and spectral summaries using extracted PCM data
• 🏷️ Label Track Automation — Programmatically create, read, and modify Audacity label tracks for annotation workflows
• 🔄 Export Pipeline — Trigger multi-format exports (WAV, MP3, FLAC, OGG) with custom encoding settings from Python scripts
• 🧩 Macro Runner — Load and execute Audacity macros (.txt macro files) programmatically as part of larger pipelines
• 🪟 Windows Process Management — Launch, detect, and gracefully shut down Audacity processes from your automation scripts

---

📋 Requirements

Requirement	Version / Notes
Python	3.8 or higher
Audacity	2.4.0 or higher (Windows build)
Operating System	Windows 10 / Windows 11
mod-script-pipe	Must be enabled in Audacity preferences
numpy	≥ 1.22.0
scipy	≥ 1.8.0
pydub	≥ 0.25.1
ffmpeg	Required by pydub for MP3/AAC support

Note: The Audacity scripting pipe (mod-script-pipe) must be enabled before using the bridge features. In Audacity, go to Edit → Preferences → Modules and enable mod-script-pipe, then restart.

---

🚀 Installation

Install from PyPI:

pip install audacity-toolkit

Install from source:

git clone https://github.com/your-org/audacity-toolkit.git
cd audacity-toolkit
pip install -e ".[dev]"

Install with optional analysis dependencies:

pip install audacity-toolkit[analysis]

---

⚡ Quick Start

from audacity_toolkit import AudacityBridge

# Connect to a running Audacity instance on Windows
bridge = AudacityBridge()

# Import an audio file into the current project
bridge.import_audio("C:/audio/interview_raw.wav")

# Apply noise reduction using Audacity's built-in effect
bridge.apply_effect("NoiseReduction", noise_gain=24, sensitivity=6.0)

# Normalize to -1 dB
bridge.apply_effect("Normalize", peak_amplitude=-1.0)

# Export the result as a high-quality WAV file
bridge.export_audio(
    output_path="C:/audio/interview_clean.wav",
    format="WAV",
    sample_rate=44100,
    bit_depth=24
)

print("Done. Clean audio exported successfully.")

---

📖 Usage Examples

1. Connecting to Audacity's Scripting Pipe

Before sending commands, Audacity must be open and mod-script-pipe must be active.

from audacity_toolkit import AudacityBridge
from audacity_toolkit.exceptions import PipeConnectionError

try:
    bridge = AudacityBridge(timeout=10)
    version = bridge.get_audacity_version()
    print(f"Connected to Audacity {version} on Windows")
except PipeConnectionError as e:
    print(f"Could not connect: {e}")
    print("Make sure Audacity is open and mod-script-pipe is enabled.")

---

2. Batch Processing Audio Files

Process an entire directory of recordings — apply effects and export in one pass.

from pathlib import Path
from audacity_toolkit import AudacityBridge, BatchProcessor

bridge = AudacityBridge()
processor = BatchProcessor(bridge)

input_dir = Path("C:/recordings/raw")
output_dir = Path("C:/recordings/processed")
output_dir.mkdir(parents=True, exist_ok=True)

# Define an effect chain to apply to every file
effect_chain = [
    {"effect": "LowPassFilter", "frequency": 8000, "rolloff": 6},
    {"effect": "Normalize",     "peak_amplitude": -2.0},
    {"effect": "TruncateSilence", "threshold": -40.0, "min_duration": 0.5},
]

results = processor.run(
    input_pattern=input_dir / "*.wav",
    output_dir=output_dir,
    effects=effect_chain,
    export_format="WAV",
)

for file_path, status in results.items():
    print(f"{file_path.name}: {status}")

---

3. Extracting Metadata from Audacity Project Files

Parse .aup3 project files (SQLite-based) to extract track and label information without opening the GUI.

from audacity_toolkit.project import AudacityProject

project = AudacityProject("C:/projects/podcast_ep12.aup3")

# List all tracks in the project
for track in project.tracks:
    print(f"Track: {track.name} | Type: {track.kind} | Duration: {track.duration:.2f}s")

# Read label tracks for annotation data
for label in project.get_labels(track_name="Segments"):
    print(f"  [{label.start:.2f}s → {label.end:.2f}s] {label.text}")

Example output:

Track: Interview Audio  | Type: wave  | Duration: 1842.30s
Track: Segments         | Type: label | Duration: 1842.30s
  [0.00s → 14.52s] intro
  [14.52s → 387.10s] guest_q1
  [387.10s → 601.88s] guest_q2

---

4. Silence Detection and Audio Analysis

Use the analysis module to detect silence regions and compute basic loudness statistics.

from audacity_toolkit.analysis import AudioAnalyzer

analyzer = AudioAnalyzer("C:/audio/field_recording.wav")

# Detect silence regions
silence_regions = analyzer.detect_silence(
    threshold_db=-50.0,
    min_silence_duration=1.0  # seconds
)

print(f"Found {len(silence_regions)} silence region(s):")
for region in silence_regions:
    print(f"  {region.start:.2f}s – {region.end:.2f}s ({region.duration:.2f}s)")

# Summary statistics
stats = analyzer.loudness_stats()
print(f"\nPeak amplitude : {stats.peak_db:.1f} dBFS")
print(f"RMS level      : {stats.rms_db:.1f} dBFS")
print(f"Dynamic range  : {stats.dynamic_range:.1f} dB")

---

5. Running Audacity Macros Programmatically

If you already have saved Audacity macros, run them against any file from Python.

from audacity_toolkit import AudacityBridge
from pathlib import Path

bridge = AudacityBridge()

macro_file = Path("C:/Users/YourName/AppData/Roaming/audacity/Macros/CleanPodcast.txt")
target_files = list(Path("C:/inbox").glob("*.wav"))

for audio_file in target_files:
    bridge.import_audio(str(audio_file))
    bridge.run_macro(macro_file)
    output_path = Path("C:/outbox") / audio_file.name
    bridge.export_audio(str(output_path), format="MP3", bitrate=192)
    bridge.close_project(save=False)
    print(f"Processed: {audio_file.name}")

---

6. Launching and Managing the Audacity Process

from audacity_toolkit.process import AudacityProcess

# Launch Audacity from a known install path (common Windows default)
proc = AudacityProcess(
    executable=r"C:\Program Files\Audacity\Audacity.exe"
)

with proc.running():
    bridge = proc.get_bridge()
    bridge.import_audio("C:/audio/sample.flac")
    bridge.apply_effect("Normalize", peak_amplitude=-3.0)
    bridge.export_audio("C:/audio/sample_norm.flac", format="FLAC")
# Audacity closes cleanly when the context manager exits

---

🗂️ Project Structure

audacity-toolkit/
├── audacity_toolkit/
│   ├── __init__.py
│   ├── bridge.py          # Named pipe interface to Audacity
│   ├── batch.py           # BatchProcessor for bulk operations
│   ├── project.py         # .aup3 project file parser
│   ├── analysis.py        # Waveform and loudness analysis
│   ├── process.py         # Windows process management
│   ├── macros.py          # Macro file loader and runner
│   └── exceptions.py      # Custom exception classes
├── tests/
│   ├── test_bridge.py
│   ├── test_project.py
│   └── test_analysis.py
├── examples/
│   └── batch_podcast_workflow.py
├── pyproject.toml
├── CONTRIBUTING.md
└── README.md

---

🤝 Contributing

Contributions are welcome and appreciated. If you find a bug, have a feature request, or want to improve the documentation, please open an issue or submit a pull request.

To set up a development environment:

git clone https://github.com/your-org/audacity-toolkit.git
cd audacity-toolkit
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -e ".[dev]"
pre-commit install

Run the test suite:

pytest tests/ -v

Please follow the Contributor Covenant code of conduct in all interactions. See CONTRIBUTING.md

---

Download

Click here to download

📥 Download

➡️ Click here to get the software