Script-to-screen synchronization for AI filmmakers.
Sync scripts and screenplays with video. Evaluate AI-generated footage. Analyze script-to-screen fidelity.
hb_sceneflow_v1_ex1_the_expansion.mp4
SceneFlow is a tool that syncs scripts and screenplays with video content, letting you see which parts of your prompt appear on screen in real-time.
Built for evaluating how AI video models visualize prompt instructions, it supports both traditional Screenplay formatting and high-precision, state-driven Auteur Script formatting with 5-part staging metadata. SceneFlow helps you compare instructions against what was actually generated — essential for assessing prompt adherence and iterating on AI cinema projects.
Note on Cue Creation: SceneFlow does not automatically extract or generate video sync cues for you. Cues must be mapped manually (by highlighting text in Edit Mode and setting timestamps) or generated externally using multimodal AI models (such as Gemini) that analyze video frames against script timecodes.
- Script-to-Screen Tracking — Highlights which parts of your script are playing in real-time
- Dual Script Workflows — Seamlessly handles both human-readable screenplays and state-chained Auteur Scripts
- Color-Coded Cues — 8 element types: dialogue, action, camera, shots, audio, VFX, transitions, environments
- Adherence Analysis — Pinpoint missed prompt elements, camera drift, or continuity deviations against the generated video
- Timing Controls — Adjustable buffers to fine-tune when highlights appear
- Portable — JSON-based projects you can save, share, and version-control
| Feature | Description |
|---|---|
| Cue-Based Sync | Link specific script segments to video timestamps |
| 8 Cue Types | Dialogue, Action, Camera, Shot, Audio, VFX, Transition, Environment |
| Auto-Scroll | Script automatically follows dialogue during playback |
| Auto-Alignment | Re-match cues when script text changes |
| Timing Buffers | Adjustable before/after timing for each cue type |
| Type | Color | Purpose |
|---|---|---|
| 🟡 Dialogue | Yellow | Character speech and conversations |
| 🔵 Action | Blue | Physical actions and movements |
| 🟢 Camera | Green | Camera movements and angles |
| 🟣 Shot | Purple | Shot descriptions and framing |
| 🟠 Audio | Orange | Sound effects and music cues |
| 🔷 VFX | Cyan | Visual effects descriptions |
| 🩷 Transition | Pink | Scene transitions |
| ⚪ Environment | Slate | Setting and atmosphere descriptions |
hb_sceneflow_v1_ex2_intent_over_rules_script.mp4
- Import/Export — Save and load projects as JSON files
- Remote Sharing — Share projects via URL using query parameters
- Raw Editing — Direct access to screenplay text and cue data
- Example Library — Pre-built demos to get started quickly
- Local Storage — Automatic saving of your work
- Dynamic App Theming — Full workspace theming in Light, Warm, and Dark modes with seamless 250ms CSS variable switching
- Auto-Sync Mode — Application shell automatically adapts to match the active screenplay paper category
- Theme Presets — 6 screenplay paper themes: Studio Crisp, Warm Parchment, Midnight Slate, OLED Blackout, Navy Slate, Newsprint
- Mobile Theme Drawer — Native bottom-sheet drawer with 4-segment mode switcher and compact swatch cards
- Adaptive Logo — Automatic dark/white logo switching across light, warm, and dark surfaces
- Width Presets — 5 reading column widths from Narrow (384px) to Expanded (1024px)
- Scroll Focus — 3 viewport alignment anchors (Top, Center, Bottom) for auto-scroll positioning
- In-Place Cue Editing — Edit cue text directly without touching raw JSON
- Mobile-Responsive — Native bottom-sheet drawers for library and themes with adaptive staging badges
- App Info & Attribution — Desktop information modal with dynamic versioning (
v2.2.0), author attribution, and documentation resource links - Keyboard Shortcuts — Desktop hotkeys for playback (
Space,K), seeking (← / →,J / L), and universal modal dismissal (Esc) - Vercel Analytics — Audience traffic insights and real-time Web Vitals monitoring
- PWA-Ready — Web manifest and icon suite for standalone app installation
SceneFlow features a fully redesigned, responsive Library Catalogue serving as an interactive hub for screenplays, cinematic series, and AI-generated video examples:
- Dynamic Sorting & Filtering — Toggle by newest, oldest, or A-Z with real-time search across titles, descriptions, tags, and volumes.
- Cross-Device Fluidity — Full modal dialog on desktop; touch-friendly bottom-sheet drawer on mobile.
- Category Navigation — Browse by AI Scenes, The Written Motion, FRAME Series, and AI Clips with contextual section badges.
- Featured Curations — Handpicked standout scripts surfaced at the top.
→ See the full list in SceneFlow Catalogue with IDs, dates, and video models.
SceneFlow helps you see how well an AI model followed your screenplay prompt:
- Assess Prompt Adherence — Compare what you wrote vs. what the model generated
- Spot Gaps — Quickly identify which script elements were missed or poorly rendered
- Compare Models — Test the same script across different AI video generators
- Iterate on Prompts — Understand what works and refine your screenplay instructions
Browse all projects in the SceneFlow Catalogue — organized by AI Scenes, The Written Motion, FRAME Series, and AI Clips, each with shareable ?example= IDs.
- Node.js (v18 or higher)
- npm or yarn
# Clone the repository
git clone https://github.com/taruma/SceneFlow.git
# Navigate to project directory
cd SceneFlow
# Install dependencies
npm install# Start development server
npm run dev
# Open in browser
# Default: http://localhost:3000- Load a Script — Use the built-in Library (
?example=ID), load a remote URL (?project=URL), or import a JSON project file. - Play the Video — The script highlights in real-time as the video timeline progresses.
- Auto-Scroll & Focus Mode — Script automatically follows active cues. Click the Focus Mode dropdown next to Auto-Scroll to filter which cue types trigger scrolling (e.g., track Dialogue only).
- Scroll Focus Line — Choose where the active cue centers in your viewport (Top 35%, Center 50%, or Bottom 65%).
- Script Width Presets — Toggle between 5 reading column widths (Narrow to Expanded) for side-by-side video review.
- Script Themes — Switch between 6 light, warm, and OLED dark themes via the theme picker.
- Switch to Edit — Click the "Edit" toggle in the header.
- Set Video Source — Paste any YouTube video URL, short ID, or direct video link.
- Edit Script Text — Click "Edit Raw" to modify the complete script and staging blocks.
- Create & Adjust Cues:
- Highlight any text in the script preview to open the Cue Editor.
- Snap start/end timestamps using the clock button or manual inputs.
- Choose a cue category (Dialogue, Action, Camera, Shot, Audio, VFX, Transition, Environment).
- Edit the selected cue text directly in-place using the monospace editor without touching raw JSON.
- Handle Overlaps — Click overlapping highlights in the script to select specific cues via the Overlap Picker.
- Align Cues — Click "Align" to automatically re-anchor highlights if script text changes; use "Find Alternative" to resolve duplicate phrase occurrences.
- Export — Download a portable JSON project file via "Save Sync".
| Key | Action |
|---|---|
Space / K |
Play / Pause video |
← / J |
Rewind 5 seconds |
→ / L |
Forward 5 seconds |
Esc |
Close active modal / dialog |
SceneFlow supports sharing projects directly via URL. When a project is loaded via query parameter, a confirmation dialog will appear to prevent overwriting your current work.
You can load any built-in screenplay example directly by appending ?example=ID to the URL.
See the SceneFlow Catalogue for the complete ID-to-title reference across all four sections.
You can load any JSON project hosted on a CORS-enabled server by appending ?project=URL.
Example:
sceneflow.taruma.my.id/?project=https://raw.githubusercontent.com/user/repo/main/script.json
Note: The remote server must allow Cross-Origin Resource Sharing (CORS) for the fetch to succeed. GitHub Gist "Raw" links are recommended for sharing.
SceneFlow uses deterministic heuristics and regex to parse, render, and synchronize both traditional screenplays and technical Auteur Scripts.
SceneFlow accommodates both major prompting styles used across AI filmmaking:
-
Classic Auteur (Screenplay Style):
- Uses traditional cinema formatting: Scene Headings (
INT./EXT.), character dialogue blocks, parentheticals, and bold action lines. - Ideal for narrative scenes, multi-page drama, and human-readable script sharing where natural language guides the model's visual staging.
- Uses traditional cinema formatting: Scene Headings (
-
Auteur Script (Technical State Engine):
- Uses modular state-transition blocks enclosed in
[<BRIEF>]tags with chained arrows (->) and bold anchor tokens ([CAM],[ACT],[AUDIO],[STATE OUT]). - Ideal for reasoning-based video models where each Macro-State line (
$S_n$ ) inherits the visible physical coordinates of the previous beat without hallucinating resets.
- Uses modular state-transition blocks enclosed in
Both workflows share the exact same Staging metadata and Timeline Cue synchronization engines.
| Element | Format | Example |
|---|---|---|
| Scene Heading | Starts with INT. or EXT. |
INT. OFFICE - DAY |
| Character Name | ALL CAPS followed by a colon | JOHN: |
| Dialogue | Lines immediately following a character name | Everything starts with intent. |
| Parenthetical | Text wrapped in parentheses | (whispering with excitement) |
| Bold Direction | Single line in ALL CAPS (emphasized action) | HE PIVOTS SHARPLY TO FACE THE DOOR. |
| Action | Mixed case narrative paragraphs | The cursor blinks on a clean slate as the creator leans in. |
| Shot / Camera Note | Text wrapped in square brackets [...] |
[CLOSE-UP – MONITOR DISPLAY] |
| Effect | Starts with SFX: or VFX: |
SFX: Mechanical keyboard click |
| Separator | Three dashes on a single line | --- |
| Part Separator | PART followed by a number |
PART 1 |
| Roman Title | Roman numeral + dot + Uppercase Title | I. THE BEGINNING |
| Auteur Script Block | Block wrapped in [<BRIEF>] and [</BRIEF>] |
See below |
SceneFlow embeds high-level prompt directives directly into your project using Staging Blocks. Staging content is concealed from the main reading flow and replaced with an interactive STAGING badge that opens a monospace inspector modal.
The standard Auteur Script framework is built upon a 5-part scaffold (modular and adaptable based on the specific scene or generation task):
-
[INTENT]— High-level vision, subject definition, and core emotional beat. -
[LOGIC]— Hard guardrails for visual planning (spatial continuity, 180° axis, object permanence). -
[AESTHETIC]— Master audio-visual reference (palette, lighting, wardrobe, location, textures). -
[OPENING]— Locked first-frame coordinate anchor ($S_0$ ) establishing baseline geometry. -
[EXECUTION]— Active timeline state-transition pipeline (wrapped in[<BRIEF>]).
Within SceneFlow, all non-execution setup blocks (parts 1–4) are encapsulated inside [[STAGING]]...[[/STAGING]] to keep the reading timeline clean:
-
[[INTENT]]— Scene vision, identity, and tone. -
[[LOGIC]]— Hard guardrails for visual planning. -
[[AESTHETIC]]— Master audio-visual styling parameters. -
[[OPENING]]— Starting first-frame coordinate anchor ($S_0$ ). -
Optional Extensions: Directives like
[[CONTINUITY PROTOCOL]]can be added for multi-shot video extensions; legacy directives ([[GLOBAL]]and[[LOOKBOOK]]) remain fully backward-compatible. -
Execution Separation: Everything inside
[<BRIEF>]...[</BRIEF>]represents the[EXECUTION]block (never labeled as staging), driving the active state-transition pipeline.
[[STAGING]]
[[INTENT]]
Create a cinematic, dialogue-driven academic drama scene featuring Mark and Robert.
[[/INTENT]]
[[LOGIC]]
Ensure rigid spatial continuity across camera setups. Preserve object permanence for the metronome.
[[/LOGIC]]
[[AESTHETIC]]
Medium: 35mm film texture.
Palette: Deep navy blue, rich mahogany dark oak, warm amber tungsten.
Lighting: Overhead tungsten auditorium grid lighting.
[[/AESTHETIC]]
[[OPENING]]
Establishing wide shot of the auditorium stage. Mark stands stage left; Robert holds a wooden metronome stage right.
[[/OPENING]]
[[/STAGING]]
For high-precision AI video models, wrap your timeline execution in [<BRIEF>] blocks. SceneFlow renders this in a dedicated monospace card and applies two automatic layout engines:
-
Waterfall Indentation: Every
->delimiter automatically creates a new line with nested indentation (\n ->), turning complex prompt sequences into clean visual beat cascades. -
Bold Anchor Tagging: Any bracketed dimension tag like
[CAM],[ACT],[AUDIO],[STATE IN], or[STATE OUT]is automatically bolded (<b>[...]</b>) for rapid cognitive scanning. -
State Chaining: Each line represents a Macro-State (
$S_n$ ), composed of modular Sub-States that map frame transformations over time.
[<BRIEF>]
[CAM 01] MS, eye-level lockoff -> [ACT] Creator types the first command -> Creator: "Let's build." -> <Mechanical keyboard click> -> [STATE OUT] Frame locked in clean focus
[CAM 02] MCU, low-angle on monitor -> [ACT] Screen reflects glowing amber text -> [AUDIO] Low cooling fan hum
[</BRIEF>]
This project is licensed under the MIT License — see the LICENSE file for details.
Author: Taruma Sakti Megariansyah