Shot Record Loader

This is the node where the whole pack starts, and the name is honest in a way you'll appreciate once you're three nodes deep: it loads a shot, it doesn't invent one. ComfyUI-Storyboard-Layout is a layout engine, not a storyboard generator - its entire job is answering "given a shot, where should things go?" This node is the "given a shot" part. You feed it a shot definition, it validates and normalizes it into clean JSON, and the rest of the chain (Composition Layout Generator → BBox Generator) takes over from there.

What it actually does

Three ways in, one normalized record out. In order of precedence:

• shot_json - a multiline STRING. Paste raw JSON like {"shot_type": "wide_establishing", "subjects": ["knight", "cathedral"]}. This is the normal path.
• shot_file - a path to a JSON file on disk. Useful when you're iterating on shot lists in an external tool.
• shot_type + subjects - manual fields, so you don't need to write JSON at all. subjects is a comma- or newline-separated list.

Fill shot_json and it wins; otherwise it falls to shot_file; otherwise the manual fields. If you leave all three empty, the node raises a clean ValueError telling you to provide one of them.

Whatever you feed it gets normalized deterministically: subject names are trimmed and de-duplicated (order preserved), the aspect ratio defaults to 16:9, composition is lowercased, and a shot_id of 1 is assigned if the record doesn't have one. It validates against the pack's shot schema, so shot_type and subjects are the two fields that must actually exist in your JSON.

The output you wire onward

The single output, shot_json, is the normalized record as a STRING - same shape you put in, tidied up. It feeds directly into the Composition Layout Generator. That's it. One shot per execution, which is the v0.1 limitation you should know about up front: hand it a JSON array of several shots and it refuses with "received N records" rather than guessing. Multi-shot batching is the planned v0.2 feature.

Installing it

Same story for every node in this pack, so here's the once:

cd ComfyUI/custom_nodes
git clone https://github.com/SurrealByDesign/ComfyUI-Storyboard-Layout

Then restart ComfyUI. Or use ComfyUI Manager and search "Storyboard Layout" - it's published on the ComfyUI Registry under the surrealbydesign publisher. The dependency story is refreshingly boring: nothing extra to install. Pillow, numpy, and torch are all provided by ComfyUI already, and the pack deliberately doesn't pin them to avoid clashing with your environment.

Where people get tripped up

• The "provide shot_json, shot_file, or shot_type" error. You dragged the node in, clicked Queue, and got this. Nine times out of ten you didn't actually type anything into any of the three inputs. Type something.
• "subjects must be a list" - your JSON has "subjects": "knight, cathedral" as a string. It needs to be ["knight", "cathedral"].
• Invalid JSON errors - the pack wraps these now (v0.1.1 hardened the error handling), so you'll get the parser's message instead of a silent crash. Pasted JSON that ends in a stray comma is the usual culprit.

One more thing worth knowing: everything is deterministic and offline. No API calls, no LLM, no keys. Same input gives you the same normalized output, every time - which is exactly what you want from a pipeline node.