Seamless Scene
← Make an edit

Find every shot of a character

Index a whole episode once on your own PC, review the cast it finds, and export the chosen character’s shots as cast-selection.json, the input for batch swaps.

Download the package (ZIP, 470 MB)Download this guide as Markdown (for your AI agent)
Version
cast-id-6
Package
469991763 bytes, sha256 feb8b7bc76bc0750583fa126828cb46cdabedcba1a00ac040f409a5abe4e2f78
Agent file
49299 bytes, sha256 7535e5f8b3a61254841c3fd0c13e3ea6b715e919fccab062eadf363866a12227

Check both before you open them. The same values are in the manifest; if anything differs, stop.

What you need

  • Windows (64-bit) with an NVIDIA GPU with 16 GB: verified, on an RTX 5070 Ti with PowerShell 7. Linux and smaller GPUs are not yet certified.
  • About 470 MB for the package, plus its setup downloads (a portable Python and FFmpeg, and the Python packages), which the package lists with their exact sizes and hashes.
  • Your episode as a local video file. Everything runs on your PC; nothing is uploaded.
  • No ComfyUI, no language model and no global changes: the package makes its own folder and environment.

The steps

  1. Verify, then set up once. Compare the ZIP’s size and sha256 with the values above before you extract it into a new folder. Setup downloads a pinned portable Python 3.12 and FFmpeg build, checks every hash, and installs the Python packages offline from the supplied hash-locked lists. Four model files are already in the package. Expected: the package check and the CUDA check pass, and your GPU’s name is shown.
  2. Check the public demonstration. The package’s tests and a GPU run on the complete short film Tears of Steel (12:14, with its credits), which is in the package. Expected: 135 shots and ten character groups (3 main, 6 secondary, 1 background), and nothing recomputed on a resumed run.
  3. Add an episode, or a batch. Double-click RUN-CAST.cmd, open its local link, and enter your episode files, one per line. Use whole episodes. For a recording that holds several episodes, split it at the real episode boundaries first, and keep the original recording.
  4. Resume after an interruption. Run the same batch again: finished stages are checked and reused; an interrupted stage starts over. A changed source, code, model or runtime is refused and needs a new batch.
  5. Review the cast (a human step). Open the episode’s review page and correct the groups: reassign one shot, merge two groups of the same person, or split one occurrence into a new character. Undo reverses the last edit. Screen time is an estimate from sampled frames, not an exact count. Each group is labelled by its share of the analysed range: main at 5% or more, secondary at 1% or more, otherwise background. The labels describe screen presence, not importance. You can change both cutoffs at the bottom of the gallery, which shows them in seconds too; raise them for a short clip.
  6. Choose and confirm the character (a human step). Check the portraits and the shot list, pick the group, tick that you reviewed its grouping and press Confirm grouping. Only a person confirms: an agent must never set a review flag or press a confirmation. Confirming covers the grouping only, not shot boundaries, masks, pictures or takes.
  7. Export the selection. Choose Export this character’s shots and keep both cast-selection.json and cast-selection-audit.json. Check the file with either checker: it should print VALID: seamless-cast-selection-v1.

Where a person decides

An AI agent can run the package from its Markdown file, but it stops and waits at every checkpoint the file marks: before each download batch and install, and above all at the group review and the character pick. Those two are yours alone.

The hand-off: cast-selection.json

  • One file per episode and character: the shots as [Start, Resume) frame ranges, one person box per shot as a tracking anchor, and whether each shot is selected. It holds no media.
  • Frames are the truth; times are derived from them. At most 500 shots per file.
  • Short shots stay selected with a warning: the batch swap adds untouched original frames around them at delivery so each clip reaches 1.5 s.
  • The next step reads it: Swap a person, batch mode.

The contract: schema · README · checkers Node and Python (no dependencies; put them next to the schema).

Credits and licenses

  • Tears of Steel © Blender Foundation / Blender Institute, 2012, CC BY 3.0: mango.blender.org/about. The complete film, with its credits, ships inside the package only; keep it and this credit together. To watch it, use the film’s own site.
  • Shot detection uses the TransNetV2 architecture with pinned third-party PyTorch weights. Face detection and recognition use YuNet (MIT) and SFace (Apache 2.0); person detection uses YOLOX (Apache 2.0). Python and FFmpeg are separate pinned third-party downloads under their own licenses. The full notices are in the package.