Installing seriesmith

1. Requirements
2. seriesmith, the proxy and the node pack
3. Workflows
4. Models
5. First run
6. Troubleshooting

​

1. Requirements

• Python 3.10 or later. pip install -e . in the repo installs seriesmith and what it needs (comfy-sdk, aiohttp, Pillow, numpy); a virtualenv is a good idea. The build and check themselves need nothing beyond the standard library.
• ffmpeg and ffprobe on PATH. Assemble, master and publish cut with them; the waveform peaks, the audio import, align and the Recording window need them too. On Windows, winget install Gyan.FFmpeg; on Linux/macOS, your package manager (apt install ffmpeg, brew install ffmpeg).
• Somewhere to render, one or both:
  • your own ComfyUI (a recent local ComfyUI; seriesmith is developed against 0.38 — the MiniMax H3, Krea 2 and SeedVR2 nodes are recent core additions), with the model files of the targets you use (section 4) and a GPU that can hold them. seriesmith has only been run on an NVIDIA RTX 5090 (32 GB) under Windows; the default H3 stack (an int8 diffusion model and a 32B text encoder in nvfp4) wants a recent NVIDIA card. seriesmith expects it at http://127.0.0.1:8188.
  • Comfy’s cloud: a Comfy API key (platform.comfy.org) for Comfy Cloud, your deployments and the hosted models through Comfy Router (docs/SETUP.md). A hosted model (Seedance, Kling, Veo, Nano Banana, …) needs no GPU and no model files; paid use is billed to the key’s account.
• Third-party node packs for some targets — see the table below.

​

Third-party node packs

​

Optional, and what each one unlocks

1. $SERIESMITH_ALIGN_PYTHON, if set to an interpreter path
2. the Python seriesmith runs on
3. python, then python3, as found on PATH

​

2. seriesmith, the proxy and the node pack

​

seriesmith

git clone https://github.com/bgstratt/seriesmith.git C:\code\seriesmith
cd C:\code\seriesmith
python -m venv .venv
.venv\Scripts\activate          (source .venv/bin/activate elsewhere)
pip install -e .
seriesmith --help

​

comfy-api-proxy

pip install comfy-api-proxy

​

The node pack

mklink /J "C:\AI\ComfyUI\ComfyUI\custom_nodes\seriesmith" "C:\code\seriesmith\comfy_nodes"

ln -s /path/to/seriesmith/comfy_nodes /path/to/ComfyUI/custom_nodes/seriesmith

​

The editor inside ComfyUI (optional)

C:\AI\ComfyUI\python_embeded\python.exe -m pip install -e . comfy-api-proxy

​

Check it

seriesmith backends               # each backend, and whether it answers
seriesmith backends --try local   # a picture up through ComfyUI and back
seriesmith targets                # what this ComfyUI can render, and what's missing

​

The upscaler (optional)

1. Clone LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler into custom_nodes:
   cd C:\AI\ComfyUI\ComfyUI\custom_nodes
   git clone https://github.com/LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler
   
   Not its “Plus” fork: that registers the same node without temporal chunking, and the re-sample then invents detail (sparkles on hair, marks on faces). Only one of the two can be installed.
2. Put minimax_h3_latent_upscaler_3d_fp16.safetensors in models/latent_upscale_models/. Its Hugging Face repo, LBH-123-AI/Minimax_h3_latent_Upscaler, now publishes it as minimax_h3_latent_upscaler_3d_conv_v1_fp16.safetensors (the same file): download that and save it under the old name (section 4, For upscaling, has the link).
3. Restart ComfyUI. seriesmith targets then prints upscale ready under minimax_h3_ref2va, or names what’s missing.
4. For takes longer than 5.5 s, clone chanon/comfyui-obvpm-timeline into custom_nodes too. Its H3 Context Windowing node samples the re-sample in overlapping windows along time, so a long shot at 2x (2688×1536) fits a 32 GB card; without it such an upscale says it needs the pack instead of running out of memory. The series’ upscale recipe’s window changes the length (0: off).

​

3. Workflows

1. --workflow <path> on the command line
2. the target’s environment variable, if it points at a file
3. the workflow of that name as saved in the running ComfyUI (fetched over its API, so it always matches your node versions)
4. $COMFYUI_PATH\user\default\workflows\<name>
5. the copy in this repo, targets/<kind>/<id>/workflow.json

• krea2 has one more fallback: finding no file at all, it uses a built-in Krea 2 turbo graph (seriesmith/targets/image/krea2/graph.py). --no-workflow forces that.
• ltx2_voice (and any audio target) puts the repo copy ahead of $COMFYUI_PATH, because no saved canvas is likely to hold an audio-only LTX graph and one of that name would be somebody’s experiment. The running ComfyUI’s saved copy still wins.

​

4. Models

seriesmith targets

​

The minimum set

​

Everything, by model family

​

For upscaling (optional)

• ltx-2.3-spatial-upscaler-x2-1.1.safetensors → models/latent_upscale_models/ (LTXVLatentUpsampler, for ltx2_ingredients) — download (ComfyUI-Manager model list (model-list.json; ComfyUI’s blueprint Image to Video (LTX-2.3).json has the same URL). Only needed to upscale, never to render.)
• minimax_h3_latent_upscaler_3d_fp16.safetensors → models/latent_upscale_models/ (MinimaxH3LatentUpscaler3D, for minimax_h3_fl2va, minimax_h3_ref2va) — download (the Hugging Face repo LBH-123-AI/Minimax_h3_latent_Upscaler, which now publishes it as minimax_h3_latent_upscaler_3d_conv_v1/minimax_h3_latent_upscaler_3d_conv_v1_fp16.safetensors (the same file: sha256 043e5a48e161…, checked 2026-10-09): save it under this name. Only needed to upscale, never to render.)

