Research spike — MP4 / GIF export of a Storyboard traversal (encoding-pipeline trade-off)

[IanMayo]

Problem

The original storyboarding epic (#24 → #215–#218) deferred "MP4 / GIF video export of a Storyboard traversal" to phase 2. Video export is the natural shareable artefact for stakeholder briefings on networks where neither VS Code, the web-shell, nor even the air-gapped briefing zip (#264) are usable (read-only kiosk displays, email attachments, conference slide decks). However, the encoding pipeline involves real trade-offs (bundle size, offline-first guarantees, codec licensing, output quality, frame-rate fidelity) and the right approach is not obvious. Committing to an implementation before evaluating those trade-offs risks shipping the wrong shape.

Proposed Solution

Time-boxed research spike, not shipping code.

Evaluate at least the following encoding-pipeline candidates and produce a recommendation:

1. Client-side via MediaRecorder + ffmpeg.wasm

   • Encoding inside the webview / SPA, no service.
   • Pros: fully offline-by-default (Article I), no service round-trip, runs inside the briefing renderer zip too.
   • Cons: ~20 MB bundle bloat (ffmpeg.wasm); slow on long Storyboards; codec licensing varies.

2. Service-side via Python (services/export/ + system ffmpeg)

   • Frontend captures a PNG sequence, hands to a new Python service that shells out to ffmpeg.
   • Pros: cleaner Article IV.1 separation; faster; smaller frontend bundle.
   • Cons: introduces a system dependency (ffmpeg); doesn't ship inside the air-gapped briefing zip; harder to use from the web-shell.

3. Hybrid — PNG sequence captured client-side, encoded via WebCodecs API (modern browsers) with ffmpeg.wasm fallback only for unsupported browsers / GIF output.

Deliverables of the spike:

• A research note at docs/project_notes/storyboard-video-export-research.md covering:
  • Bundle-size measurements for each option.
  • Encoding-time benchmarks against a representative 10-Scene Storyboard at 1080p.
  • Output-quality comparison (sample artefacts committed under evidence/).
  • Offline-by-default compatibility per Article I.
  • Air-gapped briefing zip (Refactor map feature selection styling to use CSS classes #264) integration story for each option.
  • Recommended path forward + the follow-up backlog item that would implement it.
• New backlog item(s) created from the recommendation (a separate implementation ticket, not bundled into this one).

Success Criteria

• A clear recommendation has been recorded with measurements, sample outputs, and reasoning.
• A follow-up implementation backlog item has been created (or the project has decided "not yet" with a recorded reason).
• The research artefact is committed and referenced from the parent epic notes.
• Total spend: ~1–2 dev-days.

Constraints

• No shipping code from this ticket — research artefact + sample / throwaway prototypes only.
• Article I (offline-first) — any solution that requires a network round-trip at export time is disqualified.
• Article XIV — pre-release freedom permits introducing whatever schema / service surface the recommendation needs when implementation lands.
• Time-box to two days; if the comparison is inconclusive, document the open questions and pick the lowest-risk option.

Out of Scope

• Any production / shipping implementation of video export.
• Audio narration / soundtrack.
• Interactive video (chapter markers, click-to-jump).
• Real-time streaming / live broadcast.
• Format conversion utilities beyond MP4 / GIF (no WebM, no AV1, etc. in scope of the spike).

Dependencies

• Conceptually downstream of spec(075): Add branching from history point specification #215–Add move-shape and enlarge-shape tool specifications (#056, #057) #218 (the thing we'd be exporting), all complete.
• Independent of Add range-time-plot tool specification (v1.0) #263 (time-range Scenes) and Refactor map feature selection styling to use CSS classes #264 (briefing zip), but the recommendation should consider how each integrates.

---

Originally captured under epic item #229 in BACKLOG.md; promoted via /interview 229 (2026-05-19) — epic was split into three independent items. This one is a research spike, lower priority than #263 / #264.