Make a music video starring you

# Assemble the Decosa "music video starring you" on this machine

You are setting up a music-video maker that puts the artist in their own video: the artist records a 15-second consent
clip reading a sentence that ends in three fresh words; the tool checks the words, one live face and an adult, keeps the
consent in a ledger, finds the beats, bars and sections of their track, plans 8 to 12 shots per section, and cuts them on
the beat into 16:9, 9:16 and a Spotify Canvas loop, with an AI video label on every frame, an end card crediting the
music and a C2PA credential in every file. Shots are MiniMax H3 moving clips when an H3 worker is attached, otherwise
drawn stills (FLUX.2 klein) with a camera move. 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-video-starring-you.zip (1 KB, 10 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-video-starring-you` (the api image carries the same bundle under /app/rehearsal/music-video-starring-you/;
   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-video-starring-you --bundle music-video-starring-you.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: "moving H3 shots are refused while no render GPU is attached", "the video finishes", "the shot list has 10 shots"). 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
- Apache-2.0: Qwen3.8-27B (adult check, shot list, frame checks), Qwen3-ASR-1.7B (consent read-back), FLUX.2 klein 4B
  with its Qwen3-4B text encoder and VAE (storyboard stills); MIT: the Ultra-Light face detector (bundled in the api
  image); librosa (ISC) for the beat grid.
- MiniMax H3 is NOT open for every use: the public community licence excludes the US, EU, UK and Korea. Attach an H3
  worker only if you hold a licence that covers you; keep `LICENSE-MiniMax-H3.txt` next to the weights and "MiniMax H3"
  in the credits (the api does this). Without it, the tool makes storyboards.
- Faces come only from a live consent clip: there is no photo upload anywhere, adults only, and a minor can't be enrolled
  for the music-video purpose. Don't add a photo path.
- Only use tracks you have the rights to put in a video; the end card credits the music to the artist you name.
- Bind every port to 127.0.0.1. Logs carry ids, counts and hashes.

## 1. Check the machine
1. `nvidia-smi`: the storyboard needs about 6 GB above your baseline for FLUX.2 klein (fp8 transformer, NVFP4 text
   encoder); the text model about 20 GB more (Qwen3.8-27B NVFP4 needs a Blackwell card; use a server you already run
   otherwise). H3 moving shots need a 96 GB card with about 60 GB free: we measured a peak of 49.6-52 GiB with the fp8
   transformer after the text encoder had run and been unloaded.
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 check `docker run --rm --gpus all ubuntu nvidia-smi`.
3. Disk: Qwen3.8 NVFP4 is about 20 GB; FLUX.2 klein, its encoder and VAE and the ASR model add a few more; H3 adds
   about 200 GB (our tree of transformers, text encoder, VAEs and the Turbo v4 adapter is 197 GB).

## 2. Images, weights and services
- `${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 the newest release that contains
  `decosa_api/studio_core/starring/` (`main` until one does), and `docker build -f docker/api/Dockerfile -t decosa-api:starring .`.
- ComfyUI for the storyboard: build `decosa-comfyui:local` as in the Decosa **characters** assemble prompt (ComfyUI at
  commit `30bdda1ef13a3a34fce2cd2fec633f15d832122a`) and put `flux-2-klein-4b.safetensors`
  (`black-forest-labs/FLUX.2-klein-4B`, revision `e7b7dc27f91deacad38e78976d1f2b499d76a294`),
  `qwen_3_4b_fp4_klein.safetensors` and `flux2-klein-vae.safetensors` in its `diffusion_models`, `text_encoders` and
  `vae` folders.
- The speech service: `services/lang/server.py` from the checkout in its own Python 3.12 venv (we run torch 2.8.0+cu128,
  `qwen-asr` 0.0.6, fastapi, uvicorn, soundfile, librosa 1.0.0) with `Qwen/Qwen3-ASR-1.7B` (revision
  `7278e1e70fe206f11671096ffdd38061171dd6e5`) in `LANG_MODELS/Qwen3-ASR-1.7B/`; run it with `LANG_PORT=8492`.
- The beat analyzer: `docker build -f services/mvideo/Dockerfile -t decosa-mvideo-analyze:local .` (CPU).
- Optional, H3: on the licensed box run `services/studio_core/h3/setup_box.sh`, then
  `H3_FAMILY=turbo-v4 H3_MODE=ref H3_FP8=rowwise H3_TE=swap H3_WORKER_TOKEN=<a long random string> python
  services/studio_core/h3/worker.py --port 8740` (127.0.0.1 only; reach another box over an SSH tunnel, never an open
  port). We measured shots with the same fp8 transformer; a warm worker with `H3_TE=swap` on a 96 GB card is untested.

## 3. docker-compose.yml
Write this in `~/decosa/starring/`. `network_mode: host` lets the api reach ComfyUI, the speech service, the analyzer,
your model server and the H3 worker on 127.0.0.1.

```yaml
services:
  analyze:
    image: decosa-mvideo-analyze:local
    network_mode: host
    environment: { MVIDEO_ANALYZE_HOST: 127.0.0.1, MVIDEO_ANALYZE_PORT: "8488", MVIDEO_ANALYZE_THREADS: "8" }
    healthcheck: { test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8488/health', timeout=4)"], interval: 30s, retries: 20, start_period: 600s }
  api:
    image: decosa-api:starring
    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_LANG_SPEECH_URL: http://127.0.0.1:8492
      DECOSA_MVIDEO_ANALYZE_URL: http://127.0.0.1:8488
      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_GPU_USD_PER_H: "1.32"              # what your GPU hour costs you, for the estimates
      DECOSA_PROVENANCE_DIR: /provenance
      # H3 (only with a licence that covers you): uncomment these three
      # DECOSA_STUDIO_H3_FAST: "1"
      # DECOSA_STUDIO_H3_URL: http://127.0.0.1:8740
      # DECOSA_STUDIO_H3_TOKEN: <the worker's token>
    volumes: ["decosa-data:/data", "decosa-work:/work", "decosa-provenance:/provenance"]
    depends_on: { analyze: { condition: service_healthy } }
    healthcheck: { test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8445/studio/starring/info', timeout=4)"], interval: 30s, retries: 10 }
volumes:
  decosa-data:
  decosa-work:
  decosa-provenance:
```

Use named volumes (the api runs as uid 10001). `docker compose up -d` and wait for both health checks. Create the C2PA
signing material once, then restart: `docker compose exec api python scripts/provenance_devcert.py && docker compose
restart api` (a development CA: valid signature, untrusted issuer in public validators). Back up the box's Ed25519 key:
`docker compose cp api:/data/attest ./attest-backup`. Keep the H3 token out of logs and never print it.

## 4. Smoke test (sample performers, sample song)
```bash
B=http://127.0.0.1:8445
T=$(curl -s -XPOST $B/demo/session -H 'content-type: application/json' -d '{"vertical":"studio"}' | jq -r .token); A="authorization: Bearer $T"
P=$(curl -s -XPOST $B/studio/projects -H "$A" -H 'content-type: application/json' -d '{"name":"[TEST] starring"}')
PID=$(echo "$P" | jq -r .project.id); K=$(echo "$P" | jq -r .project_key)
PERF=$(curl -s -XPOST "$B/studio/projects/$PID/performers/sample?key=$K" -H "$A" -H 'content-type: application/json' -d '{"which":"artist"}' | jq -r '.performers[0].id')
TR=$(curl -s -XPOST "$B/studio/projects/$PID/tracks?key=$K" -H "$A" -H 'content-type: application/json' -d '{"sample":"paper-lanterns"}' | jq -r .id)
V=$(curl -s -XPOST "$B/studio/projects/$PID/videos?key=$K" -H "$A" -H 'content-type: application/json' \
  -d "{\"mode\":\"artist\",\"performers\":[\"$PERF\"],\"track_id\":\"$TR\",\"look\":\"cinematic\",\"aspect\":\"16:9\",\"direction\":\"warm dusk by a harbour\"}" | jq -r .id)
until curl -s "$B/studio/videos/$V?key=$K" -H "$A" | jq -e '.status=="done" or .status=="failed"' >/dev/null; do sleep 5; done
curl -s "$B/studio/videos/$V?key=$K" -H "$A" | jq '{status, shots: (.shots|length), sync: {found: .sync.found, planned: .sync.planned, ms: .sync.median_abs_ms}, safety: .safety[0], exports: (.exports|map_values(.credential))}'
```
Expect `done` with 10 shots, every planned cut found within about 17 ms of the beat, nothing flagged, and `c2pa` on the
16:9, 9:16 and canvas exports, in about 90 s on our shared card. With H3 attached, `POST /studio/videos/$V/move?key=$K`
with `{"video":"h3-sketch"}` makes the same shots move (about a minute a shot). Report the times you measure.

## 5. Your own clip and track
In the app: get a sentence (`/performers/challenge`), record the clip within its time limit (the three words are fresh
each time, so a stored clip fails), upload your track (up to 20 MB) with its title and artist, write a line of
direction, then edit or re-roll any shot (`POST /studio/videos/{vid}/shots`). The performer's revocation link deletes
their references and videos.

## 6. 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`, the Changes
entry "Studio: family interview film, music video starring you, our story film" (29 Sep 2026).