Make a cleared song

# Assemble Decosa rights-cleared music generation on this machine

You are setting up a music generator with a paper trail: a prompt guard that refuses (or strips) named artists, songs,
labels and voice imitation; renders on MiniMax-Music3 or ACE-Step 1.5; a CPU similarity check against a catalogue of
openly licensed recordings; and for every track a C2PA credential and a signed licence certificate. Work step by step,
show me each command before you run anything with `sudo`, and stop to ask if a check fails.

## 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/music-gen-cleared.zip (506 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 music-gen-cleared` (the api image carries the same bundle under /app/rehearsal/music-gen-cleared/;
   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 music-gen-cleared --bundle music-gen-cleared.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 named-artist brief is refused", "the refusal comes from the code rules, with no model call", "no model call is spent on the named-artist refusal"). 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.

## 0. Ground rules and licences
- Music models: **MiniMax-Music3** (MiniMax-Music3 Community License) and **ACE-Step 1.5** (MIT). Text model for the
  guard: Qwen3.8-27B (Apache-2.0). Similarity: LAION CLAP `laion/larger_clap_music` (Apache-2.0) and librosa (ISC), CPU.
- MiniMax-Music3 duties, from its LICENSE: show "MiniMax-Music3" prominently in any commercial UI that uses it (§3.1);
  get MiniMax's written authorization above USD 20M yearly revenue (§3.2); a hosted service must keep and review
  safeguards against infringing uses (§4) - this stack is that safeguard, so do not turn the guard off on a service
  others use; follow the Acceptable Use Policy (Exhibit A), including disclosing machine-generated content (item 11).
- Be honest about what it does: the similarity check covers 240 Creative Commons tracks from the Free Music Archive (or
  the references you give it). It is a triage signal, not a rights clearance. The certificate claims no copyright: the US
  Copyright Office holds that prompts alone do not make an output protectable (Part 2 report, 29 Jan 2025).
- Bind every port to 127.0.0.1. Logs carry hashes, never prompts; keep it that way.

## 1. Check the machine
1. `nvidia-smi`: MiniMax-Music3 needs about 50 GB of free VRAM (measured on an RTX PRO 6000 96 GB); ACE-Step about
   15 GB. The guard's text model needs about 20 GB more (Qwen3.8-27B NVFP4), or point it at a server you already run.
   The similarity service is CPU only (about 2 GB of RAM, 8 threads).
2. `docker --version`, `docker compose version`. If Docker or the NVIDIA container toolkit is missing, ask me, then
   install them from the official repositories and run `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
3. Disk: about 60 GB (Music3 about 25 GB, ACE-Step about 10 GB, Qwen3.8-27B NVFP4 about 20 GB, CLAP 0.8 GB).

## 2. The render side (ComfyUI for Music3, optional ACE-Step)
Follow the Decosa **studio** assemble prompt, steps 2-4, for the MiniMax-Music3 weights (Comfy-Org/MiniMax-Music-3 @
`6baad88896848433857c170ba4f05d2ea9d5f218`), ComfyUI at commit `30bdda1ef13a3a34fce2cd2fec633f15d832122a`, and, if you
want the MIT engine, ACE-Step 1.5 (`ace-step/ACE-Step-1.5` @ `75fcfbdd`, weights `ACE-Step/Ace-Step1.5` @ `19671f40`).
You need ComfyUI answering on `http://127.0.0.1:8188` (or `8189`) with the `music3.api.json` graph from
`services/studio/workflows/`. decosa-api's own worker (`scripts/studio_worker.py`) sends the jobs; no render service.

## 3. Images
- `${DECOSA_REGISTRY}/decosa-api:<tag>` (**publishing soon**). If the pull fails, build from source:
  `git clone <decosa-api source: on request at https://decosa.ai/contact?topic=self-host>` (access required), check out a release that contains
  `decosa_api/verticals/music/`, and build `docker build -f docker/api/Dockerfile -t decosa-api:local .`.
  The studio worker needs FFmpeg in the api container, and the C2PA credential needs c2pa-python (the base image does
  not install the provenance extra), so add a layer (the image runs as uid 10001; install as root):
  ```dockerfile
  # ./api-ffmpeg/Dockerfile
  FROM decosa-api:local
  USER root
  RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg && rm -rf /var/lib/apt/lists/*
  RUN pip install --no-cache-dir "c2pa-python>=0.37" "pillow>=10"
  USER decosa
  ```
  `docker build -t decosa-api:music ./api-ffmpeg`.
- The similarity service, from the same checkout: `docker build -f services/music_embed/Dockerfile -t decosa-music-embed:local .`
  (CPU torch 2.14.0, transformers 5.17.0, librosa 1.0.0; the 240-track catalogue ships inside it as vectors, no audio).

## 4. docker-compose.yml
Write this in `~/decosa/music/`. `network_mode: host` lets the api reach ComfyUI and your model server on 127.0.0.1;
with bridge networking, use service names instead and publish only 127.0.0.1 ports.

