Repository Public
1# CLIP — Autonomous AI Cinema23**https://clip.spboucher.ai** — a small autonomous studio that conceives, writes, storyboards, shoots, narrates,4edits, reviews and (after a human approval) publishes original short vertical films, with a public cinema to5watch them and a private studio to run the production.67- Public cinema: vertical feed, editorial home, film pages with provenance and sources, series, explore, search,8 English and French.9- Private studio (`/studio`): Concept Lab, script and research, storyboard, prompt workbench, timeline, preview,10 automated QA, approval and release, programming, budgets, kill switch, audit log.11- Production engine: an eight-stage pipeline on a durable queue, real xAI integrations (Grok LLM, Grok Imagine12 image and video, text to speech), FFmpeg assembly, idempotent and budgeted provider calls.1314What is live and what is not is stated plainly in [`PROGRESS.md`](PROGRESS.md).1516## Architecture in one picture1718```19visitor ─▶ Caddy (TLS) ─▶ clip-web (Next.js 16: cinema, studio, API, media with range)20 │ enqueue ▲ read21 ▼ │22 Redis (BullMQ) ──▶ clip-worker ─┼─▶ PostgreSQL 1723 │ FFmpeg │24 ▼ │25 content-addressed asset store (disk)26 │27 ▼ HTTPS, server side only28 xAI: grok-4.7 · Grok Imagine · TTS (+ Claude Code as director)29```3031```32Idea → Pitches → Research → Script → Storyboard → Keyframes → Voice → Video → Assembly → QA → Approval → Release33```3435Details: [`docs/architecture.md`](docs/architecture.md). Provider facts verified against the live API:36[`docs/provider-capabilities.md`](docs/provider-capabilities.md). Money: [`docs/cost-model.md`](docs/cost-model.md).37Threat model: [`docs/security.md`](docs/security.md). Operations: [`docs/deployment.md`](docs/deployment.md).3839## Repository map4041| Path | What it holds |42|---|---|43| `src/app/(public)/[locale]/` | Public cinema (English at `/`, French at `/fr`) |44| `src/app/studio/` | Studio pages and server actions |45| `src/app/api/` | Public API, studio API, OpenAPI document (`/api/openapi.json`) |46| `src/app/media/[file]/` | Media delivery with HTTP range; public only for published films |47| `src/providers/` | Provider interfaces, xAI adapters, capability matrix, price table, HTTP layer (retries, breaker) |48| `src/pipeline/` | Stages, prompts (agent roles), provider-job wrapper (idempotency, budget, resume), FFmpeg, captions, QA, publication, orchestrator |49| `src/worker/` | Queue worker, programming scheduler, housekeeping, nightly backup |50| `src/lib/` | Contracts (Zod), auth, budget, storage, queue, search, i18n, taxonomy |51| `db/migrations/` | SQL schema |52| `scripts/` | Migrate, seed, owner bootstrap, operator CLIs, backup/restore, CI gate, secrets scan |53| `tests/`, `e2e/` | Unit tests (Vitest) and end-to-end tests (Playwright) |5455## Local setup5657Requirements: Node 24+, pnpm, PostgreSQL 17, Redis, FFmpeg.5859```bash60pnpm install61createdb clip_dev62cp .env.example .env # fill DATABASE_URL, ASSET_ROOT, APP_SECRET (openssl rand -hex 32), XAI_API_KEY, OWNER_EMAIL63pnpm migrate && pnpm seed64pnpm bootstrap:owner # prints a one-time password, to be replaced at first sign-in65pnpm build && pnpm start # web on http://localhost:864066pnpm worker # in a second terminal67```6869Sign in at `/studio`, replace the one-time password, turn on two-factor authentication in **Account**, then open70the **Concept Lab**.7172## Operator commands7374```bash75pnpm tsx scripts/provider-probe.ts # live models and prices vs the compiled matrix (no paid call)76pnpm tsx scripts/produce.ts --theme "…" --series one-minute-ideas --lang fr --shots 4 --quality draft --until qa77pnpm tsx scripts/produce.ts --project <id> --publish --approver you@example.com78pnpm tsx scripts/kill-switch.ts on|off|status79scripts/backup.sh # database dump + asset copy (+ off-node rsync)80scripts/restore.sh ~/backups/clip-spboucher-ai # restore drill into a scratch database81scripts/ci.sh # typecheck, lint, unit tests, build, secrets scan (+ e2e with PW_BASE_URL)82```8384`produce.ts` runs the same stages inline, under the same budgets and idempotency rules as the worker. Publishing85from the CLI still requires naming a studio user as approver: release is a human decision.8687## Claude Code director8889Studio → **Director**: type one idea and Claude Code directs the whole film. The worker runs `claude -p` on the node with90three tools: `./clip` (plan, keyframe, preview, render, voice, factcheck, assemble, qa, note), Read and Write. It looks at91every image it produces, tests motion with cheap previews before the 1080p renders, and stops at QA: release stays a human92decision. Requirements on the node: `/opt/homebrew/bin/claude` and an Anthropic API key in `~/.config/clip/anthropic-api-key`93(mode 600). CLI equivalent: `pnpm tsx scripts/director-start.ts --idea "…" --lang fr --shots 5 --budget 15`.9495## How spending is controlled96971. Every paid call goes through `runProviderJob()`: budget gate → atomic claim → provider → ledger.982. The gate enforces the kill switch and four ceilings (shot, film, day, month) on money spent **plus** money99 committed to running jobs. An unknown price blocks autonomous execution.1003. The same input is paid for once: the idempotency key is a hash of (kind, model, input). Re-running a stage,101 double-clicking, or a worker restart reuses the stored result; a crashed video job resumes from its provider102 `request_id`.1034. Regenerating a shot is explicit, counted, and capped; past the cap an owner must approve.1045. Nothing loops: the scheduler has a daily quota, retries are bounded, and a failed QA never retries itself.105106## Tests107108```bash109pnpm test # unit: contracts, budget gate, pricing, captions, idempotency, SSRF allow-list…110PW_BASE_URL=https://clip.spboucher.ai pnpm test:e2e # public cinema, API contract, studio access control111```112113## Licence and content114115Code: private. Films: AI-generated, © CLIP / Simon-Pierre Boucher. Voices are provider presets (no cloning); there116is no third-party music; no real person is depicted.117