Make a film of your story together

# Assemble the Decosa "our story film" on this machine

You are setting up a maker of 60-second films of a couple, told through three of their own memories: each partner
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 each consent in a ledger, finds the beats and sections of their song, plans an opening shot, the
three memories in order with a line of their words on screen and a closing shot of the two of them now, and cuts it on
the beat into 16:9 and 9:16, 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/our-story-film.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 our-story-film` (the api image carries the same bundle under /app/rehearsal/our-story-film/;
   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 our-story-film --bundle our-story-film.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 11 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 songs you have the rights to put in a video; the end card credits the music to the artist you name.
- Memories that describe a child are refused: Studio keeps children out of every video.
- 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:ourstory .`.
- 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/ourstory/`. `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:ourstory
    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 (two 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] our story"}')
PID=$(echo "$P" | jq -r .project.id); K=$(echo "$P" | jq -r .project_key)
PERFS=$(curl -s -XPOST "$B/studio/projects/$PID/performers/sample?key=$K" -H "$A" -H 'content-type: application/json' -d '{"which":"couple"}' | jq -c '[.performers[].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\":\"couple\",\"performers\":$PERFS,\"track_id\":\"$TR\",\"look\":\"cinematic\",\"aspect\":\"16:9\",\"memories\":[\"We met at a night market in the rain, sharing one umbrella that didn't work.\",\"Our first trip was a train to the coast; we missed the last train back and slept on the beach.\",\"We painted our first flat yellow, and most of the paint ended up on us.\"]}" | 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 11 shots (opening, three memories, now), every planned cut found within about 17 ms of the beat,
nothing flagged, and `c2pa` on every export, in about 2-2.5 minutes on our shared card. With H3 attached, `POST /studio/videos/$V/move?key=$K`
with `{"video":"h3-sketch"}` makes the same shots move (about 80 s a shot with two faces). Report the times you measure.

## 5. Your own clips and song
In the app: each partner gets a sentence (`/performers/challenge`) and records their own clip (the three words are fresh
each time, so a stored clip fails); upload your song (up to 20 MB) with its title and artist, write three memories in
your own words, then edit or re-roll any shot (`POST /studio/videos/{vid}/shots`). Either partner's revocation link
deletes their references and the film.

## 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).