Neo Studio

Neo Studio

🇨🇳 中文: README_ZH.md

From one sentence to prompt, image, and film: AI prompt enhancement, image generation and reference editing, and MiniMax H3 multi-segment video direction — all in one plugin. The LLM can run inside the ComfyUI process with zero extra dependencies.

Install: search Neo Studio in ComfyUI Manager (published to the ComfyUI Registry), see Installation.

Why Neo Studio

| Capability | Usual approach | Neo Studio | |------------|----------------|-----------| | Local LLM | Needs llama-cpp-python (often fails to build on Windows) | Native: safetensors text-generation models run inside the ComfyUI process, no extra dependency | | Cloud LLM | Fill endpoint and model name by hand | Built-in DeepSeek, Alibaba Cloud Bailian, Kimi, Zhipu GLM, SiliconFlow — add an API key and go; 🔌 Test Connection verifies live | | Model downloads | Download manually, then drag files into folders | ModelScope + Hugging Face dual-source search, files land in the right model folder by repo path, resumable downloads | | Chinese input | English / filename matching only | Chinese skill names searchable by full pinyin and initials; pinyin LoRA trigger-word suggestions | | Image / video generation | Wire up dozens of nodes | Pick a skill and generate (skills ship a workflow.json template); H3 multi-segment director with drag-and-reorder timeline | | After moving machines | Red nodes everywhere, fix paths one by one | 🅝 menu → "Repair Workflow" matches broken paths against real files on disk in one click | | Asset reuse | Pick images one by one with LoadImage | Gallery lightbox + ✈️ one-click write into a target node; recipes send to canvas in one click |

Works without an LLM

Available right after install and restart, with no model or API key configured:

