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
   └──────────────────────────────┘

Headless by design

No GUI automation, no hidden state: audatron runs its entire DSP pipeline headless and deterministically — same input, same calls, same bytes. Every release is published to PyPI with SLSA provenance attestations, so what you pip install is verifiably what CI built. The Audacity bridge writes artifacts, not clicks.

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.

Closed-Loop Listening

audatron's most defensible trait: the agent can hear the result of every edit and reason from the numbers, instead of declaring success on faith.

   1. inspect ──► 2. edit (trim / noise_reduce / master / …) ──► 3. hear ──► 4. listen again
                                                            │            verify the region
                                                            ▼         (silence %, centroid,
                                                           good?        onsets, peak dB)
                                                            │
                                          good → export/sync ──┘
                                          bad  → undo/redo, retry

• hear — a local, deterministic text-embedding of a segment (log-mel grid + silence map + onset grid + loudness/centroid). ~400 tokens, no audio input required — works on any LLM, including text-only local models.
• listen — a base64 WAV data-URI (16 kHz mono, 20 s cap) for audio-capable backends; hear is the text-only fallback.

from audatron.dsp import load_audio
from audatron.session import Session
from audatron.tools import dispatch

s = Session(load_audio("in.wav"), Path("in.wav"))
before = dispatch(s, "hear", {"start_s": 0.0, "end_s": 5.0, "detail": "full"})
dispatch(s, "noise_reduce", {"profile_seconds": 0.5, "strength": 1.0})
after = dispatch(s, "hear", {"start_s": 0.0, "end_s": 5.0})
assert after["silence_pct"] < before["silence_pct"]   # the noise is gone

How it differs

audatron is the only tool in this set that is headless, deterministic, and augmented with a feedback loop — the agent verifies every destructive edit by hearing the numbers, not by trusting the operation succeeded. (Capability claims about competitors are from their public READMEs; verify before citing.)

Tool surface

Development

pip install -e ".[test]"
python -m pytest -q          # 100+ tests, ~45–80s

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
  embed.py        # local text-embedding (hear) — log-mel + silence + onsets
  cli.py          # typer CLI
tests/            # pytest: DSP, tools, agent (mocked), MCP, e2e, CLI, aup3, live