repo-cinema

repo-cinema Director Skill

Create Screen Studio-grade 60fps product demo videos straight from a codebase. Instead of ad-hoc screen recordings or aimless cursor wandering, repo-cinema executes a 5-stage deterministic pipeline: analyze -> plan -> stage -> render -> verify.

Core Architectural Principles

1. Persona-First Use Cases (analyze): Never showcase internal debug stats or raw config screens. Read entrypoints, CLI commands, routes, components, and tests to synthesize concrete Persona -> Pain Point -> User Action -> Durable Outcome scenes.
2. Causal Co-Framing (plan): Frame the union bounding box bbox(trigger ∪ outcome) rather than chasing the mouse pointer. Lock horizontal focus fx = viewport.width / 2 whenever content width spans >= 70% of the stage so axes, headers, and right columns never clip offscreen.
3. Stationary Reading Holds: Ease camera zoom in before an action, then keep (zoom, fx, fy) 100% frozen during interaction + comprehension so viewers can actually read charts and toast updates.
4. Deterministic Virtual-Clock 60fps (render): Inject the Virtual Clock Shim (Date, performance.now, requestAnimationFrame) before page load so CSS transitions, ECharts animations, C2 minimum-jerk cursor trajectories (sin^3(pi * u) arcs, <=12% velocity swell, +/-6 deg tilt, arrow <-> pointing-hand morph), and dual click ripples step deterministically frame-by-frame into FFmpeg.
5. Contact-Sheet Self-Inspection (verify): Generate a 3x3 contact-sheet.png + verify-report.json (ffprobe stream validation + zero offscreen clicks) and visually inspect every panel before shipping.

Utility CLI Commands (repo-cinema)

When installed globally or executed from the repository (npx repo-cinema ... or node dist/cli.js ...), every stage outputs structured files:

# 1. Read any repo and extract use-case scenarios (optionally run repomix first)
repo-cinema analyze --repo ./my-project --output ./out/dossier.json [--repomix]

# 2. Build causal camera/cursor storyboard JSON + visual HTML preview
repo-cinema plan --dossier ./out/dossier.json --output ./out/storyboard.json --html ./out/storyboard.html --theme aurora-indigo

# 3. Build 4-in-1 stage (web-url | plugin-or-component | cli-terminal | hybrid)
repo-cinema stage --dossier ./out/dossier.json --plan ./out/storyboard.json --output ./out/stage.html [--url http://localhost:3000]

# 4. Deterministic 60fps CDP capture + 48kHz stereo SFX (or optional TTS)
repo-cinema render --plan ./out/storyboard.json --stage ./out/stage.html --output ./out/demo.mp4 --gif ./out/demo.gif --audio sfx

# 5. Validate streams, telemetry bounds & build 3x3 visual contact sheet
repo-cinema verify --video ./out/demo.mp4 --telemetry ./out/demo.telemetry.json --contact-sheet ./out/contact-sheet.png --output ./out/verify.json

# Or run the full 5-stage pipeline in one command:
repo-cinema run --repo ./my-project --out-dir ./out --theme aurora-indigo

Director Workflow

Step 1: Analyze Repository & Audience

Run repo-cinema analyze --repo <path> --output <dossier.json>. Read the generated useCases:

• Verify the detected archetype (web-app, desktop-or-ide-plugin, cli-tool, ui-library, hybrid).
• Refine captions or add domain-authentic sample fixtures if the repo has specialized workflows (remember: zero personal data, zero dev-only counters).

Step 2: Plan Storyboard & Approve Framing

Run repo-cinema plan with --html and inspect storyboard.html (or review beats, captionWarnings, and cameraKeyframes):

• Fix any warnings from the Anti-Slop Caption Linter (no "unprecedented", "next-gen", "seamlessly", or >96-char captions).
• Ensure opening frame (t=0) and closing frame (t=durationMs) sit cleanly at zoom: 1.0 for seamless README GIF looping.

Step 3: Select Stage Adapter

• web-url: App already runs locally (http://localhost:PORT). Recorder injects Virtual Clock Shim + non-intrusive cursor/camera/caption overlay directly onto the live page.
• plugin-or-component: Desktop plugins (Obsidian, VS Code, Raycast) or UI component packages rendered inside a dark macOS Studio chrome with real core modules bundled via esbuild.
• cli-terminal: Terminal tools showcased in a glass macOS terminal with synchronized command output, KPI tiles, and outcome impact cards.
• hybrid: Multi-tab macOS Studio pairing CLI execution alongside live visual output and architecture diagrams.

Step 4: Render 60fps Master + GIF + Audio

Run repo-cinema render:

• Default --audio sfx synthesizes zero-dependency 48kHz stereo micro-SFX (stereo-panned clicks aligned with cursor x, gentle zoom air-whoosh, confirmation toast chime) — zero external API keys needed.
• Optional --audio tts --tts-provider <macos-say|edge-tts|openai|elevenlabs> mixes narration cleanly with micro-SFX.

Step 5: Verify & Visually Inspect

Run repo-cinema verify and inspect contact-sheet.png directly with your file/image viewer:

• Confirm passed: true, offscreenClicks: 0, and readable text across all 9 keyframe thumbnails.
• If any element clips near viewport edges, increase marginPx in computeCausalFraming or reduce zoom by 0.06 and re-render.

Reference Guides

• Camera & Cursor Physics
• 4-in-1 Stage Adapters
• Storyboard Schema
• Open-Source Architecture & Attributions

Common Mistakes to Avoid

• Following the pointer frame-by-frame during typing/dragging: Causes motion sickness. Always lock camera framing per beat during holds.
• Using wall-clock setTimeout / real-time screen capture: Drops frames whenever CPU spikes and produces choppy 24–40fps recordings. Always drive animations via __rcStep(dtMs).
• Zooming too aggressively (> 1.35x) on wide charts or tables: Clips Y-axis labels or rightmost summary columns. Keep wideLockRatio at 0.70 so fx = width / 2.
• Committing large raw .mp4 binaries into the GitHub repo: Track lightweight palette-optimized .gif + contact-sheet.png in docs/assets/ and attach .mp4 to GitHub Releases or ignore *.mp4 locally.