Shotstead

Don't prompt the shot. Stage it.

Shotstead is a persistent virtual stage for agentic filmmaking. Instead of describing every shot from scratch, creators work with one structured 3D stage containing performers, props, motion and camera state, rehearse it, capture a Preview Take, move only the camera, and shoot again from the same world.

Shotstead is the public competition build for Agentic Cinema: The Blockbuster Hackathon.

Why Shotstead

Generative video workflows are good at making individual clips, but multi-shot filmmaking needs something more durable than a sequence of prompts. A room, performer, prop placement, blocking and camera setup should remain editable and traceable between shots.

Shotstead makes the stage the primary work object:

persistent Stage State
→ 2D / 3D / Viewfinder projections
→ rehearsal
→ browser Preview Take
→ immutable Stage version
→ camera-only child version
→ second Take from the same stage
→ execution provenance

The result is a small but concrete virtual-production workflow: same stage, new camera, proven lineage.

What is working now

The current competition build has validated runtime evidence for:

• one persistent 3D room with performer, prop and camera state;
• synchronized 2D top-down, 3D Director View and camera Viewfinder;
• replayable rehearsal;
• real browser MediaRecorder Preview Take capture;
• immutable Stage versions with parent lineage and stale-write protection;
• Take A from committed Stage v1;
• camera-only Stage v2 and Take B without rebuilding the world;
• real Gemini on Vertex AI operating the Stage through bounded Google ADK tools;
• explicit human approval outside the model tool surface before Stage mutation;
• append-only execution evidence;
• deterministic projection of execution evidence to ClickHouse Cloud;
• real Gemini query of production history through the official read-only mcp-clickhouse runtime path.

The ClickHouse integration is intentionally a production ledger, not a second source of Stage truth.

Judge-visible product story

A short demo makes this sequence obvious:

1. Open one prepared stage.
2. Rehearse and capture a Preview Take.
3. Move only the camera and commit the child Stage version.
4. Capture another angle without reconstructing the room or performance.
5. Ask which committed Stage version produced the latest successful Preview Take.
6. Gemini answers from the real ClickHouse production ledger through official MCP.

The technical integrations support the filmmaking story; they are not the story themselves.

Architecture

apps/web/                     public competition experience
packages/contracts/           Stage / Take / adapter contracts
packages/core-candidate/      immutable Stage repository and lineage logic
packages/stage-runtime-three/ Three.js rehearsal + camera Runtime
packages/stage-tools/         bounded Stage Coordinator tool runtime
adapters/google/              Gemini / Google ADK integration
adapters/partner/             ClickHouse production-ledger integration
tests/                        deterministic regression tests
e2e/                          Chromium and live integration gates

Authority stays explicit:

Stage Repository   = current Stage truth
Browser Runtime    = execution projection
ClickHouse         = append-only production history
mcp-clickhouse     = read-only agent query surface
Gemini             = tool-using coordinator over those boundaries

See docs/architecture.md for the full architecture specification.

Quick start

Requirements:

• Node.js >=22.12.0
• pnpm 11.22.0

pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm build
pnpm test:e2e

Run the web app locally:

pnpm --dir apps/web dev

The main experience is available at /. The browser execution harness used by the live Agent gate is available at /?runtime=agent.

Credential-free tests

The standard test suite is entirely credential-free and requires no Google Cloud or ClickHouse account.

To confirm no live gates accidentally execute, clear the opt-in flags first:

unset SHOTSTEAD_LIVE_GEMINI
unset SHOTSTEAD_LIVE_CLICKHOUSE
unset SHOTSTEAD_HUMAN_APPROVAL

pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm build
pnpm test:e2e

All live Vertex AI and ClickHouse tests will be skipped. See docs/validation.md for the full validation guide.

Opt-in live Google and ClickHouse tests

The live Partner gate is opt-in and requires your own Google Cloud and ClickHouse credentials.

Use .env.example as the variable reference. Do not commit secrets.

SHOTSTEAD_LIVE_GEMINI=1 \
SHOTSTEAD_LIVE_CLICKHOUSE=1 \
pnpm test:live:clickhouse

The complete live gate proves:

Gemini / Vertex AI
→ committed Stage
→ Chromium rehearsal
→ real Preview Take
→ Shotstead execution evidence
→ ClickHouse Cloud
→ official mcp-clickhouse==0.4.1
→ Gemini production-history answer

See docs/validation.md for a description of each validation level.

Cloud Run deployment

The repository includes a small production container for the static web experience. See docs/deployment-cloud-run.md.

The deployment intentionally serves the browser experience only. Google and ClickHouse credentials stay in local live-test environments or server-side secrets; they are never baked into the static bundle.

The final hosted URL will be added to the Devpost submission after final public deployment.

Scope

Shotstead is deliberately not a full DCC, world foundation model, editing suite or complete AI filmmaking platform. This competition build validates a narrower idea: a persistent, versioned virtual stage can become the stable object around which agentic filmmaking happens.

Veo cinematic execution is optional and is not required for the proven core workflow.

Rights and attribution

The competition demo uses a minimal procedural/generic stage and does not require proprietary narrative IP. Third-party software remains under its respective upstream licences; see ATTRIBUTIONS.md.

Never commit credentials, .env files, account screenshots, personal data, or unlicensed media/assets.

License

Licensed under the Apache License 2.0. See LICENSE and NOTICE.