• 🖼️ Neo Gallery — asset browsing, lightbox, file management, ✈️ one-click send to node; Civitai LoRA matching and bookmarks; batch LoRA tagging
• 🧊 Neo Recipes — save prompt + media as a recipe, one-click send to workflow (with director recipe editor)
• 🔧 Workflow Repair — one-click fix for broken model paths
• 📥 Model Hub — ModelScope / Hugging Face dual-source search with resumable downloads (ModelScope listing and search work anonymously)
• 🔲 Neo Reference Grid / 🧩 Neo Grid Split — reference-image grid management, automatic storyboard grid splitting
• 🧊 Neo Studio — standalone page (neo-studio.bat or http://127.0.0.1:8188/neo-studio; neo-studio-app.bat opens it in its own window): Assets, Director, Skills, Settings

LLM enhancement (✨ generate / image captioning / translate & classify) is the optional second step; the three modes are documented in docs/en/llm.md.

Features

| Module | Type | Description | |--------|------|-------------| | Neo Prompt Encoder | Node | Prompt management + AI enhancement; CONDITIONING + text for txt2img → prompts.md | | Neo Prompt Agent | Node | Prompt generation without CLIP; PROMPT text + BUNDLE → prompts.md | | Neo Image Gen & Edit | Node | Skill-template generation / reference editing; IMAGE output → image-gen.md | | H3 Video Director | Node | MiniMax H3 multi-segment video with native audio; drag-reorder timeline → h3-video-gen.md | | Neo Bundle Expand | Node | BUNDLE → prompt + image_1..9 for official H3 Reference-to-Video → prompts.md | | Neo Reference Grid | Node | Prompt + up to 12 reference images in one grid node → prompts.md | | Neo Grid Split | Node | Storyboard grid → IMAGE batch + embedded prompt → h3-video-gen.md | | Neo Gallery | Sidebar | Asset browser, lightbox, send-to-node, Civitai LoRA, LoRA tagging → gallery.md | | Bookmarks | Asset panel | Local bookmarks + Civitai bookmarks (download-on-open) → gallery.md | | Neo Recipes | Sidebar | Recipe management with one-click send to workflow → recipes.md | | Workflow Repair | Menu item | One-click fix for broken model paths → workflow-repair.md | | Model Hub | Menu item | Dual-source repo search, category placement, resumable downloads → model-hub.md | | Skill Management | Menu item | Inline workflow editing, canvas import & writeback, change preview + history → skills.md | | MCP Server | Standalone process | Claude Desktop / Cursor calling image & director tools over stdio → mcp.md |

Node appearance:

Demo

Interaction recordings (click a thumbnail to open the matching doc):

• — 🎞️ H3 Video Director · timeline reorder
• — 🧊 Neo Recipes · one-click send

Installation

Neo Studio App is the recommended form. It is the Studio window (Assets / Director / Skills / Settings), it starts and stops ComfyUI from its own settings page, and it puts the plugin into custom_nodes by itself — you never touch the plugin folder. It needs a ComfyUI install with its Python interpreter; it does not bundle ComfyUI.

• Portable app — a single file, Neo-Studio-<version>-windows-x64.exe, attached to GitHub Releases by .github/workflows/release-app.yml (built by tools\build_studio_exe.ps1, unsigned — expect a SmartScreen prompt on first run). It derives the ComfyUI root and the interpreter from its own location, opens a first-setup page when it cannot find them, and installs or updates the plugin from its bundled copy — user data dirs are carried over, a git checkout is never touched.
• From source — clone the repo and run tools/neo-studio-app.vbs (no console window; tools/neo-studio-app.bat is the debug entry, --debug opens DevTools). Every launch syncs studio/ into custom_nodes (same-name files only, nothing in the target is deleted).

The window, the offline service and the kernel controls: Neo Studio (Standalone App).

<details> <summary>ComfyUI plugin form — the nodes inside ComfyUI's own UI, without the Studio window</summary>

• ComfyUI Manager: search Neo Studio and install.
• comfy CLI: comfy node install comfyui-neo-studio
• Manual: clone into ComfyUI/custom_nodes/, then restart ComfyUI:

git clone https://github.com/neoneo-ai/neo-studio.git ComfyUI/custom_nodes/comfyui-neo-studio

The clone form runs on the repo root __init__.py, which hands node and route registration to studio/; the installed package (Registry, Manager, tools/install_plugin.ps1, desktop sync) has studio/__init__.py at its own root and never goes through it.

Source install: tools/install_plugin.ps1 installs the code and the built-in presets and writes the configs/data_root.json data-root pointer (user data lives outside the plugin dir, so uninstalling is just deleting the plugin dir). Commands, parameters and release switches: docs/en/release.md.

Upgrading from the old package: the Registry package moved from comfyui-neo-nodes to comfyui-neo-studio, and nothing disables the old folder for you — the plugin sync only writes comfyui-neo-studio. Delete ComfyUI/custom_nodes/ComfyUI-Neo-Nodes (or rename it to ComfyUI-Neo-Nodes.disabled, which ComfyUI skips) before installing the new one: keeping both directories registers the same nodes twice. Installs from 1.2.0 on keep user data outside the plugin directory, so removing the old folder touches no data. The pre-1.2.0 plugin kept configs/, gallery/, prompts/, recipes/, skills/ and locals/ inside its own folder and there is no migration — copy those into the data root first.

</details>

Dependencies

• openai, PyYAML, pypinyin, Pillow (auto-installed via requirements.txt; Pillow ships with ComfyUI core)
• Optional extras (features degrade gracefully when a package is missing): laya (smart skill picking), pillow-heif (HEIC reading), oss2 (Backyard OSS upload)
• llama_cpp_python (optional, only for local LLM inference)

Quick Start

1. Open Neo Studio (the app) — it installs the plugin and starts ComfyUI for you. Plugin-only users: install it and restart ComfyUI.
2. Zero-config features first (no LLM, no model setup needed): ✈️ send an asset from the Gallery lightbox into a LoadImage-type node (gallery.md), download models from the Model Hub with automatic category placement (model-hub.md), repair broken workflow paths from the 🅝 menu (workflow-repair.md).
3. Configure an LLM — pick one; needed for ✨ enhancement, image captioning and translate/classify: Native (safetensors in models/text_encoders/, runs inside the ComfyUI process, zero extra dependency), Remote (provider + API key, "🔌 Test Connection" verifies live) or Local (GGUF in models/LLM/). Setup, endpoints and GGUF rules: docs/en/llm.md.
4. First prompt: add a Neo Prompt Agent node → type a short description → click ✨ → AI-generated prompt text (no CLIP needed).
5. First image: add a Neo Image Gen & Edit node → pick an image-gen skill → prompt (from the Agent or manual) + optional reference images → queue → IMAGE output. Needs a GPU / VRAM, and the skill must declare gen_image: true and ship a workflow.json; model / Text Encoder / VAE default to "Auto".
6. First multi-segment video: add a H3 Video Director node → pick a video_director recipe → drag to reorder segments / regenerate a single segment → stitched into one VIDEO with audio.

Key Concepts

• Skill: A bundled template containing model config (model/VAE/CLIP), workflow, and default parameters. Preset skills are read-only; copy to customize.
• Bundle: Runtime payload — prompt text + optional reference images.
• Recipe: Saved prompt + media assets for reuse. Director recipes support multi-segment video generation with a timeline editor.

Neo Studio (Standalone App)

Canvas-independent page with four tabs: Assets (the full Gallery), Director (director recipes + editor + full-film generation with progress, cancel and live preview), Skills, Settings (image / video / LLM / ComfyUI log). Canvas-only actions show a hint instead of failing.

| Entry | What it does | |-------|--------------| | neo-studio.bat | Opens http://127.0.0.1:8188/neo-studio in the browser, and starts ComfyUI for you | | neo-studio-app.vbs | The same page in its own WebView2 window — no console, no browser tab; window geometry and Studio state survive restarts (needs pywebview; the WebView2 Runtime ships with Windows) | | neo-studio-app.bat | Console/debug entry for the same window (--debug opens DevTools) | | tools/neo-studio.exe | Packaged launcher with the clapperboard icon — built by tools\build_studio_exe.ps1 (release.md) |

• Offline service — app/studio_server.py on ComfyUI port + 3 (8191 by default) keeps browsing, skill / recipe editing, settings (LLM included), Model Hub, bookmarks and LoRA tagging working while ComfyUI is down. Anything that needs the ComfyUI runtime answers 409 offline, the UI says "needs ComfyUI", and the generate buttons become start buttons.
• The header only reports state — "● Running" / "● Stopped" / "● Starting", with the port, the PID and who launched it in the tooltip. The actions live at the top of Settings → 启动设置: one state line plus "▶ Start kernel" and "■ Stop kernel", the one that cannot run right now disabled.
• The window opens first — the dependency self-check, the service setup and the ComfyUI spawn run on a background thread behind a splash page; once the port answers, the page connects generation in place — no navigation, no reload — and stopping ComfyUI flips it back to the offline Studio.
• Closing the window stops the ComfyUI the desktop started (one you started yourself is left alone); a ComfyUI already listening on the port is attached to, never doubled.
• Canvas jumps stay in the window — "⤒ 主画布编辑" and "🎬 新影工坊" switch in place, and the desktop re-injects a "🎬 返回 Studio" pill on every non-Studio page.
• ComfyUI's log is under Settings → Log; the desktop's own trace (startup, page jumps, window drags) goes to data/studio_desktop.log.

Frameless window, window & taskbar icon, exe packaging, portable launcher and the source sync: Developer_EN.md.

Documentation

Full index with a one-line summary of every module doc: docs/en/README.md.

Changelog & License

Version history: CHANGELOG.md. SPDX-License-Identifier: Apache-2.0

10000+ portrait prompt collection source: civitai.com/models/2231696

Developer Docs

Project structure, backend modules, API routes, node registration, tests, and the Studio desktop internals (offline service, capability table, drag loop, launcher config): Developer_EN.md.

---

Contributing

Fork and open a pull request — no organization membership needed. Setup, the test commands, the node and route checklists and the commit rules: CONTRIBUTING.md. Vulnerability reporting and the key redaction rule: SECURITY.md.