OpenVideo Studio

What it does

OpenVideo Studio bootstraps a complete, isolated AI video environment around a local ComfyUI checkout. One command clones or updates ComfyUI, builds a dedicated Python virtual environment, installs the PyTorch build that matches your GPU (or CPU), installs the curated custom-node stack (LTX-Video, VideoHelperSuite, KJNodes) at pinned commits, optionally adds ComfyUI Manager, and downloads the official ComfyUI-packaged Wan 2.2 model files from a pinned, reviewed source.

Requirements

Quick start

Windows (PowerShell)

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1 -Cuda cu128 -Models 5b -WithManager

The default lock policy is non-destructive: if an editor, type checker, or ComfyUI process is using ComfyUI\.venv, the installer lists only the scoped blockers and exits before changing Git or packages. To authorize stopping those scoped process trees and rebuilding:

.\install.ps1 -Cuda cu128 -Models 5b -WithManager -LockedVenvAction Stop

Use -ReuseVenv for an incremental package update only when the existing environment is healthy.

AMD GPUs on Windows (DirectML)

.\install.ps1 -Cuda directml -Models 5b -WithManager

When -Cuda is omitted, the installer inspects the display adapters: a machine with both NVIDIA and AMD GPUs asks interactively which one to use, and an AMD-only machine selects DirectML automatically. The DirectML backend installs torch-directml and onnxruntime-directml instead of the CUDA builds.

Linux

chmod +x install.sh
CUDA=cu128 MODELS=5b WITH_MANAGER=true START=false ./install.sh

macOS or any machine without an NVIDIA GPU

CUDA=cpu MODELS=5b START=false ./install.sh

Validate the plan before installing (network-free)

./install.sh --cuda=cu128 --models=5b --start=false --dry-run=true

Start ComfyUI

# Windows
.\ComfyUI\.venv\Scripts\python.exe .\wan2_cli.py start --path . --port 8188

# Linux / macOS
./ComfyUI/.venv/bin/python ./wan2_cli.py start --path . --port 8188

Pick the GPU explicitly with --device gpu|directml|cpu, or use the Windows npm shortcuts: npm run wstart:cuda, npm run wstart:amd, npm run wstart:cpu (npm run wstart auto-detects). Then open http://127.0.0.1:8188 and verify the backend:

curl http://127.0.0.1:8188/system_stats

Launcher deep dive

wan2_cli.py start runs ComfyUI from the managed checkout with loopback binding and automatic device selection. Device resolution order in auto mode: CUDA (or ROCm builds of torch) → DirectML (if torch_directml is importable) → CPU. ROCm installs additionally get --use-pytorch-cross-attention. CUDA and DirectML cannot share one virtual environment, so the launcher keeps one per backend: selecting a device the current environment does not provide provisions a sibling venv on first use (ComfyUI/.venv-directml or ComfyUI/.venv-cuda, with the matching torch build plus ComfyUI and custom-node requirements) and launches from it — later selections reuse it instantly. On Windows, npm shortcuts select the device directly: npm run wstart:cuda, npm run wstart:amd, and npm run wstart:cpu (npm run wstart keeps auto-detection).

The launcher also scopes Hugging Face caches (HF_HOME, HF_HUB_CACHE, TRANSFORMERS_CACHE) to a local hf_cache/ directory under the project root, so model-hub downloads stay inside the project tree.

Installer options

Windows — install.ps1

Linux / macOS — install.sh → wan2_installer.py

Every setting is available both as an environment variable and as a --name=value argument. The shell wrapper validates values, then delegates to the cross-platform Python installer.

wan2_installer.py also exposes models (refresh model files only), start, and react (scaffold an optional status-page frontend) subcommands; every subcommand honors --dry-run.

Model selections and provenance

Every model file resolves through an immutable commit and a sha256 checksum pinned in the versioned manifest config/models.json: Wan 2.2 artifacts from Comfy-Org/Wan_2.2_ComfyUI_Repackaged, the legacy LTX-Video 0.9.x checkpoint from Lightricks/LTX-Video with its comfyanonymous/flux_text_encoders encoder, and the current LTX-2.3 stack from Lightricks/LTX-2.3-fp8, Lightricks/LTX-2.3, Comfy-Org/ltx-2.3, and Comfy-Org/ltx-2. Both installers verify each download against its manifest hash (and re-verify existing files), so Windows and Unix installs stay byte-for-byte consistent and a truncated download can never sit silently in the tree.

Download behavior

• Files land under ComfyUI/models/ in checkpoints, diffusion_models, vae, and text_encoders — the only destinations the manifest is allowed to name.
• Manifest paths are validated against a strict pattern; traversal segments are rejected before any download starts.
• Existing files above a sanity-size threshold are kept; interrupted downloads resume from .part staging files with bounded retries.
• An optional HF_TOKEN enables gated assets. On Windows it is passed to curl through stdin so it never appears in a process command line or log.

Curated node stack

"Ready to use" means the nodes your video workflows need are already installed. Both installers consume the versioned manifest config/nodes.json: each required custom node is cloned from its upstream GitHub repository, checked out at a pinned commit, and its requirements.txt is installed into the project virtual environment. Skip the stack with -SkipNodes (Windows) or --skip-nodes=true (Unix).

Architecture

