Metadata-Version: 2.4
Name: audamcp
Version: 0.2.0
Summary: MCP server for professional audio editing, stems separation, mastering, and Audacity 3.x bridge
Project-URL: Homepage, https://github.com/Dream-Pixels-Forge/audacity-mcp
Project-URL: Repository, https://github.com/Dream-Pixels-Forge/audacity-mcp
Project-URL: Issues, https://github.com/Dream-Pixels-Forge/audacity-mcp/issues
Author: DREAM-PIXELS-FORGE
License: MIT
License-File: LICENSE
Keywords: audacity,audio,demucs,llm-tools,mastering,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Editors
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: librosa>=0.10
Requires-Dist: mcp>=1.2.0
Requires-Dist: noisereduce>=3.0
Requires-Dist: numpy>=1.24
Requires-Dist: pedalboard>=0.9
Requires-Dist: pydantic>=2.0
Requires-Dist: pydub>=0.25
Requires-Dist: pyloudnorm>=0.1.0
Requires-Dist: scipy>=1.10
Requires-Dist: soundfile>=0.12
Requires-Dist: tqdm>=4.65
Provides-Extra: ml
Requires-Dist: demucs>=0.0.2; extra == 'ml'
Requires-Dist: torch>=2.1; extra == 'ml'
Requires-Dist: torchaudio>=2.1; extra == 'ml'
Provides-Extra: ml-dfn
Requires-Dist: deepfilternet>=0.5; extra == 'ml-dfn'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/banner.png" alt="audaMcp banner" width="100%">
</p>

# audaMcp

An MCP (Model Context Protocol) server that gives LLMs professional audio
editing capabilities: stems separation, neural dereverb/de-echo, repair
(declick/declip/decrackle), intelligent silence removal, mastering, and
an optional Audacity 3.x bridge.

Runs locally — no cloud, no API keys for the audio processing itself.

## What it does

| Category | Tools | Needs ML? |
|---|---|---|
| **Analysis** | `auda_health`, `auda_analyze`, `auda_probe` | no |
| **Repair** | `auda_reduce_noise`, `auda_dereverb`, `auda_deecho`, `auda_declick`, `auda_declip`, `auda_decrackle` | dereverb yes |
| **Silence** | `auda_remove_silence`, `auda_trim_silence`, `auda_split_on_silence` | no |
| **Stems** | `auda_separate_stems`, `auda_isolate_vocals`, `auda_karaoke`, `auda_isolate_drums`, `auda_isolate_bass` | yes (Demucs) |
| **Mastering** | `auda_master`, `auda_loudness_normalize`, `auda_peak_normalize`, `auda_compressor`, `auda_limiter`, `auda_eq`, `auda_stereo_widen`, `auda_reverb_add` | no |
| **Edit** | `auda_convert`, `auda_trim`, `auda_fade`, `auda_concat`, `auda_mix`, `auda_speed` | no |
| **Audacity bridge** | `auda_audacity_status`, `auda_audacity_do`, `auda_audacity_import`, `auda_audacity_export`, `auda_audacity_apply_master` | no (needs Audacity 3.x) |

All tools take **local file paths** in, write a new file out, and return
JSON with `metrics_before` / `metrics_after` so the LLM can verify the
change landed. Audio never goes over the wire.

## Quick start

### CLI install (terminal use)

```bat
:: Windows
pip install audamcp          # core DSP only (~10 MB)
pip install audamcp[ml]      # + Demucs stem separation (~1.3 GB)
```

```bash
# macOS / Linux
pip install audamcp
pip install audamcp[ml]
```

### MCP server install (for LLM clients)

```bat
:: Windows
cd audamcp
scripts\install.bat --cuda      :: GPU (RTX 3050 etc.) — recommended
:: or
scripts\install.bat             :: CPU only
:: or
scripts\install.bat --no-ml     :: skip Demucs/dereverb entirely

scripts\register_clients.py     :: register with all installed clients
python scripts\smoke_test.py    :: verify
```

```bash
# macOS / Linux
cd audamcp
./scripts/install.sh --cuda     # or omit flag for CPU
python scripts/register_clients.py
python scripts/smoke_test.py
```

Then restart your LLM client and call `auda_health` to confirm.

## Supported LLM clients

`register_clients.py` auto-detects and configures:

