Metadata-Version: 2.4
Name: audatron
Version: 0.2.2
Summary: audatron — headless, deterministic, provenance-attested LLM-driven Audacity: natural language drives track editing, noise removal, and mastering via a headless DSP engine with closed-loop listening (hear/listen), 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

[![CI](https://github.com/Dream-Pixels-Forge/audatron/actions/workflows/pr-validation.yml/badge.svg)](https://github.com/Dream-Pixels-Forge/audatron/actions)
[![PyPI version](https://img.shields.io/pypi/v/audatron)](https://pypi.org/project/audatron/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Provenance: SLSA](https://img.shields.io/badge/provenance-SLSA%20attested-brightgreen.svg)](https://pypi.org/project/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

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

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

```python
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 | Audacity-MCP (`xDarkzx/Audacity-MCP`) | cochlea | Ableton MCP (ableton-copilot-mcp) |
|---|---|---|---|---|
| GUI automation | no — headless | yes (drives the live Audacity GUI) | no | yes (live Ableton) |
| Deterministic DSP | yes | n/a (GUI-driven) | yes | n/a |
| MCP tool surface | yes (`audatron-mcp`) | yes | no | yes |
| Native Audacity-4 SQLite `.aup3` | yes | n/a | no | n/a |
| Closed-loop listening (`hear`/`listen`) | yes | no | no | no |

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

| 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 |
| `listen`       | WAV data-URI (16 kHz mono, 20 s cap) for audio-capable LLMs |
| `hear`         | local text-embedding: log-mel + silence + onsets + numbers |
| `status`       | session overview: stats + paths + sync state + undo depth |
| `history` / `undo` / `redo` | deck state |
| `load`         | replace the deck with a new file |

## Development

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