Skip to content

Script Reader & Breakdown

The script system turns a screenplay into structured production data — scenes, blocks, characters, props, audio — and gives artists one page per scene to read, break down, voice, board, and assemble.

Getting a script in

Entry point: process_script(script_path) in alc/models/script/create.py.

Source Path
FDX (canonical) ScriptStore.from_fdx() parses the .fdx and writes script.json
PDF PdfScreenplay.to_fdx() (alc/models/script/models/pdf.py) converts to a sibling .fdx first — margin-band classifier, optional OCR
Transcript The trs task turns transcribed audio/video into a TranscriptEdit and emits script.json

After ingest, entity discovery (check_for_assets()) plus AssetManifest and ScriptAuditor produce assets.json and audit.json.

The model

ScriptModel → ScriptScene → ScriptBlock (alc/models/script/models/script.py, block.py):

  • ScriptScene — heading, location, DAY/NIGHT, INT/EXT, entity pools (characters, speakers, props, sounds, fx), blocks[], and a derived timeline.
  • ScriptBlock — one beat, typed (action, dialogue, transition, ...). Carries text, speaker, characters/props, notes, a per-block camera (framing / role / angle / movement), and audio state: dialogue_clip, voice_path, word timestamps, storyboard root.

Asset reference convention

Entity ids live in block lists; display labels live in text. References are resolved at audit-commit time.

The reader

GET /c/{company}/project/{project}/scenes/{scene_id}/read (app/tools/script/script_viewer.py) — screenplay text plus the integrated timeline, scene-prep band, and per-block actions:

  • Voice takes — generate TTS per block, or record from the mic; playback streams inline.
  • Breakdown sidebar — click a block to edit its entities and camera; auto-frame a block or the whole scene.
  • Storyboards — initialize/generate boards per block; batch-render to the farm.
  • Scene prep — drag concept art onto character/location slots to stage designs for publish.
  • Open in Blender — builds the previs scene from the script state and launches Blender on it.

Breakdown grid & audit

Launched from shelf buttons:

  • Breakdown grid — GET /script/breakdown?path=... with characters / locations / props tabs and Excel export.
  • Entity resolver — GET /script/resolver?path=... — the audit checklist where discovered entities are validated, merged, and renamed before commit (/script/commit-resolver). Publishing follows the merge convention: script fields replace, production metadata preserves, orphans are marked omt rather than deleted.