seriesmith

seriesmith

A series config and episode scripts in, finished episodes out: any shot on any model, on your own GPU, on Comfy's cloud, or hosted through Comfy Router.

You describe a show once in series.json (the cast, the places, the voices, the look) and write each episode as a screenplay-flavoured markdown script (epNN.md). seriesmith parses the script into a model-free story (shotlist/shots.json), compiles every shot for the video target that renders it (a model and how to drive it), makes the reference pictures, keyframes and voices the shots need through image and audio targets, renders each shot on a backend, and cuts the takes together, through upscale, post and master.

You drive it from the editor, a page in your browser that seriesmith serve opens (shots, takes, refs, the cut, the Jobs queue), or from one command, seriesmith. Every shot is its own job, so a bad shot is rendered again alone and the rest of the episode is untouched; a shot written continuous: reads the take before it when its job starts, so a whole chain still queues at once. Every take is kept with the exact settings that made it.

seriesmith is the successor to h3pipe, which did all this on one local ComfyUI.

New here? Getting started: install it from ComfyUI-Manager and it runs in ComfyUI on the models you already have; docs/AUTHORING.md is the script and series config format.

The documents

| | What it is | Read it when | |---|---|---| | docs/QUICKSTART.md | Getting started: from ComfyUI-Manager, on a page of its own, or a clone in custom_nodes | First | | docs/FULL_SETUP.md | The node packs, model files, LoRAs and software for every feature, by job: H3 at full quality, voices, upscale, post, master, 360s | Turning on a feature that says something is missing | | INSTALL.md | Each part in detail: seriesmith, the node pack, the workflows, every model file with its folder and link, a first episode | Setting up by hand, or a model is missing | | docs/SETUP.md | The backends: your ComfyUI, Comfy Cloud, deployments, Router; the default models; the settings file and the key | Choosing where shots render | | docs/EDITOR.md | Driving the editor: the order things happen in, every button, what click, double-click and right-click do in each panel, and the keyboard | Using the editor | | docs/IMPORT_XML.md | An edit from Premiere, Resolve or Final Cut 7 (an FCP7 XML) as a new show: a shot per clip, its footage the take, the cut and its sound kept; the three ways its footage comes in | You have an edit to bring in and enhance | | docs/AUTHORING.md | The format, and the whole of it: a first episode to copy, every field of the script and the series config, framing, timing, camera and the reference rules | Writing or fixing an episode. Read once before the first one | | docs/SCRIPT_CONVERSION.md | A spec-format screenplay scene worked all the way through to shots | You have a screenplay and want it as an episode | | docs/STORY_STRUCTURES.md | Story structures (three-act, Story Circle, Fable, Kishōtenketsu, the Hero's Journey, …): each one's beats, their share of the runtime, how beats become shots, and each beat's music for the first-pass score | Outlining an episode from scratch | | docs/SOUND_GUIDE.md | The episode's sound in order: voices only (the takes' voice stems), a place's ambience bed, a shot's effects, a score drafted from the script's beats, themes across a show, the mix and its stems | Making an episode sound like one piece | | docs/SCORING.md | Scoring an episode: the spotting sheet, a first pass drafted from the beats, hits, cues and the cue window, themes, takes, levels | Putting music under a cut | | docs/MUSIC_VIDEO.md | A music video: the song as the episode's recording, the lyrics as lines, the vocal stem | Cutting to a finished song | | docs/FINISHING.md | Render size, upscale, master, post and titles: how takes become a delivered master | Finishing an episode | | docs/COMMANDS.md | The command line in depth: build, refs, render, assemble, takes and the cut, recorded dialogue, the project layout | Working from a terminal | | docs/CONTINUOUS.md, docs/POST_PROCESSING.md, docs/RECORDED_DIALOGUE.md, docs/KREAGEN.md | Continuous shots; the post pass; lip sync to a recording; the reference-image generator | Using that part | | docs/H3_TARGET.md | The default video target, MiniMax H3 Ref2VA, in detail: its reference slots, sheets, voices, audio policies, pacing | Tuning shots for H3 | | docs/API.md | The editor's HTTP API and the on-disk contracts behind it (takes, overrides, the cut, references) | Changing the editor, or driving seriesmith from your own code | | docs/DESIGN.md, docs/PLAN.md | How seriesmith is built (backends, the queue, the two hosts) and the work list | Changing seriesmith | | CONTRIBUTING.md | House rules: the golden tests, how the generated docs are regenerated | Sending a change |

prompts/SKILL.md and prompts/seriesmith-script.instructions.md are generated from docs/AUTHORING.md by python tools/make_prompts.py, so an assistant drafting a script reads exactly what you do; the same command builds the installable script-writing skill (prompts/seriesmith-episode-script.zip, committed, to upload in Claude or unzip into .claude/skills/). Edit the guide, never the copies — a test fails if they drift.

  you write                     generated                                    rendered
  ─────────                     ─────────                                    ────────
  series.json ─┐                shotlist/shots.json (story)
  epNN.md     ─┼─ build ─▶      shotlist/shotlist[.<target>].json ─ render ─▶ renders/<shot>/<shot>_tNN.mp4
  (recording) ─┘  (align)       refs_todo.json ─── refs / keyframes ─▶ refs/       │
                                                                     assemble / master ─▶ epNN.mp4

Targets and backends

A shot renders on MiniMax H3 Ref2VA unless the script (target:), a render profile, the episode (chosen in the editor) or the series config (series.target) names another. A shot retargeted in the editor or with seriesmith override is compiled for its new target when it is queued; no rebuild.

| Video target | Label | Runs on | |---|---|---| | minimax_h3_ref2va (default) | MiniMax H3 Ref2VA | a ComfyUI: local, Comfy Cloud, a deployment | | fasth3_omni | FastH3 Omni: FastVideo's 8-step H3, up to eight subjects a shot | a ComfyUI | | minimax_h3_fl2va | MiniMax H3 FL2VA (first/last frames) | a ComfyUI | | ltx2 | LTX-2.5 distilled (text / keyframes to video + audio) | a ComfyUI | | ltx2_ingredients | LTX-2.3 ingredients (character/plate refs) | a ComfyUI | | wan22_i2v | Wan 2.2 14B I2V | a ComfyUI | | wan22_ti2v | Wan 2.2 5B TI2V | a ComfyUI | | wan22_vace | Wan 2.2 14B VACE (refs) | a ComfyUI | | hosted video models (Seedance, Kling, Wan, Veo, Runway, hosted H3, …) | the models seriesmith has tried, plus drafts to probe; the Models window lists them, and adds any other from Router's catalog | Comfy Router |

| Image target | Label | |---|---| | krea2 (default for refs) | Krea 2 turbo (text to image) | | hosted image models (Nano Banana, Seedream, GPT Image, Flux, Qwen, Krea 2, …) | on Comfy Router; listed and added in the Models window | | z_image_turbo | Z-Image Turbo (fast text to image) | | flux2_klein | FLUX.2 Klein 9B (text to image) | | flux2_klein_edit (default for keyframes, when installed) | FLUX.2 Klein 9B edit (uses reference images) | | flux_kontext | FLUX.1 Kontext dev (edit, one reference) | | minimax_h3_still | MiniMax H3 as an image model: renders 5 frames, keeps the first, up to 9 references | | fasth3_omni_still | FastH3 Omni as an image model, as minimax_h3_still | | qwen_image_21 | Qwen-Image 2.1: text to image, or an edit of up to 16 reference images | | fibo2_dev | Fibo 2.0 Dev: text to image, or an edit of up to 4 references (non-commercial licence) | | fibo2_edit_turbo | Fibo 2.0 Edit Turbo: 4-step edits only (non-commercial licence) | | qwen_rapid_aio | Qwen-Image-Edit Rapid AIO: a 4-step all-in-one edit checkpoint, up to 3 references | | klein_erp_360 | FLUX.2 Klein 9B with a 360 outpaint LoRA: a plate as an equirectangular panorama (the Refs tab's Make 360) |

| Audio target | Label | |---|---| | ltx2_voice (default for voices) | LTX-2.5 audio-only: one speaking voice from a character's voice line | | drama3 | Fish Audio Drama 3: a character's voice sample cloned | | qwen3_tts | Qwen3-TTS: a voice designed from a character's description, then cloned | | fishaudio_drama3 | Drama 3 hosted, through ComfyUI's Fish Audio partner nodes (paid) | | stable_audio3 (default for score) | Stable Audio 3 Medium: music cues | | ace_step15 | ACE-Step 1.5 XL: music cues, and repaint (bars of a take made again) | | yue2 (default for songs) | YuE2: songs, sung from lyrics (non-commercial licence) | | mmaudio_ambience (default for ambience) | MMAudio large 44k v2: a place's ambience bed | | sa3_sfx_ambience | Stable Audio 3 Small SFX: a place's ambience bed | | h3_foley (default for effects) | MiniMax H3 FL2VA: a shot's effects from its picture | | ltx23_foley | LTX-2.3 Foley LoRA: a shot's effects from its picture | | hunyuan_xl_foley | HunyuanVideo-Foley XL: a shot's effects from its picture |

Each target lives in seriesmith/targets/<kind>/<id>/: target.json (presets, the model files it needs with their tier and download links, how to drive it, which backends can run it), its code (the prompt writer, the compile) and, for a workflow target, workflow.json. A Comfy Router model is data only: its target.json says where a shot's prompt, pictures, length, size and seed go in the provider's request (tools/make_router_targets.py writes the built-in ones).

Your own models. The editor's Models window (beside every model picker) adds another Comfy Router model from Router's catalog (its schema read, its limits checked, a free dry run of the request), or turns a workflow saved in your ComfyUI into a model: video for shots, or image for refs and keyframes, ending in any save node. Save one for every show (targets/ beside the settings file) or for one show (<show>/targets/<id>/); a new one is a draft until you probe it and enable it. Every video model and hosted image model has a Limits form (length, size, prompt length, pictures, sound); a change to a built-in one is kept on this machine. From the command line, seriesmith target-from-workflow <workflow> <episode> --save saves a workflow as that show's model (--save --every-show: every show's).

Backends are where a job runs: local (your own ComfyUI, straight to its own API), cloud (Comfy Cloud), deployment:<target> (a deployed workflow) and router (a hosted model through Comfy Router). The last three need a Comfy API key. A job runs on the request's backend, else the shot's, the episode's, the series config's (series.backend), else its target's first. seriesmith backends lists what this machine is set up for; docs/SETUP.md sets them up.

What's installed? With ComfyUI running, seriesmith targets prints one line per target (ready, degraded, not_ready, unknown) and every missing file under it with its models folder and download link. A missing required file skips the shot with its link; a missing accelerator (a turbo LoRA) renders the slower base preset, and the take says so. The editor's model pickers and its Models window show the same.

Install

INSTALL.md is the full walkthrough; docs/QUICKSTART.md the short one. Three ways, one app:

• Inside ComfyUI: Manager → Custom Nodes Manager, search for seriesmith, install the latest nightly (no numbered release is approved on the Comfy Registry yet), restart ComfyUI (or, once one is, comfy node install seriesmith). The editor is in its sidebar and renders on it. No other node pack is needed.
• On a page of its own: git clone https://github.com/bgstratt/seriesmith.git, then run_seriesmith.bat (this PC; run_seriesmith_ext.bat: your home network too; run_seriesmith.sh on Linux/macOS) sets itself up in the folder's .venv the first time, opens the editor at http://127.0.0.1:8190, and starts it again after the editor's Restart; seriesmith stop [--restart] stops it from a terminal. It renders on a ComfyUI, or with only a Comfy API key, on Comfy's cloud.
• A clone in custom_nodes, for following main: git clone https://github.com/bgstratt/seriesmith.git in ComfyUI's custom_nodes, and restart ComfyUI. (Cloud and Router want comfy-sdk in ComfyUI's Python: Settings gives the command. A clone kept elsewhere: link its comfy_nodes into custom_nodes instead.)

The default models are the ones you already have: H3, else LTX-2, else Wan 2.2 for video; Krea 2, else FLUX.2 Klein, ... for pictures (docs/SETUP.md, "The default models"). Everything else is optional, and Settings → Features… lists it (downloading the model files and ffmpeg itself; a node pack from ComfyUI-Manager, a Python package by the pip command it gives):

• more models;
• H3's sparse attention (the PlagueKind pack: H3 renders without it, marked degraded);
• voices;
• upscalers;
• post-processing;
• a full ffmpeg.

docs/FULL_SETUP.md lists it all by feature. INSTALL.md has every model file with its link, generated from the targets by python tools/make_models_md.py.

Requirements, in short:

• a recent local ComfyUI and an NVIDIA GPU that can hold the models you use (developed on a 32 GB card), or a Comfy API key and the cloud;
• git;
• Python 3.10+, only for the editor on its own page and the command line.

ffmpeg comes with it (imageio-ffmpeg and PyAV), and your own wins if you have one.

The editor

seriesmith serve (or seriesmith serve --root Shows) serves the editor at http://127.0.0.1:8190:

• Shots (sidebar): the project folders (roots) and the episode, the pass (final / proxy) and the episode's model; build; every shot with its takes, status and stale marks; render, redo, cancel, pick the take the cut uses, discard a take. Import… (Project folders) asks which: An edit (FCP7 XML)…, a cut from Premiere, Resolve or Final Cut 7 as a new show (docs/IMPORT_XML.md), or a seriesmith series, which brings in a whole season's scripts at once, with one series config or one per episode.
• Refs (sidebar): every character view, prop, plate, voice and shot keyframe the series config and script call for, with candidates to generate, import, compare, edit, turn, discard and pick; a location's angles, its 360 panorama and its H3 camera tour.
• Timeline (bottom): the cut as an editable track — reorder, trim frame by frame, lock, undo, Play all and Export.
• Sound (under the timeline's clips): the Dialogue, Effects, Ambience and Music lanes, each with its fader, mute and solo, and the mix heard in Play all and rendered on export: voices only (the takes' own music split off), a bed for each place, a shot's effects from its frames; the spotting sheet drafts a first-pass score from the script's story beats and places the episode's music, the cue window shapes a cue and picks its take, and a take can become a theme the whole show carries (docs/SOUND_GUIDE.md, docs/SCORING.md).
• Viewer (docked in the middle): a shot's takes with A/B compare (side by side or wipe), a ref's candidates, a tour to keep any frame from, a 360 in its viewer; scroll on the picture to zoom.
• Gallery: every picture of the refs and every take of the shots, large, in one window; arrow through them, see what each was made with (its prompt, model, seed and the pictures it was sent), regenerate, pick, and save a selection as one zip. A ref other episodes share brings their pictures too.

• Jobs (the queue button, top right): every render, ref, upscale, post and tour queued, running and done, per backend — with progress, the log, cancel, reorder, pause a backend, and run again as a new take.
• Script, Series config, Inspector, Recording, Audio from…, Promote, Upscale, Post-process, Master and Models open as floating windows.
• Settings (top bar): this machine's Comfy API key, ComfyUI and deployment addresses, the default video and picture models, and, on the PC that runs the server, Stop and Restart.

docs/EDITOR.md is the guide to driving all of it. Everything the editor does is a file in the episode folder (overrides.json, cut.json, take records, _history/), and the commands do the same.

Quick start (command line)

seriesmith new      Shows\ep05             # a series config + script that build (from examples/starter/)
seriesmith check    Shows\ep05             # validate and check dialogue pacing (writes nothing)
seriesmith build    Shows\ep05             # the story, shotlists, reference work orders
seriesmith targets  Shows\ep05             # which targets this ComfyUI can render
seriesmith supply   Shows\ep05 C:\sheets   # pictures you already have, into their ref slots
seriesmith refs     Shows\ep05             # generate the views, props, plates still missing
seriesmith render   Shows\ep05 --proxy     # low-res animatic
seriesmith assemble Shows\ep05 --proxy     # join it into one mp4
seriesmith render   Shows\ep05             # full-res
seriesmith master   Shows\ep05             # the series recipe (upscale, post) on every shot, then the master
seriesmith publish  Shows\ep05             # the review cut between the series intro and outro

Every command has --help; --backend NAME picks where its jobs run. The command line runs its jobs on a queue of its own and waits for them; the editor's server runs its own queue. docs/COMMANDS.md covers every command.

Tests

pip install -e .[test]
python -m pytest                  # six workers in parallel; -n 0 for one process
cd web && npx vitest run

The golden tests rebuild every fixture and compare the results byte for byte with tests/golden/; no test reaches a real backend.

License

MIT — see LICENSE.