# Architecture: clip-storyboard-director

## Core Principles

1. **Temporal Discretization:**
   Videos are generated in fixed or variable time intervals (e.g., 5s, 10s, 15s). Each step is represented in `project.yaml` with explicit start and end times, camera movements, perspectives, and active prompt versions.

2. **4D Persistence Buffer:**
   To combat generative drift across shots:
   - **Characters:** Physical appearance, clothing, key visual identifiers.
   - **Locations / Backdrops:** Environmental features, lighting conditions, architectural style.
   - **Objects:** Specific interacting entities (e.g. twin suns, spacecraft).
   - **Props:** Portable items (e.g. handheld objects, stardust particles).

3. **Clue-Frame Chaining:**
   - When a take for Shot $N$ is imported, FFmpeg extracts the exact last frame:
     `ffmpeg -sseof -0.1 -i video.mp4 -update 1 -q:v 1 clue_frame.png`
   - In Shot $N+1$, this frame is used as an image-to-video / continuity seed.

4. **Edge CDP Automation & Cowork Protocol:**
   - Chrome DevTools Protocol (CDP) connects to Microsoft Edge on port 9222.
   - The Cockpit runs a local WebSocket connection to inspect DOM elements, select video engines (Veo, Runway, Kling), inject clean visual prompts without accidental language mixing, and trigger generation.
   - The Cowork Protocol provides a lightweight JSON-RPC interface (`/api/cowork/focus`, `/api/cowork/receipts`) so AI agents and human directors can collaborate seamlessly.

5. **Dynamic Audio Staging & Mastering:**
   - Track 1: In-Video environmental soundscape (generated by Veo).
   - Track 2: Background music bed or drone.
   - Track 3: MIDI / melody.
   - Track 4: Sound effects (SFX).
   - Voice: Text-to-speech synthesized via Microsoft Edge Neural TTS (`edge-tts`).
   - Dynamic Ducking: In-video audio is automatically attenuated (-9 dB) during voiceover playback to guarantee dialogue clarity.