Metadata-Version: 2.5
Name: drumsplit-mcp
Version: 0.1.0
Summary: One-call drum separation for agents, with resumable downloads
Project-URL: Homepage, https://drumsplit.io
Project-URL: Documentation, https://drumsplit.io/developers
Author: DrumSplit
Requires-Python: >=3.10
Requires-Dist: filelock<4,>=3.16
Requires-Dist: httpx<1,>=0.28
Requires-Dist: mcp<3,>=2.3
Requires-Dist: pydantic<3,>=2.11
Provides-Extra: test
Requires-Dist: pytest-asyncio<2,>=1; extra == 'test'
Requires-Dist: pytest<10,>=8; extra == 'test'
Description-Content-Type: text/markdown

# DrumSplit for agents

Upload a local audio file, separate its drums, and save the ZIP and WAV stems
with one tool call. This package provides a local MCP server, a command-line
client, and a Python client for the existing DrumSplit API.

## Install and connect

Use Python 3.10 or newer:

```sh
python -m pip install drumsplit-mcp==0.1.0
```

Sign in at [DrumSplit Developers](https://drumsplit.io/developers), create an API
key, and set `DRUMSPLIT_API_KEY` in your agent host's secret settings or launch
environment. The connector never creates an account or purchases credits.
API credits are separate from website credits. Each submitted split consumes
one API credit, including drum-bus-only output.

Configure your MCP host to launch `python -m drumsplit_mcp`. The Python executable
must belong to the environment where you installed this package. For hosts that
accept JSON configuration:

```json
{
  "mcpServers": {
    "drumsplit": {
      "command": "python",
      "args": ["-m", "drumsplit_mcp"]
    }
  }
}
```

Provide `DRUMSPLIT_API_KEY` to that process through the host's credential or
environment configuration. Keep credentials out of prompts and shared config.
Restart the connection after changing its environment.

Ask your agent to separate the drums from a local song and save them in a new
output folder. The tool call is:

```json
{
  "name": "separate_audio",
  "arguments": {
    "file": "/audio/song.wav",
    "output_dir": "/audio/song-stems"
  }
}
```

The server runs alongside the agent. Paths refer to files accessible to that
process. This release does not accept public audio URLs or provide a hosted MCP
endpoint for browser-only agents.

## Use the command line

With `DRUMSPLIT_API_KEY` in your environment:

```sh
drumsplit separate song.wav --output-dir ./song-stems
drumsplit resume ./song-stems
drumsplit status JOB_ID
drumsplit download JOB_ID --output-dir ./downloaded-stems
drumsplit balance
```

Commands print JSON. Exit code 0 means the command succeeded, including a job
that is still processing. Exit code 1 means an error, a failed job, or a job that was not found. CLI usage
errors exit with code 2.

`separate` supports `--output-mode full|drumbus`,
`--input-type full_mix|drum_stem`, `--algorithm auto|natural|puncher`,
`--quality standard|studio`, and `--wait-seconds`. Defaults are `full`,
`full_mix`, `auto`, `standard`, and 45 seconds. Paid-only options and duration
limits are enforced by the API. Input files must be nonempty supported audio
files no larger than 100 MiB.

## Resume an interrupted request

Keep the output folder. The connector writes `.drumsplit-request.json` before
submitting audio. The file contains request metadata and a retry key, without
your API credential. Repeating `separate` with the same file, options, account,
and output folder reuses that request. `resume` also works after the source
file is removed once the job ID has been saved.

If the upload response is lost, `resume` reads the original audio and reuses
the saved idempotency key. An unconfirmed request older than 23 hours stops
instead of risking another charge after the API's documented 24-hour retry
window. Never delete the request record to recover an uncertain submission.
Contact support with its request ID if the connector cannot reconcile it.

A timeout returns `status: processing`, the job ID, and the output folder.
Call `resume_split` or `drumsplit resume` later. Known jobs are never resubmitted.
Failed or expired jobs do not automatically start replacement splits. A not_found observation can be checked again with resume; it is not cached as a permanent failure. Results
are retained on the server for 24 hours; locally downloaded results remain in
the output folder.

Use one new output folder per song/request. The connector refuses to overwrite
unrelated files or mix different requests in the same folder. Keep the original
API key available for resumption. A different key cannot adopt its saved record. The output folder itself must not be a symbolic link.

## Tools

- `separate_audio`: submit, wait, and save the ZIP and WAV files.
- `resume_split`: continue a saved request using its output folder.
- `get_job_status`: inspect a job with the current API key.
- `download_stems`: save an existing job without submitting audio.
- `get_balance`: read the API credit balance and usage.

Downloads always use the authenticated DrumSplit API. The connector does not
follow download redirects or arbitrary URLs returned by a server. ZIP extraction
accepts flat WAV filenames, rejects traversal and symbolic links, and bounds the
download and extracted size. Completed results include the archive path and
individual WAV paths.

## Use Python

```python
import asyncio
from drumsplit_mcp import DrumSplitClient

async def main():
    async with DrumSplitClient.from_environment() as client:
        result = await client.separate_audio("song.wav", "song-stems")
        print(result)

asyncio.run(main())
```

## Verify or build from source

Run these commands from this package directory:

```sh
python -m pip install -e '.[test]' build
python -m pytest -q
python -m build
```

The tests run an offline HTTP service and real MCP/CLI clients. They verify the
connector's upload, recovery, download, and filesystem behavior. They do not
prove GPU separation quality or production billing.

`DRUMSPLIT_API_URL` defaults to `https://drumsplit.io/api/v1`. The isolated
staging hostname and HTTP loopback addresses are supported for testing. Direct
Modal URLs are rejected. Do not run mutation tests against a Pages PR preview:
those previews use production services.