- **Claude Code** — `claude mcp add`
- **Claude Desktop** — writes `claude_desktop_config.json`
- **Cursor** — writes `.cursor/mcp.json`
- **GLM / ZCode** — writes `configs/glm_zcode.json` + prints the snippet
- **Codex / other MCP** — `codex mcp add` + `configs/codex.toml`

The server speaks stdio MCP, so any MCP-aware client works.

## GPU / memory policy

- Defaults to **auto-detect**: uses CUDA if free VRAM ≥ ~1 GB, else CPU.
- Per-call `device="cpu"` / `"cuda"` override on every ML tool.
- **Long files on small GPUs** (RTX 3050 / 4GB) auto-segment via Demucs's
  native `--segment` flag — no OOM crashes. See `audamcp/config.py`.
- CUDA OOM during Demucs triggers an automatic CPU retry.

## Audacity bridge

The `auda_audacity_*` tools require **Audacity 3.x** with `mod-script-pipe`
enabled. See [`scripts/enable_audacity_pipe.md`](scripts/enable_audacity_pipe.md).

Audacity 4.0 removed `mod-script-pipe`; the bridge is 3.x-only. All other
tools work regardless of Audacity version (or with no Audacity installed).

## Skill

Install `dpf-audio-pro` (the companion skill) into your skills directory
to give the LLM curated workflows that chain these tools:
podcast cleanup, music mastering, vocal isolation, dialog restoration,
and archival restoration. See the skill's `SKILL.md`.

## CLI usage

The `auda` command gives terminal access to all DSP functions directly:

```bash
# Analyze a file
auda analyze track.wav

# Peak normalize to -1 dBFS
auda normalize track.wav -o normalized.wav --target-db -1

# LUFS normalize to Spotify target
auda normalize track.wav -o spotify.wav --method lufs --lufs-target spotify

# Trim 10s–30s
auda trim track.wav -o clip.wav --start 10 --end 30

# Fade in 2s, fade out 3s
auda fade track.wav -o faded.wav --fade-in 2 --fade-out 3

# Concatenate with 0.5s gap
auda concat intro.wav body.wav outro.wav -o full.wav --gap 0.5

# Mix two files at different gains
auda mix music.wav vocals.wav -o mixed.wav --gains 0.7,1.0

# Transcode to 48kHz mono MP3
auda convert track.wav output.mp3 --sample-rate 48000 --channels 1 --bitrate 192k

# Apply EQ
auda eq track.wav -o eq.wav --highpass 30 --low-shelf-db 2 --high-shelf-db -1

# Compress
auda compressor track.wav -o comp.wav --threshold -18 --ratio 3 --attack 15 --release 180

# Limit
auda limiter track.wav -o limited.wav --ceiling -1

# Full mastering chain
auda master track.wav -o mastered.wav --target spotify

# Stem separation (requires demucs: pip install audamcp[ml])
auda stems track.wav -o stems_dir/
auda vocals track.wav -o vocals.wav
auda karaoke track.wav -o backing.wav

# Denoise
auda denoise noisy.wav -o clean.wav --algorithm spectral --strength 0.85

# Check system
auda health

# Raw ffprobe metadata
auda probe track.wav
```

All commands output JSON by default with `{ok, tool, output, processing_seconds, ...}`.

## Project layout

```
audamcp/
├── pyproject.toml          # uv-managed; deps split into core / ml / ml-dfn
├── audamcp/
│   ├── server.py           # FastMCP app + @mcp.tool registrations
│   ├── cli.py              # `auda` CLI (click) — direct terminal access
│   ├── audio_io.py         # load / save / convert / probe
│   ├── loudness.py         # BS.1770 + streaming target table
│   ├── analyze.py          # BPM, spectral, dynamic range
│   ├── master.py           # pedalboard mastering chain + dynamics
│   ├── dsp_util.py         # convert / trim / fade / concat / mix / speed
│   ├── desilence.py        # silence detect / trim / remove / split
│   ├── repair.py           # declick / declip / decrackle
│   ├── denoise.py          # noisereduce + DeepFilterNet
│   ├── stems.py            # Demucs (htdemucs / _ft / _6s)
│   ├── dereverb.py         # bs_roformer dereverb / deecho
│   ├── audacity_bridge.py  # mod-script-pipe named-pipe client
│   ├── config.py           # device detection + paths
│   └── utils.py            # timing + JSON envelopes
├── scripts/                # install / register / smoke_test
└── configs/                # ready-to-paste per-client snippets
```

## License

MIT.
