[repo-study-julius-caesar-script-continuous-video] Script-to-continuous-video engine with byte-stable bibles, hard-cut linter, and episode composer

[atomantic]

Provenance

• Studied Repository: willemhelmet/julius-caesar
• License: MIT
• Date: 2026-09-04

Rationale

willemhelmet/julius-caesar solves the fundamental problem of generating continuous video from dramatic scripts without visual degradation. When chaining video clips:

1. Omitting full, byte-identical descriptors across clips causes models to mutate character faces, clothing, and environment.
2. Attempting continuous takes ("the camera continues", "still on her face") causes compounding visual smear, repeat, and collapse across chained clips.
3. Dialogue pacing needs to snap to model frame grids (e.g. 17n+5 or 24fps) with explicit speaker tagging.
   While PortOS has low-level chunk stitching (server/services/videoGen/chainedVideo.js), it lacks a high-level script-to-video production system connecting Writers Room / Story Builder / FableLoom scripts to continuous video rendering. Adopting upstream's byte-stable bibles, hard-cut prompting rules, and beat compiler gives PortOS authors a complete pipeline to generate multi-scene episodes that play as one seamless video.

Proposed Changes

1. Script-to-Beats Compiler (server/lib/scriptVideoCompiler.js):
   • Ingest scene scripts and partition dialogue/actions into discrete beats (<=35 words, <=2 speakers).
   • Calculate clip duration from spoken word count (~2.5 words/sec + 1.5s air) snapped to target frame rates (24fps / 17n+5).
   • Inject byte-stable "Bible" slot descriptors for cast (build + hair + age + one color accent), locations (visual + ambience), and style into every clip prompt.
   • Format dialogue into explicit speaker clauses: S1 (Speaker, voice): "...".
   • Enforce a maximum chain length (<=6 clips) before mandating a fresh re-establish (fresh cut).
2. Deterministic Video Prompt Linter (server/lib/videoPromptLinter.js):
   • Ensure every continuing clip (cut_type: 'continue') opens with an explicit hard cut ("Hard cut to <framing>:") and distinct camera framing/angle from the preceding clip.
   • Enforce character string verbatim presence (the canon lock).
   • Reject cross-clip continuous referents ("same", "still", "again", "continues", "as before").
   • Reject negative constructions ("no", "without", "never") and UI overlays ("text", "caption", "overlay").
   • Check character length bounds (e.g. <=800 chars).
3. Continuous Video Orchestrator (server/services/videoGen/continuousVideo.js):
   • Coordinate sequential generation across supported video backends (Reactor fast-h3, fal.ai, local LTX).
   • Thread previous clip identifiers (continue_from_clip_id or last-frame still extraction) into dependent beats.
   • Fall back to a fresh re-establish if an upstream clip in the chain fails or is evicted, preventing pipeline stall.
   • Stitch completed clips into a final episode video using stitchVideos.
4. Episode Composer UI (client/src/components/videoGen/EpisodeComposer.jsx):
   • Interactive multi-scene composer in MediaGen and Story Builder allowing users to write rough episode ideas or import scenes from FableLoom / Writers Room.
   • Live AI scene expansion enforcing the hard-cut and self-containment rules.
   • Visual beat inspection showing camera cuts, speaker tags, slot locks, and lint status.
   • Seamless "Queue episode" action that locks capacity and streams progress.

Fix:

• server/lib/scriptVideoCompiler.js
• server/lib/videoPromptLinter.js
• server/services/videoGen/continuousVideo.js
• server/services/videoGen/chainedVideo.js
• client/src/components/videoGen/EpisodeComposer.jsx
• client/src/pages/VideoGen.jsx
• client/src/components/fableloom/LoomSettingsDrawer.jsx

Estimated Scope

Large feature (epic): ~800 lines across server compiler/linter, continuous orchestrator, and client EpisodeComposer component, backed by comprehensive unit tests for beat compilation, prompt linting, and chained video sequencing.

Decomposed into

• Script-to-Beats Compiler for continuous video episodes #6225 — Script-to-Beats Compiler for continuous video episodes
• Deterministic video-prompt linter for continuous episode clips #6226 — Deterministic video-prompt linter for continuous episode clips
• Continuous video orchestrator: coordinate chained episode clip generation #6227 — Continuous video orchestrator: coordinate chained episode clip generation
• Episode Composer UI for continuous multi-scene video in MediaGen and FableLoom #6228 — Episode Composer UI for continuous multi-scene video in MediaGen and FableLoom