Find the songs in your mix

# Decosa Find the songs in your mix: use the hosted API

You are wiring Decosa's mix cue sheet into this project. It takes a long recording (a DJ mix, a radio show), an
optional tracklist (titles, with or without times) and optional track files (the songs that were played), and returns
every song's start, a timestamped tracklist, a chaptered .m4a (one MP4 chapter per song) and a signed cue sheet that
names the audio's SHA-256. It runs on CPU with no model call and no outside service. It never names a song it was given
no title or file for. Use only what is listed below. If you need something else, stop and ask me.

- Base URL: `https://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz`.
- Retention on the hosted API: the mix and track files are deleted when the run ends; the chaptered .m4a is kept for
  one hour (or until `DELETE /cue/runs/{id}`); the song list and cue sheet (no audio) for 24 hours, for the token or key
  that made the run.

## Auth: API key (or a demo session)
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page. Keep it in an environment variable,
   `DECOSA_API_KEY`, never in code. Send `Authorization: Bearer $DECOSA_API_KEY`.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "mix-cue-sheet"}` returns `{"token", "expires_at", "budget"}`.
   a limited number of sessions per network per hour (the current limits are in `demo_sessions` of GET /healthz). Over a limit: HTTP 429 with `Retry-After`.
3. One run at a time per demo token (409 otherwise); 429 with `Retry-After` when the service is busy.

## Endpoints
- Upload each file first, in chunks (the public edge caps request bodies, so always chunk):
  `POST /cue/uploads {"kind": "mix"|"ref", "bytes": <size>, "filename": "..."}` -> 201 `{upload_id, chunk_bytes, bytes, kind, expires_s}`,
  then `PUT /cue/uploads/{upload_id}?offset=<bytes sent so far>` with the raw bytes (`Content-Type: application/octet-stream`,
  at most 16 MB per chunk) -> `{received, bytes, complete}`. A 409 says the offset the server expects; resume from it.
  Limits: a mix up to 150 MB and 2 hours; up to 30 track files of up to 40 MB and 15 minutes each.
- `POST /cue/mark` `{"audio": "<mix upload_id>", "tracklist"?: "...", "refs"?: [{"upload": "<ref upload_id>", "title": "Artist - Title"}], "title"?: "...", "stream"?: true}`,
  or `{"sample": "demo-1"}` for a demo mix. Tracklist: one song per line in play order, `12:30 Artist - Title` or just
  `Artist - Title`; up to 400 lines and 20,000 characters.
  - With `"stream": true` (or `Accept: text/event-stream`) it streams `run` `{run_id, poll}`, `stage`
    `{stage: features|refs|resolve|chapters, progress: 0..1}`, then `done` (the run, below) or `error`, then `budget`.
    With `"stream": false`: 202 `{run_id, poll}`; poll `GET /cue/runs/{run_id}` until `status` is `done` or `error`.
  - The run: `{id, status, markers: [{start, title, source, confidence}], songs, method, detector, duration_s, audio_sha256, timing, tracklist, downloads: {tracklist, m4a, record}, audio_expires_s, record_signed, inputs_deleted}`.
    `source`: `tracklist` (your time, used as written), `own_refs` (found from your track file), `guess` or `detector`
    (placed from the audio). `confidence`: `identified` or `estimated`; show estimated starts as "check by ear".
- `GET /cue/runs/{id}/tracklist.txt` (`0:00 Title` per line), `GET /cue/runs/{id}/chapters.m4a` (410 once deleted),
  `GET /cue/runs/{id}/record` (the signed cue sheet), `DELETE /cue/runs/{id}` (deletes the chaptered audio now).
- `POST /record/verify` (no token) `{"record": {...}}` -> `{ok, summary, bad}`.
- `GET /cue/info`, `GET /cue/samples`, `GET /cue/samples/{id}/audio`, `GET /attest/signing-key` (no token).
- Errors: 400 (the message says what is wrong, including audio that cannot be decoded or is too long), 402 budget,
  404 unknown upload or run, 409 wrong offset or a run already going, 413 too large, 429 busy.

## Example: mark a mix and save the files (Python, `pip install httpx`)
```python
import httpx, os, pathlib, time
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}

def upload(path, kind):
    data = pathlib.Path(path).read_bytes()
    u = httpx.post(f"{API}/cue/uploads", headers=H, json={"kind": kind, "bytes": len(data), "filename": pathlib.Path(path).name}).json()
    step, off = min(u["chunk_bytes"], 16 * 1024 * 1024), 0
    while off < len(data):
        r = httpx.put(f"{API}/cue/uploads/{u['upload_id']}", params={"offset": off}, headers={**H, "Content-Type": "application/octet-stream"},
                      content=data[off:off + step], timeout=120)
        r.raise_for_status()
        off = r.json()["received"]
    return u["upload_id"]

body = {"audio": upload("mix.mp3", "mix"), "tracklist": pathlib.Path("tracklist.txt").read_text(),
        "refs": [{"upload": upload(p, "ref"), "title": pathlib.Path(p).stem} for p in ["track1.mp3", "track2.flac"]],
        "stream": False}
