audatron

Natural-language audio production, mirrored live into Audacity.

audatron is a realtime, LLM-driven toolchain: you prompt an agent (or any coding tool — Claude Code, Codex, opencode, kimi, pi, qwen code —) in plain English, and it drives a real Audacity workflow in your browser: inspect the waveform, trim tracks, strip noise, master to a target loudness, and export — while the matching Audacity project + TCL/Lua scripts are written so you can watch the edits land on the open project.

   you (natural language)
        │
        ▼
   ┌──────────────────────────────┐
   │  audatron agent (LLM loop)   │   ← Anthropic / OpenAI-compatible / Ollama
   └──────────────────────────────┘
        │  tool calls
        ▼
   ┌──────────────────────────────┐
   │  DSP engine (headless)       │   ← trim / gain / normalize / noise / master / export
   └──────────────────────────────┘
        │  every step
        ▼
   ┌──────────────────────────────┐
   │  Audacity bridge             │   ← .aup3 project + generated TCL + Lua scripts
   └──────────────────────────────┘

Install

pip install -e .
audatron doctor        # verify numpy, ffmpeg, Audacity, LLM backends

Quickstart

# 1. generate a test clip
audatron demo demo.wav --freq 440 --seconds 3

# 2. one-shot: natural language in, mastered wav out
audatron run "trim to 2s, remove hiss, master to -14 LUFS, export wav" demo.wav --backend anthropic

# 3. interactive REPL
audatron chat demo.wav --backend anthropic
#    you › make it sound like a radio
#    you › sync          ← pushes the deck into a live Audacity project

The LLM agent is optional

Every operation the agent can perform is also available without an LLM:

audatron inspect demo.wav              # stats + spectral analysis
audatron sync demo.wav                 # Audacity project + TCL/Lua, no LLM

Audacity integration

audatron sync writes:

The .native.aup3 is a real SQLite database matching Audacity 4's on-disk format: four tables (project, sampleblocks, autosave, project_history), float32 sample blocks sized the way the app writes them (up to 262144 samples / 1 MiB), and the app's dict/doc record streams. It opens natively with the waveform + track layout intact, no external WAV side-file needed. The XML .aup3 is kept as a fallback for older Audacity builds.

Open it in your running Audacity 4:

"C:\Program Files\Audacity 4\bin\Audacity4.exe" <project>\river_master-proj.native.aup3

or let audatron launch it for you:

audatron sync river_master.wav --open-audacity    # opens the native project
audatron sync river_master.wav --run-tcl          # + auto-runs the TCL macro

MCP server

audatron ships an MCP stdio server so any MCP-capable coding agent can drive it. The tools are the same DSP surface the CLI agent uses.

audatron-mcp        # newline-delimited JSON-RPC 2.0 over stdio

Wiring it into a coding agent — see dev-notes/MCP-SETUP.md for Claude Code, Codex, opencode, kimi, qwen-code, and generic MCP clients.

Tool surface

Development

pip install -e ".[test]"
python -m pytest -q          # 102 tests, ~45s

Layout:

src/audatron/
  dsp.py          # headless DSP engine (numpy + soundfile)
  session.py      # stateful deck + op history
  tools.py        # tool surface shared by CLI agent + MCP
  agent.py        # LLM agent loop (Anthropic/OpenAI/Ollama)
  backends.py     # LLM provider clients (+ streaming)
  live.py         # realtime foreground view (token stream + waveform)
  audacity.py     # .aup3 + TCL/Lua generation + Audacity lookup
  aup3.py        # native Audacity-4 SQLite .aup3 writer
  mcp_server.py   # MCP stdio JSON-RPC server
  cli.py          # typer CLI
tests/            # pytest: DSP, tools, agent (mocked), MCP, e2e, CLI, aup3, live