[davior]

Summary

Adds docs/gecko-video-creator.md, a draft spec for Gecko Video Creator (GVC) at gvc.geckopico.com. GVC is the third app in the Gecko Suite: Notes provides the script, GAM provides the media, and GVC produces the video.

Today, Notes' article-to-video export only has an implicit model of a video: a flat Shot list re-inferred from the note's blocks on every render, plus one global RenderOptions. This doc makes that model an explicit JSON document, the VideoSpec, which both an AI and the UI can edit.

The doc covers:

• The current export as a baseline: how segmenter.py turns a note into shots, every RenderOptions field, and the limits of that model. Music, motion and transitions are global only, there's one music track, no clip trimming and no timed overlays.
• The VideoSpec schema: segments (scene, card, clip), the narration beats inside them, overlays, any number of audio tracks, an asset registry, and credits.
  • Timing is segment-anchored. Music, sound effects and overlays attach to segments or beats with optional offsets.
  • Exact seconds are only worked out by a compile step at render time.
• A worked JSON example with a trimmed clip from GAM, a quote overlay shown while its line is read, two music tracks that crossfade, a sound effect, and placeholders for an image to generate and footage to find.
• A table mapping every current export feature to the VideoSpec, so importing an existing note loses nothing.
• How the AI edits a video: a deterministic importer writes the first draft, then the AI proposes small, validated operations that are stored as JSON Patches. Changes are reviewed, never applied silently.
• Where material comes from: the Notes and GAM APIs, marked as existing or still to build.
• Phased migration: Phase 0 proves the schema inside Notes against the current renderer before GVC exists.
• Open decisions: ten listed at the end.

It also records an existing bug: the video dialog's Voice picker writes options.voice, but the renderer never reads it and always uses the account voice.

This is a docs-only change. No application behaviour changes.

Test plan

• The worked-example JSON parses.
• Every anchor in the example points at an existing segment or beat, and every asset key it uses exists.
• All relative links in the doc point at files that exist.
• The Mermaid diagrams render in GitHub's markdown view.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PwaujUokXQAxnebBArpZuj

---

Generated by Claude Code