StageFlow v1.1.0 — In-Browser WebCodecs MP4 Export & Studio Polish

StageFlow v1.1.0 brings zero-install, deterministic in-browser MP4 video export powered by WebCodecs and mp4-muxer — allowing directors, educators, and choreographers to render clean Stage Cam POV film gates and 16:9 Observer Diorama schematics directly from the web studio without needing Node.js, Playwright, or FFmpeg.

This release also introduces the stageflow-score-creator workspace skill for guided YAML authoring and resolves a subtle split-pane telemetry bug affecting Observer Camera focal length readouts.

---

What's New in v1.1.0

🎬 In-Browser Deterministic MP4 Export (File ▾ → Export Video (.mp4)...)

• Two Selectable Export Cameras:
  • Stage Cam POV: Clean film gate render at gateScale = 1.0 matching your score's aspect_ratio (16:9, 1.85:1, 2.39:1, 4:3, 9:16) with zero viewfinder borders and inherited thin-lens WebGL2 DoF bokeh blur (On / Off).
  • Observer Diorama (16:9): Macroscopic blueprint view locking output to 16:9 (1920×1080 / 1280×720) with visible Stage Camera chassis, tripod/dolly tracks, rectangular gate frustums, focus plane frames, DoF brackets, and 3D trajectory curves. Supports both Scripted Observer and Current Viewport Angle.
• WebCodecs + mp4-muxer Client-Side Pipeline:
  • Dedicated offscreen WebGL <Canvas frameloop="never" dpr={1}> mounted strictly while an export is actively encoding.
  • Progressive H.264 profile negotiation (avc1.640028 → avc1.640033 → avc1.4d002a → avc1.42001f), encodeQueueSize backpressure control, immediate VideoFrame.close() memory cleanup, live progress telemetry, thumbnail preview, and clean cancellation.
  • Configurable 1080p / 720p resolution, 60 fps / 24 fps cadence, Entire Scene / Current Shot range, and Light / Warm / Dark stage palettes.
  • Pure Layer 1 export resolution, timing, aspect-ratio, and filename utilities covered by unit tests in tests/unit/exportMath.test.ts.

🧭 Workspace Authoring Tooling (stageflow-score-creator Skill)

• Added .agents/skills/stageflow-score-creator/SKILL.md for AI-assisted YAML score authoring and pedagogical choreography explanation.
• Enforces strict documentation-only grounding (YAML_AUTHORING_GUIDE.md, STAGEFLOW_SCRIPT_SPECIFICATION.md, SCORE_CATALOG.md) and clean in-chat YAML output without repository pollution.

---

Bug Fixes

• Preserved Un-Adapted Observer Focal Length in Split-Pane Layouts (ObserverCameraRig.tsx):
  • Fixed a bug where narrow split-workspace layouts (where adaptive diorama FOV widens vertical FOV to preserve horizontal stage framing) leaked distorted equivalent focal lengths (e.g., 17mm–21mm instead of 35mm) into the [OBS] Telemetry Capsule and copied YAML snippets during free orbit or preset snaps.
  • ObserverCameraRig now preserves the exact un-adapted optical focal length (lastAppliedFocalLengthMmRef) rather than reverse-converting the canvas-adapted camera FOV.

---

Quality & Verification

• Unit Test Suite: 236 deterministic tests passing across 20 Vitest suites.
• Static Checks: oxlint (0 warnings / 0 errors) and strict TypeScript tsc -b build clean.

---

Upgrade & Usage Notes

• Browser Requirements for In-Browser MP4 Export: WebCodecs (VideoEncoder) is supported in modern Chromium-based browsers (Chrome, Edge) over HTTPS or localhost. For headless CLI batch rendering (libx264, VP9, ProRes .mov, GIF, or PNG sequences), npm run record and npm run record:batch remain available — see Viewport Recorder Guide.
• Backward Compatibility: All v1.0.0 YAML choreography scores remain 100% compatible without changes.

---

Full Changelog & Documentation

• 📜 CHANGELOG.md ([1.1.0]) — Granular file-by-file technical breakdown.
• 📖 YAML Authoring Guide — Complete DSL syntax and production recipes.
• 📐 StageFlow Script Specification — Optical math, kinematics, and normalized AST contracts.

StageFlow v1.0.0 — Initial Release: 3D Camera-Blocking & Scene Choreography Diorama

Welcome to StageFlow

