# Magic Master — Agent Playbook

Machine-readable manifest: https://magicmaster.pro/agent.json
OpenAPI (public subset): https://magicmaster.pro/openapi-public.json
Base URL: https://magicmaster.pro · Support: support@magicmaster.pro
Last updated: 2026-08-30

You are an AI agent using Magic Master to master audio on behalf of a human
principal. This file is the contract: what the service does, what it costs, what
you may do without asking, and what you must hand back to the human.

## Connect over MCP (recommended)

Magic Master speaks the Model Context Protocol at `https://magicmaster.pro/mcp`
(streamable HTTP, protocol revisions 2026-07-28 / 2025-11-25 / 2025-06-18).
Add it as a remote MCP server in your client, or POST JSON-RPC there directly.
Send your credentials with every request (`X-API-Key: mm_…` or
`Authorization: Bearer <jwt>`); the free tools work without them.

Tools: `get_service_info`, `list_presets`, `get_pricing`, `check_limits`,
`analyze_track`, `clean_ai_trace`, `master_track`, `get_job`, `create_topup_link`.
Audio goes in as a public https URL (`audio_url`); results come back as job ids —
poll `get_job`. The tools call the same public API with your credentials, so the
quotas, gates and billing below apply unchanged.

Working example with the official Python SDK. Note that
`streamable_http_client()` takes **no** `headers` argument — pass a preconfigured
HTTP client instead; sending the header any other way fails with a TypeError:

```python
import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client

http = httpx2.AsyncClient(headers={"X-API-Key": "mm_…"}, timeout=120.0)
async with http:
    async with Client(streamable_http_client("https://magicmaster.pro/mcp",
                                              http_client=http)) as c:
        result = await c.call_tool("check_limits", {})
```

**Two endpoints, pick by how your client authenticates.**

| Endpoint | Auth | Use it when |
|---|---|---|
| `https://magicmaster.pro/mcp` | none, or `X-API-Key` | you write the code, or you only need the free tools |
| `https://magicmaster.pro/mcp/oauth` | OAuth 2.1 only | your client cannot send custom headers (Claude Desktop) |

The second endpoint answers `401` with a `WWW-Authenticate` challenge pointing at
`/.well-known/oauth-protected-resource`, which is what makes a compliant client
start the OAuth flow on its own. Everything else about the two endpoints is
identical — same tools, same quotas, same billing.

OAuth details: authorization server metadata at
`/.well-known/oauth-authorization-server`; dynamic client registration at
`/oauth/register`; PKCE with `S256` is required; the only scope is `mastering`;
tokens are issued for the resource `https://magicmaster.pro/mcp` and are rejected
anywhere else. Access tokens live an hour, refresh tokens rotate on every use.

## What this service does

Automatic audio mastering: loudness (LUFS), True Peak limiting (ITU-R BS.1770-5),
multiband dynamics and EQ, restoration (de-hum, de-click, de-reverb), stem
mastering, and removal of Suno/Udio AI fingerprints.

- Input formats: `wav`, `mp3`, `flac`, `m4a`.
- Output formats: `wav`, `wav24`, `mp3`, `flac`, `opus`, `aac`
  (`bitrate` for MP3: 128/192/256/320; for OPUS: 128/192).
- Upload ceiling: ~100 MB without a paid account, 300–800 MB for paying accounts
  depending on format.

## Access and cost

Free, no key needed:
- `POST /api/v2/analyze` — LUFS, peak dBFS, duration, sample rate, stereo correlation
  (`extended=true` adds spectrum, LUFS timeline, vectorscope).
- `POST /api/v2/clean` — remove the Suno/Udio AI fingerprint; loudness and tone unchanged.
- `POST /api/v2/multipreview` — 24 s of the track rendered in 2–6 styles at once (6 per day).
- `GET /api/v2/limits` — **call this first**: token balance, free quota left and when it
  resets, upload cap, retention, and `can_master_now`. One request instead of guessing.
- `GET /api/master/status/{id}`, `GET /api/master/result/{id}`, `GET /api/presets`,
  `GET /api/tokens/packages`, `GET /api/v2/chain/default`.

Trial for agents: register once with `POST /api/agents/register`. It needs the
principal's account, and both steps are plain API calls — you do not need the web
UI for any of it:

```
POST /api/auth/register   {"email": "…", "password": "…"}   → {"access_token": "…"}
POST /api/auth/login      {"email": "…", "password": "…"}   → {"access_token": "…"}
POST /api/agents/register {"name": "your-agent", "purpose": "…"}
  with header  Authorization: Bearer <access_token>
  → {"api_key": "mm_…", "trial_tokens_granted": 3, "tokens_balance": …}
```

You get an API key plus **3 trial PRO masters** — any preset, all PRO modules, any
export format. One trial per account. A brand-new account may also carry welcome
tokens, so the starting balance can be higher; `check_limits` is the truth. After
the trial runs out: the free quota below, or tokens.