```yaml
services:
  embed:
    image: decosa-music-embed:local
    network_mode: host
    environment: { MUSIC_EMBED_HOST: 127.0.0.1, MUSIC_EMBED_PORT: "8486", MUSIC_EMBED_THREADS: "8" }
    volumes: ["hf-cache:/hf"]
    healthcheck: { test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8486/health', timeout=4)"], interval: 30s, retries: 20, start_period: 600s }
  api:
    image: decosa-api:music
    network_mode: host
    environment:
      DECOSA_HOST: 127.0.0.1
      DECOSA_PORT: "8445"
      DECOSA_DATA_DIR: /data
      DECOSA_LLM_ROUTE: direct
      DECOSA_LLM_URL: http://127.0.0.1:8114/v1        # your Qwen3.8-27B server (vLLM, served name qwen3.8-27b)
      DECOSA_LLM_MODEL: qwen3.8-27b
      DECOSA_STUDIO_WORKER: command
      DECOSA_STUDIO_WORKER_CMD: python /app/scripts/studio_worker.py
      DECOSA_STUDIO_COMFY_URL: http://127.0.0.1:8188
      DECOSA_STUDIO_WORK_DIR: /work
      DECOSA_STUDIO_ALLOW_ACESTEP: "0"                  # "1" only if ACE-Step is installed where the worker can run it
      DECOSA_MUSIC_EMBED_URL: http://127.0.0.1:8486
      DECOSA_MUSIC_ENGINES: music3                      # add ",acestep" with ACE-Step
      DECOSA_PROVENANCE_DIR: /provenance
    volumes: ["decosa-data:/data", "decosa-work:/work", "decosa-provenance:/provenance"]
    depends_on: { embed: { condition: service_healthy } }
    healthcheck: { test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8445/music/info', timeout=4)"], interval: 30s, retries: 10 }
volumes:
  decosa-data:
  decosa-work:
  decosa-provenance:
  hf-cache:
```

Use named volumes, never host folders: the api runs as uid 10001 and a host folder Docker creates is root's
(`PermissionError: '/data/keys.sqlite'`). The embed service downloads CLAP (`laion/larger_clap_music` @
`a0b4534a14f58e20944452dff00a22a06ce629d1`) on its first start; after that you can set `HF_HUB_OFFLINE: "1"`.
`docker compose up -d`, then wait for both health checks. Create the C2PA signing material once, then restart the api:
`docker compose exec api python scripts/provenance_devcert.py && docker compose restart api`; `GET /provenance/status`
must show `"c2pa": true`. It is a development CA: public C2PA validators show the signature as valid and the issuer as
untrusted. A trust-list certificate is your own purchase. On first start the api creates this box's Ed25519 key in
`decosa-data` (`/data/attest/`): back it up with `docker compose cp api:/data/attest ./attest-backup`, keep it private,
never print it. Certificates and render receipts are signed with it (an attestation by you, the operator).

## 5. Smoke test
```bash
B=http://127.0.0.1:8445
T=$(curl -s -XPOST $B/demo/session -H 'content-type: application/json' -d '{"vertical":"music-gen-cleared"}' | jq -r .token)
curl -s -XPOST $B/music/guard -H "authorization: Bearer $T" -H 'content-type: application/json' \
  -d '{"prompt":"Upbeat pop in the style of Taylor Swift"}' | jq '.guard | {decision, decided_by}'     # refused, by code
curl -s -XPOST $B/music/guard -H "authorization: Bearer $T" -H 'content-type: application/json' \
  -d '{"prompt":"Upbeat pop in the style of Taylor Swift, bright guitars","mode":"strip"}' | jq '.guard | {decision, rendered_prompt}'
R=$(curl -s -XPOST $B/music/generate -H "authorization: Bearer $T" -H 'content-type: application/json' \
  -d '{"prompt":"Warm acoustic pop for a bakery ad, ukulele and hand claps, instrumental","engine":"music3","seconds":30,"seed":5501}' | jq -r .run_id)
until curl -s $B/music/runs/$R -H "authorization: Bearer $T" | jq -e '.status=="done" or .status=="failed"' >/dev/null; do sleep 5; done
curl -s $B/music/runs/$R -H "authorization: Bearer $T" | jq '{status, credential, similarity: .similarity.verdict, certificate}'
curl -s $B/music/certificates/$R | jq '{record: .}' | curl -s -XPOST $B/record/verify -H 'content-type: application/json' -d @- | jq .ok
```
Expect: the first prompt refused by code with no model call; the second stripped to "Upbeat pop, bright guitars"; the
render `done` with `credential: "c2pa"`, a similarity verdict (`clear` for a fresh track) and a certificate that verifies
(`true`). Then take one catalogue track's audio if you have it, pitch-shift it (`ffmpeg -i in.mp3 -af rubberband=pitch=1.12246 out.mp3`)
and `POST /music/check` it as the body: expect a high score with that track named. Report the times you measure; on our
RTX PRO 6000 a 30 s Music3 track rendered in 21-74 s on a shared card and the similarity check took about 2 s on CPU.

## 6. Use your own references
The strongest use is checking against the references a client sent. For one track, `POST /music/runs/{id}/compare`
with the reference file as the body (compared in memory, not kept). For a standing set, rebuild the catalogue from your
own licensed files with `scripts/music_build_catalog.py` then `--augment`, and mount it at `/catalog` in the embed service.

## 7. Point the app at the local API
Set `NEXT_PUBLIC_DECOSA_API=http://127.0.0.1:8445` in the site's `.env.local`. Contract: `API_CONTRACT.md`, section
"Rights-cleared music generation". Any UI that plays Music3 output must show "Powered by MiniMax-Music3".