From 3fbef65b20fc3c766954fbc8297a2ef638257090 Mon Sep 17 00:00:00 2001 From: "russell@unturf.com" Date: Thu, 19 Feb 2026 17:56:23 -0500 Subject: [PATCH] docs: add karaoke pipeline architecture to CLAUDE.md Disk-backed vocal isolation pipeline, 3.698GB upstream limit, concurrency, retry, and caller documentation. --- CLAUDE.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 1a02254..a29a577 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,6 +20,18 @@ Files are NEVER streamed through uwsgi. The server only generates presigned URLs - **Uploads**: presigned `post` → client uploads directly to Spaces - **Thumbnails**: public CDN URLs with `?ts=` cache busting +### Karaoke Pipeline (lib/karaoke.py) + +Disk-backed vocal isolation pipeline. Downloads media from S3, builds a JSON +request on disk with streaming base64 encoding, POSTs to unsandbox API, streams +response to disk, decodes artifacts one at a time and uploads to S3. + +- **Concurrency**: `ThreadPoolExecutor` sized to account's unsandbox concurrency limit +- **Memory**: ~64KB per worker on the request side (disk-backed, not in-memory) +- **Upstream limit**: 3.698GB / 3,698,742,051 bytes per file (unsandbox `@max_upload_bytes`) +- **Retries**: 3 attempts with exponential backoff (5s, 10s) +- **Callers**: `views/product.py`, `views/shop.py` (backfill), `scripts/backfill_karaoke.py` + ## Project Setup This project uses a Makefile for most development operations. Use `make` commands instead of running tools directly.