StageFlow is an open-source, web-based 3D camera-blocking and scene choreography diorama. It synchronizes a universal video player (local video files, YouTube URLs, or a 60fps procedural simulator) with an interactive Three.js blueprint stage, allowing you to study, dissect, and visualize the spatial staging and camera maneuvers of film scenes at every millisecond.

StageFlow was born out of genuine curiosity about visual storytelling: What does it actually mean to block a scene? How do camera moves, focal lengths, and performer staging interact to create meaning? Rather than acting as a heavyweight production animatics tool, StageFlow is designed as an analytical sketchbook—stripping away visual clutter down to pure architectural geometry, sightlines, focal planes, and trajectories.

---

What's New in v1.0.0

🎥 Dual-Camera Spatial Architecture

• Stage Camera (Director's Viewfinder):
  • Projects a true-to-aspect rectangular pyramidal frustum matching your reference film gate (16:9, 2.39:1 anamorphic, etc.).
  • Features a sliding Focus Plane Frame, near/far Depth-of-Field limit brackets, and an emerald world-space tether for off-axis subject tracking.
  • Includes an opt-in, single-pass WebGL2 24-tap Vogel disk bokeh blur viewfinder shader ([ Blur ] / hotkey B).
• Observer Camera (Macroscopic Viewport):
  • Plays scripted choreography trajectories smoothly in 'scripted' mode.
  • Features an intuitive pause-to-free-orbit handover: the camera locks to the authored path during playback, and unlocks OrbitControls the instant playback is paused so you can freely orbit, pan, and inspect the frozen staging from any angle.
  • Instantaneous POV cuts ($0\text{ms}$) between 'scripted', 'free', and 'stage-pov' modes.

📐 Choreography as Code (Declarative YAML Schema)

• Authored entirely in human-readable, version-controlled YAML scripts (*.yaml).
• Stateless Functional Timeline (Frame_t = f(t)): Every millisecond of camera movement and actor blocking is purely deterministic. Scrubbing forward or backward yields bit-for-bit identical 3D states with zero cumulative drift.
• 11 Expressive Camera Maneuvers: Static holds, push-in/pull-out dollies, tracking trucks, pedestals, pans, tilts, Dutch rolls, orbital sweeps, Catmull-Rom spline curves, swoops, and compound paths.
• Contiguous Single-Take Takes ("Oners"): Opt-in continuous: true chaining automatically links camera coordinates and actor positions across shot boundaries without teleports or snaps.
• Two-Shot Centroid Framing: Support for multi-subject targets (target: ["detective", "witness"]), dynamically resolving the 3D world-space midpoint and tracking walking actors at 60fps.

⏱️ Precision Universal Media Clock

• Universal synchronization parity across:
  • Local Media: Drag-and-drop .mp4 and .webm files directly into the browser (processed 100% locally in-memory).
  • YouTube Streams: Frame-accurate sync via a custom 60fps performance.now() drift extrapolation engine.
  • Blueprint Simulator: Standalone 60fps virtual clock for studying scores without external video files.
• Remote score loading via query parameters (?score=<catalog-id> or ?url=<raw-yaml-url>) with address bar hygiene.

🔍 Cinematic Optics & Thin-Lens Depth of Field

• Full-frame optical math ($36 \times 24\text{mm}$ sensor geometry) mapping real focal lengths (24mm, 35mm, 50mm, 85mm) to vertical FOV.
• Thin-lens Gaussian Depth of Field with aperture presets (shallow: f/2.8, medium: f/5.6, deep: f/∞) and custom numeric $f$-stops.
• Cinematic rack focus pulls (focus_start $\to$ focus_end) and subject follow-focus.

🛞 Physical Camera Mounts & Dolly Tracks

• Stationary Tripods: Blueprint 3-legged stands with splayed legs, floor pucks, and vertical telescoping center columns.
• Dolly Rails & Carts: Physical dual-rail floor tracks ($0.42\text{m}$ standard gauge) with orthogonal cross-ties and a 4-wheeled dolly cart.
• Catmull-Rom Spline Rails: Curved camera tracks with smooth multi-waypoint guidance.

🧍 Directional Mannequins & 3D Spatial Dimensions

• Characters, set props, and spike marks with configurable 3D dimensions ($w, h, d$).
• Floor-pinned scaling ($Y = 0$) ensuring actors never sink into or float above the stage floor.
• Anatomically preserved head spheres and shoulder bars with telescoping torso columns for crouching and sitting postures.
• Shape-matched ground footprints (oriented rectangular bounding boxes for props, elliptical footprints for characters).

📋 Directorial Studio Shell & Scene Desk

• Executive Scene Production Brief: High-density overview showing scene premise notes (Markdown-enabled), 4-stat production metrics, lens package chips, and active maneuver tags.
• Categorized Call Sheet & Roster: Live inventory of characters, set props, and spike marks with dimension badges.
• Dual-Camera Telemetry Capsule: Bottom-right HUD with integrated [ OBS | CAM ] switcher and 1-click YAML snippet copying.
• 4 Curated Visual Themes: Dark Obsidian (default), Pure Black, Light Stone, and Warm Paper.
• Accessible Info Modal: Press ? anywhere to bring up shortcuts, creative intent notes, and documentation links.

🎬 Deterministic 60fps Headless Viewport Recorder CLI

• Built-in Node.js CLI (npm run record) powered by Playwright and FFmpeg.
• Exports pixel-perfect, 60fps MP4 or Apple ProRes (.mov) viewport choreography videos.
• Three recording viewpoints: Scripted Observer View, Stage Camera POV (Viewfinder), or Picture-in-Picture (Diorama + Viewfinder).
• Optional reference audio track syncing.

📚 Bundled Studies & Educational Blueprints

• Scene Studies (Authored by Taruma Sakti):
  • Vector Field (Sci-Fi Scene Study, 28.0s)
  • The Expansion (Dramatic Ensemble Study, 32.0s)
• Factory Blueprints (BP 01–07):
  • BP 01: Character Blocking & Trajectories
  • BP 02: Camera Maneuver Showcase
  • BP 03: Continuous Single-Take Oner
  • BP 04: Dutch Angle & Camera Roll Banking
  • BP 05: Two Rooms: Architectural Threshold Crossing
  • BP 06: Optics, Rack Focus & Depth of Field Masterclass
  • BP 07: Physical Camera Rigs & Dolly Tracks

---

Studio Keyboard Shortcuts

Shortcut	Action	Description
Space	Play / Pause	Toggle playback. Pausing unlocks free 3D orbit controls.
[ / ]	Step Frame	Step backward / forward by 1 video frame ($1/30\text{s}$).
← / →	Scrub Timeline	Scrub backward / forward by $1\text{s}$ (Hold Shift for $5\text{s}$).
B	DoF Bokeh Blur	Toggle single-pass WebGL2 Stage Cam viewfinder depth-of-field blur.
G	Framing Guides	Toggle rule-of-thirds and safe-action composition overlays.
L	3D Label Mode	Cycle mannequin label display mode (all $\to$ key $\to$ off).
?	About & Shortcuts	Open the About StageFlow dialog and documentation links.

---

Getting Started

1. Launch the Web Studio

Try the studio directly in any modern WebGL2-compatible browser (Chrome, Edge, Firefox, Safari):
👉 https://stageflow.taruma.my.id

2. Run Locally

# Clone the repository
git clone https://github.com/taruma/stageflow.git
cd stageflow

# Install dependencies
npm install

# Start local development server
npm run dev

3. Record a 60fps Choreography Video

# Record bundled Blueprint 06 in 1080p 60fps
npm run record -- --score blueprint-06-optics-dof --camera observer --preset cinematic

---

Documentation & Learning Resources

Detailed technical specifications and authoring guides are available in the repository:

• 📖 YAML Authoring Guide — Comprehensive guide to writing choreography scores with copy-pasteable recipes.
• 📐 StageFlow Script Specification — Mathematical foundations, kinematics, and normalized AST contract tables.
• 🗂️ Choreography Score Catalog — Index of all bundled scene studies and factory blueprints.
• 🎥 Viewport Recorder CLI Guide — Playwright + FFmpeg 60fps video capture workflow.
• 🗺️ Architecture File Map — 5-layer decoupled repository structure and module catalog.

---

Project Attribution & Sister Applications

StageFlow is created by Taruma Sakti (@taruma).

If you find StageFlow helpful for studying cinema, teaching camera blocking, or planning scenes, a shout-out or link back is always appreciated:

StageFlow — 3D Camera-Blocking & Scene Choreography Diorama
Created by Taruma Sakti (https://github.com/taruma/stageflow)

Also check out sister project SceneFlow, a standalone studio synchronizing screenplays side-by-side with reference video.

---

AI Collaboration Note

StageFlow was developed by Taruma Sakti in pair programming with AI agents inside Google Antigravity using Gemini 3.8 Flash and Gemini 4 Argon. It is an exploratory "vibe-coded" project built for creative analysis and learning.

---

Full Changelog

For the complete technical diff and architectural evolution, see CHANGELOG.md.