The repository is a bootstrap and launch layer around third-party ComfyUI and Wan assets. There is no application backend, account system, media store, telemetry service, or hosted inference API — runtime state lives entirely under your local ComfyUI/ tree.

Installation flow

Security and privacy model

Trust boundaries to keep in mind

• Git hosts, package indexes, and Hugging Face are external supply-chain boundaries; a successful TLS download is not a checksum-verified artifact.
• ComfyUI and custom nodes execute code with your user's permissions — review third-party nodes before installing them.
• The project does not maintain cryptographic hashes for model artifacts; for high-assurance deployments, record and verify digests independently.

Repository layout

openvideo-studio/
├── install.ps1                    # Windows installer (hardened, lock-aware)
├── install.sh                     # Linux/macOS wrapper with validation + dry run
├── wan2_installer.py              # Cross-platform installer implementation
├── wan2_cli.py                    # Local ComfyUI launcher (loopback by default)
├── wan2_cli_args.py               # Shared argument validators (port, model source)
├── config/models.json             # Versioned model source, revision pin, artifact map
├── config/nodes.json              # Curated custom-node stack at pinned commits
├── scripts/Installer.Venv.psm1    # Scoped Windows lock detection and safe removal
├── scripts/sanitize_workflows.py  # Workflow privacy gate (strips account metadata)
├── scripts/                       # Optional maintenance and repair utilities
├── tests/                         # Port-contract, lock-policy, and repo validation suites
├── docs/                          # Architecture, installers, provenance, testing, releases
├── examples/                      # Sanitized example ComfyUI workflows
├── site/                          # This page (deployed by GitHub Actions)
└── ComfyUI/                       # Local runtime tree; ignored by Git

Optional utilities

Everything in scripts/ is opt-in maintenance tooling — none of it runs during a normal installation.

Validation — local-first by design

GitHub Actions in this repository does one thing: deploy this page. There is intentionally no hosted test pipeline — correctness, security, and privacy gates run locally, where a real Windows executable lock and a real filesystem can actually be exercised:

npm run check

That single command runs, in order:

• the inclusive port contract (1–65535) across the PowerShell installer and both Python entry points;
• a live Windows executable-lock integration test proving the Fail policy is non-destructive, the scoped Stop policy removes only its own process tree, and deletion guards hold — under PowerShell 7 and Windows PowerShell 5.1;
• parse checks for every maintained PowerShell, Python, and workflow JSON file;
• a privacy sweep of all tracked filenames and text for personal paths, machine names, emails, tokens, and workspace identifiers;
• ruff linting, Bash syntax checks, the network-free Unix installer dry run, and offline npm lockfile consistency.

Tests resolve any Python 3.10+ interpreter automatically (py -3.10 → py -3 → python3 → python), so the suite runs unmodified on Windows, Linux, and macOS. On non-Windows systems the native lock test is skipped and reported as skipped — never silently passed.

Troubleshooting

Access to .venv\Scripts\python.exe is denied

This is normally a Windows executable-image lock, not a permissions problem. Rerun with the default -LockedVenvAction Fail to see the scoped process list, close those processes, or explicitly allow scoped termination with -LockedVenvAction Stop. If an earlier deletion was interrupted partway, rebuild rather than passing -ReuseVenv.

Large PyTorch download fails

Rerun with -ReuseVenv once the new venv and pip exist. Network installs already use bounded command retries, pip connection retries, resume attempts, and a longer socket timeout.

CUDA is unavailable

Confirm the NVIDIA driver supports the selected PyTorch CUDA build, then inspect the environment directly:

.\ComfyUI\.venv\Scripts\python.exe -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

Memory errors: os error 1455 or hostbuf_file_reader_read

Both usually mean Windows ran out of physical or commit memory while staging model weights. Escalate in order: free RAM first (WSL/Docker and editor windows are common consumers) and prefer fp8/fp4 text-encoder variants over fp16; then launch with --disable-pinned-memory (via CUSTOM_WAN_COMFYUI_ARGS) so transfers spill to the page file; then add --disable-dynamic-vram — dynamic VRAM streaming (comfy-aimdo) has had issues with quantized video models independent of free RAM and is actively patched, so keep ComfyUI and comfy-aimdo updated; on multi-GPU machines add --cuda-device 0. A different error, "buffer length … must be a multiple of element size", means a model file is truncated — re-run the installer, which sha256-verifies and replaces corrupt files.

The AMD GPU is not being used

With both NVIDIA and AMD cards installed, auto prefers CUDA. Force the AMD path with npm run wstart:amd (or --device directml); the first run provisions ComfyUI\.venv-directml, which downloads several GB. Verify the DirectML environment directly:

.\ComfyUI\.venv-directml\Scripts\python.exe -c "import torch_directml; print(torch_directml.is_available(), torch_directml.device_name(0))"

If a provisioning run was interrupted, delete ComfyUI\.venv-directml and select the device again to rebuild it.

Contributing and community

Small, single-purpose pull requests are easiest to review. Keep loopback-only binding and non-destructive lock handling as defaults, run npm run check before submitting, and call out review-sensitive changes (new download hosts, process termination, token handling, model sources) explicitly.

• Contributing guide
• Security policy — report sensitive findings privately
• Support policy
• Code of conduct
• Full operational documentation