• seedvr2_ema_vae_fp16.safetensors → models/vae/ — download (ComfyUI templates utility_seedvr2_3b_int8_upscale_video.json / utility_seedvr2_7b_int8_upscale_image.json (properties.models))
• seedvr2_7b_int8_convrot.safetensors → models/diffusion_models/ — download (ComfyUI templates utility_seedvr2_3b_int8_upscale_video.json / utility_seedvr2_7b_int8_upscale_image.json (properties.models))
• seedvr2_3b_int8_convrot.safetensors → models/diffusion_models/ — download (ComfyUI templates utility_seedvr2_3b_int8_upscale_video.json / utility_seedvr2_7b_int8_upscale_image.json (properties.models))
• ltx2: nothing extra. Its render already has a latent upsampler, and an upscale runs that second stage again on the take
• wan22_i2v: an upscale model from models/upscale_models/ (RealESRGAN_x2.pth by default), then its own sampler
• wan22_ti2v: an upscale model from models/upscale_models/ (RealESRGAN_x2.pth by default), then its own sampler
• wan22_vace: an upscale model from models/upscale_models/ (RealESRGAN_x2.pth by default), then its own sampler

​

For the editor’s 360s and turned views (optional)

​

5. First run

Shows\
  MyShow\
    refs\            the pictures, shared by every episode (`../refs/...` in the configs)
    ep01\
      series.json    the series config: the look, the cast, the locations, the voices
      ep01.md        the script
    ep02\
      series.json    its own, so this episode can add a character
      ep02.md

• The script should be named after its folder — ep01\ep01.md. Any other single .md in the folder is accepted, but two of them and nothing can tell which is the script.
• series.json goes in the episode folder. seriesmith build and check insist on it; the editor falls back to a config in the parent folder.

​

Something to copy from

• examples/starter/ — the smallest correct pair: one character, one prop, one location, three shots. It is what seriesmith new writes and what Your first episode in the authoring guide quotes, so it builds with no warnings as it stands.
• examples/series_example.json and examples/script_example.md — a full three-sequence episode with props, a voice-only character and audio: windows. Note that it is written for a recorded dialogue mix (audio.mode: source_track), so its dialogue shots stay blocked until you supply audio/ep01_dialogue_mix.wav or change the mode.
• tests/fixtures/kitchen_sink/ and tests/fixtures/mixed/ — small episodes that exercise most of the format, including shots retargeted onto other models.
• docs/AUTHORING.md is the format itself: every field, the frame grids, the syllable budget, how to break a scene into shots.
• To draft with an AI assistant, python tools/make_prompts.py packages that guide as a skill in build/skill/seriesmith-episode-script/ — copy the folder into .claude/skills/ for Claude Code, or upload the zip beside it on claude.ai. It carries the build, so the assistant can check a script with nothing installed.

​

A first episode

seriesmith new Shows\ep01 --title "First Light"
seriesmith build Shows\ep01

​

The command line

seriesmith targets                      # what this ComfyUI can render (ComfyUI must be up)
seriesmith check    Shows\ep01          # validate + dialogue pacing; writes nothing
seriesmith build    Shows\ep01          # story IR, shotlists (final AND proxy), refs_todo
seriesmith refs     Shows\ep01 --list   # the reference images it would draw
seriesmith refs     Shows\ep01          # draw them
seriesmith supply   Shows\ep01 C:\sheets --dry-run
                                          # pictures you already have: which ref each file
                                          # name means (drop --dry-run to put them in)
seriesmith render   Shows\ep01 --proxy  # queue the shots, one take each -> renders_proxy\
seriesmith assemble Shows\ep01 --proxy  # join them -> renders_proxy\ep01_proxy.mp4

seriesmith render   Shows\ep01
seriesmith assemble Shows\ep01          # -> renders\ep01.mp4

seriesmith upscale  Shows\ep01 --check  # what it would upscale, and how
seriesmith upscale  Shows\ep01          # the cut's final takes -> <take>.up.mp4 (--proxy: the animatic's)
seriesmith assemble Shows\ep01 --upscaled --size 1920x1080   # -> renders\ep01_up.mp4

• check prints the shot count, the runtime, and a pacing table — every dialogue shot with the syllables-per-second it forces on the performance. 0 crammed is what you want.
• build writes shotlist\, refs_todo.md and refs_todo.json and prints the model, LoRA and step count each pass will use.
• refs --list shows what is missing before it spends any GPU time; refs then draws each one, keeping every attempt as a take under refs\_takes\.
• render --list is the dry run. Shots whose reference images are still missing show as blocked, and the report names the exact file each one wants — --allow-missing-refs renders them against flat grey stand-ins if you want to see the motion first.
• assemble --proxy --check reports the cut (order, take, trims) and writes nothing.

​

The same thing in the editor

1. In the Shots tab, check the project roots hold Shows\ (or set them). The episode list fills in.
2. Pick ep01 and the proxy pass.
3. Build — the same build the command line runs, with its report in the panel.
4. Open the Refs tab and generate the character sheet and the plate. Every candidate is a take; pick the one you want.
5. Back in Shots, render — a shot, a selection or the episode. Each take is a job in the Jobs window (the queue button, top right), with its progress and log; takes appear as they finish, and the Viewer plays them and compares two side by side or under a wipe.
6. The Timeline (bottom) is the cut: reorder, trim, pick a take per shot, Play all to watch it without rendering anything, then Export to assemble the one mp4.

​

6. Troubleshooting

cd web
npm install                  # once
npm run build:standalone     # -> ../seriesmith/server/static/
npm run build                # -> ../comfy_nodes/web/seriesmith-editor.js