run = httpx.post(f"{API}/cue/mark", headers=H, json=body, timeout=60).json()
while (v := httpx.get(f"{API}{run['poll']}", headers=H).json())["status"] not in ("done", "error"):
    time.sleep(2)
for m in v["markers"]:
    print(m["start"], m["title"], m["source"], m["confidence"])
for key, name in [("tracklist", "tracklist.txt"), ("m4a", "mix-chapters.m4a"), ("record", "cue-sheet.json")]:
    if v["downloads"].get(key):
        pathlib.Path(name).write_bytes(httpx.get(f"{API}{v['downloads'][key]}", headers=H, timeout=300).content)
```

## Honest limits
- It names only songs it is given a title or a file for; the hosted API does no catalogue lookup.
- Titles without a time or a file are placed from the audio alone and marked `estimated`; on long beat-matched blends
  they can be off. Track files place their songs from the audio itself.
- The learned transition detector is off on the hosted API (its training audio has no dataset licence).

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

# Decosa Find the songs in your mix: run it yourself (containers)

You are setting up Decosa's mix cue sheet on this machine, so mixes, unreleased edits and track files never leave it. It
finds every song's start in a long recording from an optional tracklist, optional track files and the audio itself,
writes a chaptered .m4a (one MP4 chapter per song) and a timestamped tracklist, and signs a cue sheet with this box's
own key. It runs on CPU: no GPU and no model server. Nothing is sent to Decosa's hosted API.

Status: the container images (${DECOSA_REGISTRY}/decosa-*) and the compose file are on request while self-host is in early access (not on a public registry yet): ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry as DECOSA_REGISTRY, the compose file URL as DECOSA_COMPOSE_URL, and pull access. If a pull fails with
"not found", "denied" or "unauthorized", stop and tell me. Do not substitute other images.

Ask me before any command that needs sudo, and show me the command first.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
   nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
   "test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
   https://decosa.ai/samples/mix-cue-sheet.zip (1 KB, 12 checks, synthetic or openly licensed: see `licence` in expected.json),
   show me what is in it, and run the rehearsal against the local API:
   `docker compose exec api python scripts/rehearse.py mix-cue-sheet` (the api image carries the same bundle under /app/rehearsal/mix-cue-sheet/;
   with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
   `python scripts/rehearse.py mix-cue-sheet --bundle mix-cue-sheet.zip --base-url http://127.0.0.1:<PORT>`.
   It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "the run finishes", "eight songs are found", "the first song is Mirrorball Sunday at 0:00"). Show me
   the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
   to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
   machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## Steps
1. Docker: if `docker compose version` fails, install Docker Engine and the compose plugin using Docker's official
   instructions for this distribution (docs.docker.com/engine/install). No NVIDIA toolkit is needed.
2. Fetch the compose file:
   `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
   Read it. Keep only the `api` service (drop `llm` and every GPU service: this tool calls no model). Keep its named
   `/data` volume and bind every port to 127.0.0.1. Leave `DECOSA_CUE_DETECTOR` unset (off).
3. Pull and start: `docker compose pull api && docker compose up -d api`.
4. Check: `curl -fsS http://127.0.0.1:<PORT>/cue/info` shows `detector.mode: "off"` and the limits;
   `GET /attest/signing-key` shows this box's public key. Show me the key: it is what others pin to verify my cue sheets.
5. Smoke test: get a token with `POST /demo/session {"vertical":"mix-cue-sheet"}` and run
   `POST /cue/mark {"sample": "demo-1", "stream": false}`, then poll `GET /cue/runs/{run_id}` until `status` is `done`.
   Expect one marker per line of the sample's tracklist (`GET /cue/samples`), in order, the first at 0:00, and
   `record_signed: true`. `GET /cue/runs/{id}/chapters.m4a` must download and show one chapter per song
   (`ffprobe -show_chapters`). Then `POST /record/verify` with the record from `GET /cue/runs/{id}/record`: `ok` must be
   true; change one song's `start_ms` in it and verify again: it must fail.
6. Your own mix: upload in chunks (`POST /cue/uploads {kind: "mix", bytes, filename}`, then
   `PUT /cue/uploads/{id}?offset=N` with at most 16 MB per chunk), then `POST /cue/mark {"audio": "<upload_id>", "tracklist": "..."}`.
   Add your track files as `kind: "ref"` uploads and `"refs": [{"upload", "title"}]` for exact starts.
7. Report back: the public key and key id, the song list and how long the run took.

## Options (off by default)
- Learned transition detector: `DECOSA_CUE_DETECTOR=onnx` and `DECOSA_CUE_DETECTOR_PATH=/data/cue/detector.onnx` with a
  weights file you are comfortable using. The v1 weights were trained on the DJ Mix Dataset (YouTube-sourced, no dataset
  licence), which is why the hosted tool keeps it off; a licence-clean retrain is planned.
- Song lookup for untitled songs: `DECOSA_MIXCUE_SELFHOST=1` and your own `DECOSA_CUE_AUDD_TOKEN`. This sends a
  compressed copy of the mix to AudD (audd.io), a paid third-party service under its own terms. Ask me before turning it on.

Off. This tool uses no GPU, so there is nothing to offer the network from this box.