Multi-functional ComfyUI custom nodes plugin for image/video processing, translation, prompt generation, and more.
cd ComfyUI/custom_nodes
git clone https://github.com/liangzoey/comfyui-ZoeyTool.git
cd comfyui-ZoeyTool
pip install -r requirements.txt
| Node | Description |
|---|---|
| True Size Image Loader | Load images from folder at original resolution, sequential batch output, natural sorting, alpha channel as mask output |
| Batch Image Saver | Save images + text files in batch with custom index, digit count, overwrite mode |
| Mask Bounding Box Drawer | Draw bounding boxes from mask with HTML5 color picker, opacity/fill/width controls, preset colors, light type + prompt output, behind-subject compositing, optional rembg background removal |
| Batch Image Cropper | Batch crop images (left/right/top/bottom), overwrite mode, filename preservation |
| Light Handle Control | Interactive lighting direction with draggable handle, circular gradient mask, lighting prompt output (16 light types), behind-subject compositing, multiple handle shapes |
| Text Overlay | Overlay text on images with custom or system fonts, adjustable size/color/position |
| Multi-function Image Editor | Flip, rotate, split, edge detect, blur, sharpen, threshold, color invert, grayscale, perspective warp, blend, stylize |
| Image Edit Prompt Generator | Auto-generate edit prompts for text/object/style/background editing, virtual try-on, object add/remove |
| Frame Crop/Outpaint | Interactive frame-based cropping and outpainting with fill color, real-time canvas preview |
| Multi-layer Canvas | 5-layer image compositing with drag reposition, scroll scale, rotation handle, and horizontal/vertical flip |
| Node | Description |
|---|---|
| Batch Video Loader | Load video file list from directory, multi-format (mp4/avi/mov), natural sort, limit control |
| Video Batch Processor | Batch process videos (format, frame rate), auto-install dependencies, skip existing |
| Smart Video Saver | Save processed videos with date folders and metadata |
| Node | Description |
|---|---|
| Pure Translator | Multi-engine translation: Helsinki-NLP models / Baidu API / Google API. Supports ZH/EN/JA/KO |
| Hunyuan Translator (HY-MT1.5) | Tencent Hunyuan MT local deployment, 20+ languages, auto-download model cache, terminology & context support |
| Wan2.2 Prompt Generator | Cinematic video prompt generator with 16 control dimensions: subject, scene, action, lighting, composition, lens, style |
| Node | Description |
|---|---|
| Multi File Batch Renamer | Batch rename files with regex find/replace, natural sort, custom start index |
| ZOEYTextEncodeQwenImageEditPlus | Qwen image edit encoder with multi-reference images for Qwen2-VL |
| VR 360° Preview | 360° equirectangular panorama VR viewer powered by Pannellum |
| System Monitor | Live CPU/RAM/VRAM/GPU temperature & utilization dashboard via embedded HTTP server, with background VRAM auto-cleanup |
| MiniMax H3 Reference-to-Video (@) | Wraps official MiniMaxH3ReferenceToVideo with Seedance-style @ reference tags (@P1/@V1/@A1/@C1/@L1) auto-expanded to native tags, plus a storyboard director panel and a permanent global asset library |
| Music Generation (YuE2) | Whole YuE2 pipeline in ONE node: text-to-music, cover (reference song → melody → re-sing), AI lyric writing, voice conversion, LoRA. Type a one-line description, set a duration slider, press Run |
One node replaces an 8-node graph. Everything — checkpoint loading, ABC scoring, music-token generation, sampling, decoding, saving — happens inside a single execute(); no wiring required.
The duration control is honest. 时长(秒) is an upper bound, not a promise. Internally YuE2 turns it into a token budget (25 tokens/second), then silently shrinks that budget if your style/lyrics are long, and may finish early on its own. The real length only comes back from the model — so the node reads it back and prints each take's actual duration on the node panel. Expect output shorter than requested.
Lyric length rule: roughly 7 seconds per line. A live 建议歌词 ≤ N 行 hint is drawn under the duration slider. Lyrics longer than the budget get truncated at the end.
| Control | Notes |
|---|---|
模式 | 文生音乐 (text-to-music) or 翻唱 (cover: transcribe a reference song's melody, then re-sing it with new style/lyrics) |
歌曲描述 | One line. Used when AI 写词 is on and style/lyrics are empty |
时长(秒) | 30–300 upper bound |
版本数 | 1–4 takes, seeds base + i × 7919 |
Style selectors (plain backend COMBO inputs — dropdowns, no frontend code): 语言 / 人声 / 曲风 / BPM / 乐器1-3 / 制作质感. They are composed server-side into the style string with the same formula as YuE Studio:
语言 + 人声 + 曲风 + BPM + 乐器 + 制作质感
→ Chinese, husky male vocal, folk, 78 BPM, fingerstyle acoustic guitar, harmonica, warm analog production
风格提示词 is a manual override — fill it and it wins over the selectors. 歌词 uses [Verse]/[Chorus] tags; leave it empty with AI 写词 on and the model writes it.
Resolution order: manual 风格提示词 > AI 写词 > the selectors.
Remaining inputs: AI 写词 (local llama.cpp + GGUF), 写词模型, 参考音频, 模型, YuE2 LoRA (applied to both MODEL and CLIP — style/melody tokens come from the CLIP half), 输出格式, 音色转换 (Demucs + Seed-VC) with 移调/转换步数, 识别歌词文本 (Qwen3-ASR).
Sampling parameters (steps 32 / CFG 1.0 / dpm_2 / sgm_uniform) are fixed to the values this pipeline is known to work with and are deliberately not exposed — CFG especially, since YuE2 does its CFG inside the text encoder.
This node is backend-only: no frontend JS.
Outputs land in output/yue/<timestamp>/: one FLAC per take (true length, never padded), plus mp3/, vc/, meta.json, lyrics.txt.
When AI 写词 or 音色转换 are enabled, the node serializes GPU use: the helper engine runs entirely before YuE2 loads or entirely after it unloads. Two GPU consumers are never resident at once.
⚠️ Machine-specific absolute paths. The external engines are referenced by absolute path and must be edited at the top of
nodes/zoey_yue2_studio.pyif they move: llama.cpp (LLAMA_SERVER, plusCUDA_BIN— without it onPATH, llama.cpp silently falls back to CPU, 10× slower with no error), ASR (ASR_PYTHON/ASR_SCRIPT/ASR_MODEL_ROOT), voice conversion (VC_PYTHON/VC_SCRIPT/SEEDVC_DIR).
⚠️ Caching. Like the rest of this pack, the node defines no
IS_CHANGED. Withseedoncontrol_after_generate(the default) pressing Run again regenerates; but if you pin the seed, ComfyUI returns cached audio and silently skips the AI-writing and voice-conversion subprocesses. Bump the seed, or change any input, to force a real re-run.
Wraps the official MiniMaxH3ReferenceToVideo (text + image/video/audio references → video). Type @ in the prompt to open a media picker with thumbnails; hover any @ thumbnail for a large preview.
@ Reference tags — auto-expand to native <Picture N>/<Video N>/<Audio N>:
| Tag | Meaning |
|---|---|
@P1 | 1st connected reference image |
@V1 | 1st connected reference video |
@A1 | 1st connected reference audio |
@C1 | storyboard character slot (director mode) |
@L1 | global asset library entry |
🧰 Global Asset Library (permanent, cross-workflow): the 素材库 widget on the node lets you upload local images (character/prop/scene) and audio files to disk (input/zoey_library/). Characters support an appearance note and an optional voice audio. Reference any saved entry with @L1…; the node auto-loads the file and injects it into generation (no LoadImage node needed), and auto-writes purpose annotations such as <Picture K> 是{name}的人物参考（锁定脸和服装）。外貌：…，音色参考 <Audio N>.
🎬 Director panel (故事板/分镜): enable director_mode to build multi-shot storyboards instead of a single prompt. Per shot:
(S1) says: <d>[lang] text</d>; global speaker list for voice descriptions@C (assign a reference image → auto <Picture K> 是{name}的人物参考（锁定脸和服装） declaration)overall_soundscape / non_diegetic_music), cross-shot consistency toggle, and a live compiled-prompt preview| Package | Required | Notes |
|---|---|---|
| torch, Pillow, numpy | Yes | Core |
| opencv-python-headless | Yes | Image/video ops |
| transformers | For Hunyuan | Translator model |
| rembg | Optional | Mask node BG removal |
| av / PyAV | Optional | Video processor |
| psutil | Optional | System monitor node |
MIT
ComfyUI 多功能工具插件，提供图像/视频处理、翻译、提示词生成等实用节点。
cd ComfyUI/custom_nodes
git clone https://github.com/liangzoey/comfyui-ZoeyTool.git
cd comfyui-ZoeyTool
pip install -r requirements.txt
| 节点 | 功能 |
|---|---|
| 真尺寸图像加载器 | 批量逐张加载文件夹中的图像，保持原始尺寸，自然排序，输出 Alpha 通道作为遮罩 |
| 智能图像存储器 | 批量保存图像 + 文本文件，自定义序号位数、起始索引、覆盖模式 |
| 遮罩边界框绘制 | 根据遮罩绘制矩形框，弹出调色板选色，透明度/填充/线宽调节，预设配色、灯光类型与提示词输出、主体后合成，可选 rembg 背景移除 |
| 图像批量裁剪器 | 批量裁剪图片（左/右/上/下自由裁剪），覆盖模式，保留原文件名 |
| 灯光手柄控制 | 交互式灯光方向控制，拖拽手柄生成圆形渐变遮罩与灯光提示词（16 种灯光类型），支持主体后合成、多种手柄形状 |
| 文本叠加 | 在图像上叠加文字，支持自定义或系统字体，可调字号、颜色、位置 |
| 多功能图像编辑器 | 翻转、旋转、分割、边缘检测、模糊、锐化、二值化、颜色反转、灰度化、透视变换、融合、风格化 |
| 图像编辑提示词生成器 | 自动生成编辑提示词，支持文字/对象/风格/背景编辑、虚拟试穿、对象添加/移除 |
| 框选裁剪/外扩 | 交互式框选裁剪与画布外扩，实时预览，自定义填充色 |
| 多功能画布 | 5 层图像叠加合成，拖拽移动、滚轮缩放、旋转手柄、水平/垂直翻转 |
| 节点 | 功能 |
|---|---|
| 批量视频加载器 | 从目录加载视频文件列表，支持多格式（mp4/avi/mov），自然排序 |
| 视频批处理器 | 批量处理视频（格式转换、帧率调整），自动安装依赖，跳过已处理文件 |
| 智能视频存储器 | 保存处理后视频，支持按日期分类、元数据写入 |
| 节点 | 功能 |
|---|---|
| 纯净翻译器 | 多引擎翻译：Helsinki-NLP 内置模型 / 百度API / 谷歌API，支持中/英/日/韩 |
| 混元翻译器 (HY-MT1.5) | 腾讯混元翻译模型本地部署，20+ 语言，自动下载缓存，术语干预和上下文翻译 |
| Wan2.2提示词生成器 | 影视级视频提示词生成，16 个控制维度：主体、场景、动作、光源、构图、镜头、风格 |
| 节点 | 功能 |
|---|---|
| 多文件批量重命名 | 批量重命名文件，正则查找替换，自然排序，自定义起始序号 |
| ZOEYTextEncodeQwenImageEditPlus | Qwen 图像编辑编码器，支持多张参考图 |
| VR 360° 预览 | 360° 全景图 VR 预览，基于 Pannellum 全屏查看器 |
| 系统监控 | 实时监控 CPU/内存/显存/GPU 温度与利用率，内置 HTTP 看板，后台自动清理显存 |
| MiniMax H3 参考转视频 (@) | 包装官方 MiniMaxH3ReferenceToVideo，支持 Seedance 风格 @P1/@V1/@A1/@C1/@L1 引用语法自动展开为原生标签，附带导演台分镜面板与永久全局素材库 |
| 音乐生成 (YuE2) | 把整条 YuE2 管线压进一个节点：文生音乐、翻唱（参考曲→旋律→重唱）、AI 写词、音色转换、LoRA。填一句描述、拖一下时长、按运行 |
一个节点顶掉原本 8 个节点的连线图。检查点加载、ABC 写谱、音乐 token 生成、采样、解码、保存全部在一个 execute() 里完成，不需要连任何线。
时长是诚实的。 「时长(秒)」是上限而不是承诺。YuE2 内部先把它换算成 token 预算（25 token/秒），风格或歌词太长时这个预算会被静默压小，模型自己也可能提前收尾。真实长度只有模型知道——所以节点会把它读回来，在节点面板上打印每一版的实际时长。成品通常比设定值短，属正常。
歌词长度经验值：约 7 秒/行。时长滑块下方会实时显示「建议歌词 ≤ N 行」。超出预算的歌词，结尾会被截断。
| 控件 | 说明 |
|---|---|
模式 | 文生音乐 / 翻唱（翻唱=先转写参考曲的旋律，再用新的风格和歌词重唱） |
歌曲描述 | 一句话。开启 AI 写词 且风格/歌词为空时用它 |
时长(秒) | 30–300，是上限 |
版本数 | 1–4 版，种子为 基准 + i × 7919 |
风格选择器（后端 COMBO，就是下拉框，不需要任何前端代码）：语言 / 人声 / 曲风 / BPM / 乐器1-3 / 制作质感。节点内部按和 YuE Studio 一样的公式拼成风格串：
语言 + 人声 + 曲风 + BPM + 乐器 + 制作质感
→ Chinese, husky male vocal, folk, 78 BPM, fingerstyle acoustic guitar, harmonica, warm analog production
风格提示词 是手填覆盖项——填了就以它为准。歌词 用 [Verse]/[Chorus] 分段；开 AI 写词 且歌词留空时由模型写。
优先级：手填 风格提示词 > AI 写词 > 选择器拼串。
其余输入：AI 写词（本地 llama.cpp + GGUF）、写词模型、参考音频、模型、YuE2 LoRA（同时作用于 MODEL 和 CLIP——曲风/旋律 token 是 CLIP 那半边产生的）、输出格式、音色转换（Demucs + Seed-VC）含 移调/转换步数、识别歌词文本（Qwen3-ASR）。
采样参数（步数 32 / CFG 1.0 / dpm_2 / sgm_uniform）固定成这条管线验证过的那套，刻意不暴露——尤其 CFG，YuE2 的 CFG 是在文本编码器内部做的，这里改大只会炸。
本节点是纯后端：没有前端 JS。
产物落在 output/yue/<时间戳>/：每版一个 FLAC（真实长度，不做补零），另有 mp3/、vc/、meta.json、lyrics.txt。
开了 AI 写词或音色转换时，节点会把显存使用串行化：辅助引擎要么全在 YuE2 加载之前跑完，要么全在 YuE2 卸载之后跑。任何时刻都不会有两个 GPU 消费者同时驻留。
⚠️ 绝对路径与本机绑定。 外部引擎按绝对路径调用，换位置需要改
nodes/zoey_yue2_studio.py顶部的常量：llama.cpp（LLAMA_SERVER，以及CUDA_BIN——这个目录不上PATH，llama.cpp 会静默回落 CPU，慢 10 倍且不报错）、ASR（ASR_PYTHON/ASR_SCRIPT/ASR_MODEL_ROOT）、变声（VC_PYTHON/VC_SCRIPT/SEEDVC_DIR）。
⚠️ 缓存。 和本仓库其它节点一样，本节点不定义
IS_CHANGED。随机种子默认是control_after_generate，重按运行会重新生成；但如果你把种子固定住，ComfyUI 会直接返回缓存音频，并静默跳过 AI 写词与变声子进程。改一下种子或任意输入即可强制重跑。
包装官方 MiniMaxH3ReferenceToVideo（文字 + 图片/视频/音频参考 → 视频）。提示词里输入 @ 弹出带缩略图的素材选择器；鼠标悬停任意 @ 缩略图可看大图。
@ 引用标签 —— 自动展开为原生 <Picture N>/<Video N>/<Audio N>：
| 标签 | 含义 |
|---|---|
@P1 | 第 1 张已连接的参考图 |
@V1 | 第 1 段已连接的参考视频 |
@A1 | 第 1 段已连接的参考音频 |
@C1 | 导演台角色槽（导演模式） |
@L1 | 全局素材库条目 |
🧰 永久全局素材库（跨工作流）：节点上的「素材库」控件可本地上传图片（角色/道具/场景）与音频文件到磁盘（input/zoey_library/）。角色支持外貌备注与可选语音音频。提示词里用 @L1… 调用，节点自动加载文件并注入生成（无需再连 LoadImage 节点），并自动补用途标注，如 <Picture K> 是{name}的人物参考（锁定脸和服装）。外貌：…，音色参考 <Audio N>。
🎬 导演台（分镜/故事板）：开启 director_mode 用多镜头分镜替代单条提示词。每镜支持：
(S1) says: <d>[语言] 原文</d>；全局说话人列表写音色描述@C（分配参考图 → 自动生成 <Picture K> 是{name}的人物参考（锁定脸和服装） 声明）overall_soundscape / non_diegetic_music）、跨镜一致开关、实时编译预览| 包 | 必需 | 说明 |
|---|---|---|
| torch, Pillow, numpy | 是 | 核心 |
| opencv-python-headless | 是 | 图像/视频处理 |
| transformers | 混元翻译器 | 翻译模型 |
| rembg | 可选 | 遮罩节点背景移除 |
| av / PyAV | 可选 | 视频处理器 |
| psutil | 可选 | 系统监控节点 |
MIT
Multi-functional ComfyUI custom nodes plugin for image/video processing, translation, prompt generation, and more.
cd ComfyUI/custom_nodes
git clone https://github.com/liangzoey/comfyui-ZoeyTool.git
cd comfyui-ZoeyTool
pip install -r requirements.txt
| Node | Description |
|---|---|
| True Size Image Loader | Load images from folder at original resolution, sequential batch output, natural sorting, alpha channel as mask output |
| Batch Image Saver | Save images + text files in batch with custom index, digit count, overwrite mode |
| Mask Bounding Box Drawer | Draw bounding boxes from mask with HTML5 color picker, opacity/fill/width controls, preset colors, light type + prompt output, behind-subject compositing, optional rembg background removal |
| Batch Image Cropper | Batch crop images (left/right/top/bottom), overwrite mode, filename preservation |
| Light Handle Control | Interactive lighting direction with draggable handle, circular gradient mask, lighting prompt output (16 light types), behind-subject compositing, multiple handle shapes |
| Text Overlay | Overlay text on images with custom or system fonts, adjustable size/color/position |
| Multi-function Image Editor | Flip, rotate, split, edge detect, blur, sharpen, threshold, color invert, grayscale, perspective warp, blend, stylize |
| Image Edit Prompt Generator | Auto-generate edit prompts for text/object/style/background editing, virtual try-on, object add/remove |
| Frame Crop/Outpaint | Interactive frame-based cropping and outpainting with fill color, real-time canvas preview |
| Multi-layer Canvas | 5-layer image compositing with drag reposition, scroll scale, rotation handle, and horizontal/vertical flip |
| Node | Description |
|---|---|
| Batch Video Loader | Load video file list from directory, multi-format (mp4/avi/mov), natural sort, limit control |
| Video Batch Processor | Batch process videos (format, frame rate), auto-install dependencies, skip existing |
| Smart Video Saver | Save processed videos with date folders and metadata |
| Node | Description |
|---|---|
| Pure Translator | Multi-engine translation: Helsinki-NLP models / Baidu API / Google API. Supports ZH/EN/JA/KO |
| Hunyuan Translator (HY-MT1.5) | Tencent Hunyuan MT local deployment, 20+ languages, auto-download model cache, terminology & context support |
| Wan2.2 Prompt Generator | Cinematic video prompt generator with 16 control dimensions: subject, scene, action, lighting, composition, lens, style |
| Node | Description |
|---|---|
| Multi File Batch Renamer | Batch rename files with regex find/replace, natural sort, custom start index |
| ZOEYTextEncodeQwenImageEditPlus | Qwen image edit encoder with multi-reference images for Qwen2-VL |
| VR 360° Preview | 360° equirectangular panorama VR viewer powered by Pannellum |
| System Monitor | Live CPU/RAM/VRAM/GPU temperature & utilization dashboard via embedded HTTP server, with background VRAM auto-cleanup |
| MiniMax H3 Reference-to-Video (@) | Wraps official MiniMaxH3ReferenceToVideo with Seedance-style @ reference tags (@P1/@V1/@A1/@C1/@L1) auto-expanded to native tags, plus a storyboard director panel and a permanent global asset library |
| Music Generation (YuE2) | Whole YuE2 pipeline in ONE node: text-to-music, cover (reference song → melody → re-sing), AI lyric writing, voice conversion, LoRA. Type a one-line description, set a duration slider, press Run |
One node replaces an 8-node graph. Everything — checkpoint loading, ABC scoring, music-token generation, sampling, decoding, saving — happens inside a single execute(); no wiring required.
The duration control is honest. 时长(秒) is an upper bound, not a promise. Internally YuE2 turns it into a token budget (25 tokens/second), then silently shrinks that budget if your style/lyrics are long, and may finish early on its own. The real length only comes back from the model — so the node reads it back and prints each take's actual duration on the node panel. Expect output shorter than requested.
Lyric length rule: roughly 7 seconds per line. A live 建议歌词 ≤ N 行 hint is drawn under the duration slider. Lyrics longer than the budget get truncated at the end.
| Control | Notes |
|---|---|
模式 | 文生音乐 (text-to-music) or 翻唱 (cover: transcribe a reference song's melody, then re-sing it with new style/lyrics) |
歌曲描述 | One line. Used when AI 写词 is on and style/lyrics are empty |
时长(秒) | 30–300 upper bound |
版本数 | 1–4 takes, seeds base + i × 7919 |
Style selectors (plain backend COMBO inputs — dropdowns, no frontend code): 语言 / 人声 / 曲风 / BPM / 乐器1-3 / 制作质感. They are composed server-side into the style string with the same formula as YuE Studio:
语言 + 人声 + 曲风 + BPM + 乐器 + 制作质感
→ Chinese, husky male vocal, folk, 78 BPM, fingerstyle acoustic guitar, harmonica, warm analog production
风格提示词 is a manual override — fill it and it wins over the selectors. 歌词 uses [Verse]/[Chorus] tags; leave it empty with AI 写词 on and the model writes it.
Resolution order: manual 风格提示词 > AI 写词 > the selectors.
Remaining inputs: AI 写词 (local llama.cpp + GGUF), 写词模型, 参考音频, 模型, YuE2 LoRA (applied to both MODEL and CLIP — style/melody tokens come from the CLIP half), 输出格式, 音色转换 (Demucs + Seed-VC) with 移调/转换步数, 识别歌词文本 (Qwen3-ASR).
Sampling parameters (steps 32 / CFG 1.0 / dpm_2 / sgm_uniform) are fixed to the values this pipeline is known to work with and are deliberately not exposed — CFG especially, since YuE2 does its CFG inside the text encoder.
This node is backend-only: no frontend JS.
Outputs land in output/yue/<timestamp>/: one FLAC per take (true length, never padded), plus mp3/, vc/, meta.json, lyrics.txt.
When AI 写词 or 音色转换 are enabled, the node serializes GPU use: the helper engine runs entirely before YuE2 loads or entirely after it unloads. Two GPU consumers are never resident at once.
⚠️ Machine-specific absolute paths. The external engines are referenced by absolute path and must be edited at the top of
nodes/zoey_yue2_studio.pyif they move: llama.cpp (LLAMA_SERVER, plusCUDA_BIN— without it onPATH, llama.cpp silently falls back to CPU, 10× slower with no error), ASR (ASR_PYTHON/ASR_SCRIPT/ASR_MODEL_ROOT), voice conversion (VC_PYTHON/VC_SCRIPT/SEEDVC_DIR).
⚠️ Caching. Like the rest of this pack, the node defines no
IS_CHANGED. Withseedoncontrol_after_generate(the default) pressing Run again regenerates; but if you pin the seed, ComfyUI returns cached audio and silently skips the AI-writing and voice-conversion subprocesses. Bump the seed, or change any input, to force a real re-run.
Wraps the official MiniMaxH3ReferenceToVideo (text + image/video/audio references → video). Type @ in the prompt to open a media picker with thumbnails; hover any @ thumbnail for a large preview.
@ Reference tags — auto-expand to native <Picture N>/<Video N>/<Audio N>:
| Tag | Meaning |
|---|---|
@P1 | 1st connected reference image |
@V1 | 1st connected reference video |
@A1 | 1st connected reference audio |
@C1 | storyboard character slot (director mode) |
@L1 | global asset library entry |
🧰 Global Asset Library (permanent, cross-workflow): the 素材库 widget on the node lets you upload local images (character/prop/scene) and audio files to disk (input/zoey_library/). Characters support an appearance note and an optional voice audio. Reference any saved entry with @L1…; the node auto-loads the file and injects it into generation (no LoadImage node needed), and auto-writes purpose annotations such as <Picture K> 是{name}的人物参考（锁定脸和服装）。外貌：…，音色参考 <Audio N>.
🎬 Director panel (故事板/分镜): enable director_mode to build multi-shot storyboards instead of a single prompt. Per shot:
(S1) says: <d>[lang] text</d>; global speaker list for voice descriptions@C (assign a reference image → auto <Picture K> 是{name}的人物参考（锁定脸和服装） declaration)overall_soundscape / non_diegetic_music), cross-shot consistency toggle, and a live compiled-prompt preview| Package | Required | Notes |
|---|---|---|
| torch, Pillow, numpy | Yes | Core |
| opencv-python-headless | Yes | Image/video ops |
| transformers | For Hunyuan | Translator model |
| rembg | Optional | Mask node BG removal |
| av / PyAV | Optional | Video processor |
| psutil | Optional | System monitor node |
MIT
ComfyUI 多功能工具插件，提供图像/视频处理、翻译、提示词生成等实用节点。
cd ComfyUI/custom_nodes
git clone https://github.com/liangzoey/comfyui-ZoeyTool.git
cd comfyui-ZoeyTool
pip install -r requirements.txt
| 节点 | 功能 |
|---|---|
| 真尺寸图像加载器 | 批量逐张加载文件夹中的图像，保持原始尺寸，自然排序，输出 Alpha 通道作为遮罩 |
| 智能图像存储器 | 批量保存图像 + 文本文件，自定义序号位数、起始索引、覆盖模式 |
| 遮罩边界框绘制 | 根据遮罩绘制矩形框，弹出调色板选色，透明度/填充/线宽调节，预设配色、灯光类型与提示词输出、主体后合成，可选 rembg 背景移除 |
| 图像批量裁剪器 | 批量裁剪图片（左/右/上/下自由裁剪），覆盖模式，保留原文件名 |
| 灯光手柄控制 | 交互式灯光方向控制，拖拽手柄生成圆形渐变遮罩与灯光提示词（16 种灯光类型），支持主体后合成、多种手柄形状 |
| 文本叠加 | 在图像上叠加文字，支持自定义或系统字体，可调字号、颜色、位置 |
| 多功能图像编辑器 | 翻转、旋转、分割、边缘检测、模糊、锐化、二值化、颜色反转、灰度化、透视变换、融合、风格化 |
| 图像编辑提示词生成器 | 自动生成编辑提示词，支持文字/对象/风格/背景编辑、虚拟试穿、对象添加/移除 |
| 框选裁剪/外扩 | 交互式框选裁剪与画布外扩，实时预览，自定义填充色 |
| 多功能画布 | 5 层图像叠加合成，拖拽移动、滚轮缩放、旋转手柄、水平/垂直翻转 |
| 节点 | 功能 |
|---|---|
| 批量视频加载器 | 从目录加载视频文件列表，支持多格式（mp4/avi/mov），自然排序 |
| 视频批处理器 | 批量处理视频（格式转换、帧率调整），自动安装依赖，跳过已处理文件 |
| 智能视频存储器 | 保存处理后视频，支持按日期分类、元数据写入 |
| 节点 | 功能 |
|---|---|
| 纯净翻译器 | 多引擎翻译：Helsinki-NLP 内置模型 / 百度API / 谷歌API，支持中/英/日/韩 |
| 混元翻译器 (HY-MT1.5) | 腾讯混元翻译模型本地部署，20+ 语言，自动下载缓存，术语干预和上下文翻译 |
| Wan2.2提示词生成器 | 影视级视频提示词生成，16 个控制维度：主体、场景、动作、光源、构图、镜头、风格 |
| 节点 | 功能 |
|---|---|
| 多文件批量重命名 | 批量重命名文件，正则查找替换，自然排序，自定义起始序号 |
| ZOEYTextEncodeQwenImageEditPlus | Qwen 图像编辑编码器，支持多张参考图 |
| VR 360° 预览 | 360° 全景图 VR 预览，基于 Pannellum 全屏查看器 |
| 系统监控 | 实时监控 CPU/内存/显存/GPU 温度与利用率，内置 HTTP 看板，后台自动清理显存 |
| MiniMax H3 参考转视频 (@) | 包装官方 MiniMaxH3ReferenceToVideo，支持 Seedance 风格 @P1/@V1/@A1/@C1/@L1 引用语法自动展开为原生标签，附带导演台分镜面板与永久全局素材库 |
| 音乐生成 (YuE2) | 把整条 YuE2 管线压进一个节点：文生音乐、翻唱（参考曲→旋律→重唱）、AI 写词、音色转换、LoRA。填一句描述、拖一下时长、按运行 |
一个节点顶掉原本 8 个节点的连线图。检查点加载、ABC 写谱、音乐 token 生成、采样、解码、保存全部在一个 execute() 里完成，不需要连任何线。
时长是诚实的。 「时长(秒)」是上限而不是承诺。YuE2 内部先把它换算成 token 预算（25 token/秒），风格或歌词太长时这个预算会被静默压小，模型自己也可能提前收尾。真实长度只有模型知道——所以节点会把它读回来，在节点面板上打印每一版的实际时长。成品通常比设定值短，属正常。
歌词长度经验值：约 7 秒/行。时长滑块下方会实时显示「建议歌词 ≤ N 行」。超出预算的歌词，结尾会被截断。
| 控件 | 说明 |
|---|---|
模式 | 文生音乐 / 翻唱（翻唱=先转写参考曲的旋律，再用新的风格和歌词重唱） |
歌曲描述 | 一句话。开启 AI 写词 且风格/歌词为空时用它 |
时长(秒) | 30–300，是上限 |
版本数 | 1–4 版，种子为 基准 + i × 7919 |
风格选择器（后端 COMBO，就是下拉框，不需要任何前端代码）：语言 / 人声 / 曲风 / BPM / 乐器1-3 / 制作质感。节点内部按和 YuE Studio 一样的公式拼成风格串：
语言 + 人声 + 曲风 + BPM + 乐器 + 制作质感
→ Chinese, husky male vocal, folk, 78 BPM, fingerstyle acoustic guitar, harmonica, warm analog production
风格提示词 是手填覆盖项——填了就以它为准。歌词 用 [Verse]/[Chorus] 分段；开 AI 写词 且歌词留空时由模型写。
优先级：手填 风格提示词 > AI 写词 > 选择器拼串。
其余输入：AI 写词（本地 llama.cpp + GGUF）、写词模型、参考音频、模型、YuE2 LoRA（同时作用于 MODEL 和 CLIP——曲风/旋律 token 是 CLIP 那半边产生的）、输出格式、音色转换（Demucs + Seed-VC）含 移调/转换步数、识别歌词文本（Qwen3-ASR）。
采样参数（步数 32 / CFG 1.0 / dpm_2 / sgm_uniform）固定成这条管线验证过的那套，刻意不暴露——尤其 CFG，YuE2 的 CFG 是在文本编码器内部做的，这里改大只会炸。
本节点是纯后端：没有前端 JS。
产物落在 output/yue/<时间戳>/：每版一个 FLAC（真实长度，不做补零），另有 mp3/、vc/、meta.json、lyrics.txt。
开了 AI 写词或音色转换时，节点会把显存使用串行化：辅助引擎要么全在 YuE2 加载之前跑完，要么全在 YuE2 卸载之后跑。任何时刻都不会有两个 GPU 消费者同时驻留。
⚠️ 绝对路径与本机绑定。 外部引擎按绝对路径调用，换位置需要改
nodes/zoey_yue2_studio.py顶部的常量：llama.cpp（LLAMA_SERVER，以及CUDA_BIN——这个目录不上PATH，llama.cpp 会静默回落 CPU，慢 10 倍且不报错）、ASR（ASR_PYTHON/ASR_SCRIPT/ASR_MODEL_ROOT）、变声（VC_PYTHON/VC_SCRIPT/SEEDVC_DIR）。
⚠️ 缓存。 和本仓库其它节点一样，本节点不定义
IS_CHANGED。随机种子默认是control_after_generate，重按运行会重新生成；但如果你把种子固定住，ComfyUI 会直接返回缓存音频，并静默跳过 AI 写词与变声子进程。改一下种子或任意输入即可强制重跑。
包装官方 MiniMaxH3ReferenceToVideo（文字 + 图片/视频/音频参考 → 视频）。提示词里输入 @ 弹出带缩略图的素材选择器；鼠标悬停任意 @ 缩略图可看大图。
@ 引用标签 —— 自动展开为原生 <Picture N>/<Video N>/<Audio N>：
| 标签 | 含义 |
|---|---|
@P1 | 第 1 张已连接的参考图 |
@V1 | 第 1 段已连接的参考视频 |
@A1 | 第 1 段已连接的参考音频 |
@C1 | 导演台角色槽（导演模式） |
@L1 | 全局素材库条目 |
🧰 永久全局素材库（跨工作流）：节点上的「素材库」控件可本地上传图片（角色/道具/场景）与音频文件到磁盘（input/zoey_library/）。角色支持外貌备注与可选语音音频。提示词里用 @L1… 调用，节点自动加载文件并注入生成（无需再连 LoadImage 节点），并自动补用途标注，如 <Picture K> 是{name}的人物参考（锁定脸和服装）。外貌：…，音色参考 <Audio N>。
🎬 导演台（分镜/故事板）：开启 director_mode 用多镜头分镜替代单条提示词。每镜支持：
(S1) says: <d>[语言] 原文</d>；全局说话人列表写音色描述@C（分配参考图 → 自动生成 <Picture K> 是{name}的人物参考（锁定脸和服装） 声明）overall_soundscape / non_diegetic_music）、跨镜一致开关、实时编译预览| 包 | 必需 | 说明 |
|---|---|---|
| torch, Pillow, numpy | 是 | 核心 |
| opencv-python-headless | 是 | 图像/视频处理 |
| transformers | 混元翻译器 | 翻译模型 |
| rembg | 可选 | 遮罩节点背景移除 |
| av / PyAV | 可选 | 视频处理器 |
| psutil | 可选 | 系统监控节点 |
MIT