Mastering without payment:
- No account: **3 basic masters per calendar month per IP**.
- Free account: **1 master per UTC day** (3 during the first 24 h after signup).
- PRO parameters are dropped for guests and rejected with `403` for signed-in
  free users. Reference mastering is PRO.

Paid: **1 token = 1 full PRO master** — any of the 24 presets, all PRO modules
(Reference Match, Dynamic EQ, Transient Designer, Spectral Denoiser, Parallel
Compression, De-esser), every export format, batch and stem mastering. Tokens
never expire. Read live prices from `GET /api/tokens/packages` — never quote them
from memory. An API key (`X-API-Key`) is issued in the profile after any token
purchase; up to 10 active keys.

Result retention: guests keep the file in RAM ~1 hour; free accounts 1 day;
paying accounts 7 days; Studio 30 days. Sources are processed in memory.

## Choosing settings — rules, not taste

1. **Analyze first.** If input LUFS is above −8 or the crest factor is low, the
   source is already brickwalled: use style `unlimiter` and do not add loudness.
2. **Target comes from the destination**: Spotify/YouTube −14, Apple Music and
   podcasts −16, audiobook −19, club −9. True Peak ≤ −1 dBTP always.
3. **Style keys** (the key is `hiphop`, not `hip-hop`), with their default LUFS:
   `standard` −14, `edm` −9, `big_room` −8, `house_basic` −10, `hiphop` −13,
   `trap` −11, `pop` −12, `rock` −11, `metal` −10, `rnb` −13, `country` −14,
   `afrobeats` −12, `kpop` −11, `jazz` −16, `classical` −18, `podcast` −16,
   `lofi` −18, `dry_vocal` −14, `voice` −16, `audiobook` −19, `warm` −14,
   `bright` −14, `bass` −12, `unlimiter` −12.
4. **Suno/Udio track**: clean the fingerprint first, then master.
5. **Unsure between two styles?** Spend nothing: call multipreview and compare.

## Work loop

```
POST /api/v2/master            multipart: file, style, target_lufs, out_format
  headers: X-API-Key: mm_…     (optional)  Idempotency-Key: <uuid>  (recommended)
  → {"job_id": "…"}
GET  /api/master/status/{job_id}   poll every 3 s until status is "done" or "error"
GET  /api/master/result/{job_id}   → the mastered bytes
```

Typical wall-clock: 20–60 s; up to 10 minutes for a long track with restoration.
Instead of polling you may pass `webhook_url` (public https only).
`Idempotency-Key` makes a network retry safe: the same key returns the same
`job_id` and never charges a second token.

Report back to your principal, from the status payload: `after_lufs`,
`true_peak_db`, `lra`, `platform_ready`, and the download URL or saved path.

## Errors: what they mean, what to do

Every error carries a machine-readable envelope next to the human text:

```json
{"detail": "Лимит Free-тарифа исчерпан…",
 "error": {"code": "guest_quota_exhausted", "message": "Free guest quota exhausted…",
           "retry_after": 216000, "hint_url": "https://magicmaster.pro/register"}}
```

Branch on `error.code`, not on the text. Quota errors also set `Retry-After` and
`X-RateLimit-*` headers. The full code list is in `/agent.json` under `errors.codes`.

| Code | Meaning | Correct action |
|---|---|---|
| 400 | Unreadable file, wrong format, oversize | Do not retry the same bytes; report to the principal |
| 401 | Missing or invalid key | Ask the principal for a key from /profile |
| 402, 429 | Free quota exhausted | **Do not loop.** Report the number and reset time; offer a top-up |
| 403 | PRO module requested without a token | Drop the PRO parameters and master for free, or top up |
| 404 on status/result | Job expired (see retention above) | Re-run if the principal still needs it |
| 5xx | Server error | Retry once with the same `Idempotency-Key`; the token is not charged twice |

## Payment protocol — you prepare, the human confirms

You cannot complete a card payment or a Telegram Stars purchase yourself. Both
need the human. Do this instead:

1. Read `GET /api/tokens/packages` for the live packs.
2. Ask the principal which pack they want.
3. Hand over the checkout link: https://magicmaster.pro/wallet for RUB via
   YooKassa, or the Telegram bot https://t.me/magicmasterpro_user_bot command
   `/buy` for Telegram Stars — the live way to pay from outside Russia. USD/EUR
   card checkout is **not** live; do not promise it.
4. Poll the balance until credited, then continue.

Never ask for card numbers. Never store the principal's credentials.

## Terms you must respect

The principal must hold the rights to the audio. Rights to both the source and
the master stay with them; the service claims none. Do not use the service to
bypass limits or to process unlawful content. If a master fails through our
fault, the token is refunded. Full offer: https://magicmaster.pro/terms ·
Privacy: https://magicmaster.pro/privacy · Governing law: Russian Federation.

## Do not

- Do not invent prices, presets or limits — read them from the API.
- Do not retry a quota error in a loop; it will not clear before the reset time.
- Do not re-upload the same file to "improve" a master; change the preset or the
  target instead, and use multipreview to compare for free.
- Do not present the master as your own work: tell the principal it came from
  Magic Master and where to re-download it.