Metadata-Version: 2.4
Name: audatron
Version: 0.2.0
Summary: audatron — LLM-driven realtime Audacity: natural language drives track editing, noise removal, and mastering, with a headless DSP engine plus auto-generated Audacity TCL scripts, an agent chat REPL, and an MCP stdio server.
Author: DREAM PIXELS FORGE
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.26
Requires-Dist: soundfile>=0.12
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: httpx>=0.27
Requires-Dist: pydub>=0.25
Provides-Extra: noisereduce
Requires-Dist: noisereduce>=3.0; extra == "noisereduce"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"

# 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

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

## Quickstart

```bash
# 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:

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

## Audacity integration

`audatron sync` writes:

| File                        | Purpose                                            |
|---------------------------|----------------------------------------------------|
| `deck.wav`                 | clean copy of the current deck                     |
| `<name>.aup3`             | Audacity 3.x XML project (fallback)               |
| `<name>.native.aup3`     | **native Audacity 4 SQLite project** (primary)    |
| `audatron.tcl`            | generated TCL script (run via Tools → Macros)     |
| `audatron.lua`            | generated Lua script (Audacity 2.x scripting)      |
| `audatron.json`           | machine-readable manifest of the ops               |

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.

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

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

## Tool surface

| Tool           | What it does |
|----------------|--------------|
| `inspect`      | sr, duration, peak, loudness dB, silence ratio |
| `analyze`      | spectral centroid, onsets, silence ranges |
| `trim`         | keep a `[start, end]` window |
| `gain`         | apply ± dB |
| `normalize`     | peak-normalize to a target dBFS |
| `noise_reduce` | spectral-subtraction denoise (profile from head) |
| `master`       | loudness-normalize to target LUFS + peak ceiling |
| `export`       | write wav / flac / mp3 / ogg |
| `sync`         | generate the Audacity project + scripts |
| `history` / `undo` | deck state |
| `load`         | replace the deck with a new file |

## Development

```bash
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
```
