Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > comfyui-ZoeyTool

ComfyUI Extension: comfyui-ZoeyTool

Repo Name

comfyui-ZoeyTool

Author
liangzoey (Account age: 0 days)
Nodes
View all nodes(1)
Latest Updated
2026-11-10
Github Stars
0.01K

How to Install comfyui-ZoeyTool

Install this extension via the ComfyUI Manager by searching for comfyui-ZoeyTool
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter comfyui-ZoeyTool in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

comfyui-ZoeyTool Description

comfyui-ZoeyTool adds ComfyUI nodes for batch image and video editing, translation, prompt writing, reference-guided video and character replacement, music generation, and system monitoring.

comfyui-ZoeyTool Introduction

comfyui-ZoeyTool is a collection of custom nodes for ComfyUI. It brings image editing, video processing, translation, prompt writing, music generation, and system monitoring into your workflows.

You can use individual nodes for small tasks, such as placing text on an image or translating a prompt. You can also combine them into longer workflows: load a folder of images, edit them, and save the results; or load several videos, process them, and organize the outputs. Some more involved tasks, including YuE2 music generation and MiniMax H3 character replacement, are packaged into single nodes so you have fewer connections to manage.

The extension is especially useful when you want to:

  • Prepare or edit images without leaving ComfyUI.
  • Apply the same operation to many images or videos.
  • Turn creative choices, such as lighting direction or camera movement, into prompts.
  • Keep reference characters and other assets available across video workflows.
  • Generate music or make targeted changes to a video while retaining its surrounding scene.

How comfyui-ZoeyTool Works

A ComfyUI workflow is a set of connected nodes. Each node receives something, performs a task, and passes a result onward. Think of it as an assembly line: one node loads an image, another crops it, and a third saves it.

ZoeyTool's nodes work in several ways:

  • Direct editing: An image node changes pixels, such as by cropping, blurring, or adding text.
  • Guided editing: A control produces a mask or prompt for another part of your workflow. For example, the Light Handle Control lets you drag a handle to indicate where light should come from.
  • Batch processing: A node applies an operation to multiple files, helping you avoid repeating the same steps by hand.
  • Model-assisted generation: Nodes such as YuE2 Music Generation and MiniMax H3 Reference-to-Video use specialized models for audio or video tasks. Their inputs describe the result you want; the model generates the output.

A mask is a guide that identifies the part of an image or video to work on. In character replacement, for example, the mask marks the tracked subject so the model can repaint that region while leaving other areas alone. A reference image is a visual example you provide to guide the appearance of a generated character or scene.

comfyui-ZoeyTool Features

Image Processing

NodeWhat you can do
True Size Image LoaderLoad images from a folder at their original resolution. Files are naturally sorted, so numbered names follow a human-readable order. The node can output an image's alpha channel as a mask.
Batch Image SaverSave multiple images and accompanying text files. Set the starting index, the number of digits in filenames, and whether existing files may be overwritten.
Mask Bounding Box DrawerDraw a box around the area identified by a mask. Choose a color, opacity, fill, and line width; use preset colors; or output a lighting prompt. It also supports placing the effect behind a subject and optional background removal with rembg.
Batch Image CropperRemove pixels from the left, right, top, or bottom of multiple images. You can preserve filenames and choose whether to overwrite files.
Light Handle ControlDrag a handle to set a lighting direction. The node produces a circular gradient mask and a corresponding lighting prompt, with 16 light types and several handle shapes. It can composite lighting behind a subject.
Text OverlayPlace text on an image using a system or custom font. Adjust its size, color, and position.
Multi-function Image EditorPerform operations including flipping, rotation, splitting, edge detection, blur, sharpening, thresholding, color inversion, grayscale, perspective warp, blending, and stylization.
Image Edit Prompt GeneratorDraft prompts for tasks such as changing text, objects, style, or background; adding or removing objects; and virtual try-on.
Frame Crop/OutpaintUse an interactive frame and live canvas preview to crop an image or extend its canvas. Choose a fill color for the added area.
Multi-layer CanvasCombine up to five image layers. Drag layers into position, use the scroll wheel to scale them, rotate with a handle, and flip them horizontally or vertically.
Local Detailer (Face/Hand)Detect faces or hands, crop and enlarge each region, refine it with your connected model and VAE, then blend it back with softened edges. An optional mask lets you add regions manually.

For example, you could use True Size Image Loader to bring in a numbered series of artwork, Batch Image Cropper to give every piece the same framing, and Batch Image Saver to export the results with consistent filenames.

Video Processing

NodeWhat you can do
Batch Video LoaderLoad a naturally sorted list of videos from a directory, including MP4, AVI, and MOV files. Set a limit when you only want to process part of the list.
Video Batch ProcessorProcess multiple videos, including format and frame-rate changes. It can skip existing results.
Smart Video SaverSave processed videos in date-based folders with metadata.

Together, these nodes provide a load → process → save workflow for collections of videos.

Translation and Prompt Writing

NodeWhat you can do
Pure TranslatorTranslate between Chinese, English, Japanese, and Korean using a Helsinki-NLP model, Baidu API, or Google API. Choose the engine that suits your workflow.
Hunyuan Translator (HY-MT1.5)Run Tencent Hunyuan MT locally for translation across more than 20 languages. It supports context and terminology guidance and can download models into a cache.
Wan2.2 Prompt GeneratorBuild cinematic video prompts by specifying details such as the subject, scene, action, lighting, composition, lens, and style. It provides 16 control dimensions in total.

If a translation must retain a particular name or creative term, the Hunyuan Translator's terminology support can help you guide that wording. If a video idea feels too vague, the Wan2.2 Prompt Generator helps you describe its visual components more precisely.

File, Preview, and System Tools

  • Multi File Batch Renamer: Rename naturally sorted files using a starting index or find-and-replace rules, including regular expressions.
  • ZOEYTextEncodeQwenImageEditPlus: Encode prompts with multiple reference images for Qwen image editing.
  • VR 360° Preview: View a 360° equirectangular panorama in a VR-style viewer powered by Pannellum.
  • System Monitor: See live CPU, system memory, GPU memory, GPU temperature, and utilization information on a dashboard. It also includes background GPU-memory cleanup.
  • ID Photo Background: Select a red, white, blue, or green background. The node outputs the selected color as text, which you can pass to a prompt or background-replacement node; it does not change the image by itself.

MiniMax H3 Reference-to-Video

MiniMax H3 Reference-to-Video (@) wraps the official MiniMaxH3ReferenceToVideo node. It uses a text prompt together with connected image, video, or audio references to guide video generation.

Type @ in the prompt to open a media picker with thumbnails. Hover over a thumbnail for a larger preview. Reference tags let you refer to assets without repeatedly writing their full descriptions:

TagRefers to
@P1The first connected reference image
@V1The first connected reference video
@A1The first connected reference audio clip
@C1A character slot in director mode
@L1An entry in the global asset library

The node expands these shortcuts into the reference tags used by MiniMax H3.

The global asset library stores uploaded character, prop, and scene images, as well as audio, in input/zoey_library/. Assets remain available across workflows. You can add an appearance note and optional voice audio to a character, then refer to a saved asset with an @L tag instead of connecting another image loader.

Enable director_mode when you want a multi-shot storyboard rather than one prompt. For each shot, you can set camera movement and shot size, add dialogue with speakers S1–S5, assign character references, choose transitions, and set duration. The panel can allocate time based on dialogue length and shows a live preview of the compiled prompt. It also includes shot templates, sound and music fields, and a cross-shot consistency option.

MiniMax H3 Mask Character Replace

ZoeyTool provides a MiniMax H3 Mask Character Replace (SAM3) node and a mask replacement mode within the Reference-to-Video node. Both are described as workflows for identifying a subject in source frames and repainting the masked region with H3 while retaining the surrounding scene. The source audio can be preserved.

A typical workflow in the dedicated node is:

  1. Connect source video frames as an IMAGE batch, and connect source audio if you have it.
  2. Connect the replacement character image to ref_image_0. In the prompt, you can refer to it as @P1 or <Picture 1>.
  3. Enter an English noun phrase in seg_prompt, such as person, woman, or red car, to tell SAM3.1 what to track.
  4. Use max_objects and object_indices to select the tracked subject. Increase mask_grow to extend the selected area; use mask_feather to soften its edge.
  5. Run the node and inspect its output frames, audio, preview mask, and information text.

You can connect your own mask to bypass SAM3 segmentation. When writing a custom replacement prompt, describe both the replacement character and the source scene. Describing only the character can cause details from the reference image's background to appear inside the repainted area.

The ref_image_size setting offers a speed/detail tradeoff: match is faster, while max can better preserve reference identity but takes substantially longer. Automatic resolution retains the source aspect ratio within the node's canvas limit. The frame count may be adjusted to a length the model accepts.

In the Reference-to-Video node's replacement mode, the corresponding inputs use names such as replace_video, replace_audio, and replace_mask. Its replacement settings appear in a collapsible row.

Music Generation (YuE2)

Music Generation (YuE2) combines text-to-music, cover generation, optional AI lyric writing, voice conversion, and LoRA support in one node. It handles the generation and saving steps internally.

The main controls are:

ControlWhat it changes
模式 (Mode)Choose text-to-music or cover. Cover mode takes a reference song's melody and re-sings it with new style or lyrics.
歌曲描述 (Song description)Supply a one-line idea, particularly useful when AI lyric writing is enabled and style or lyrics are empty.
时长(秒) (Duration)Set an upper bound from 30 to 300 seconds, not a guaranteed output length.
版本数 (Number of takes)Generate one to four versions.
Style selectorsChoose language, vocal character, genre, BPM, up to three instruments, and production character.
风格提示词 (Style prompt)Enter a manual style description that overrides the selector-built style.
歌词 (Lyrics)Provide lyrics, optionally organized with [Verse] and [Chorus] tags. Leave them empty with AI 写词 enabled for generated lyrics.
参考音频 (Reference audio)Provide the song used in cover mode.
音色转换 (Voice conversion)Enable voice conversion, with controls for pitch shift and conversion steps.

For instance, choosing a husky vocal, folk genre, 78 BPM, acoustic guitar, and warm production builds a combined style description. A manually entered style prompt takes priority over that combination.

Plan for a shorter result than the duration setting. YuE2 uses the setting as a generation budget and may end early; long style descriptions or lyrics can reduce the available budget. The node reports each take's actual duration. As a rough guide, allow about seven seconds per lyric line. The node displays a suggested line count, and lyrics beyond the budget may be cut off.

Outputs are organized under output/yue/<timestamp>/. They include a FLAC for each take, alongside output folders and files such as mp3/, vc/, meta.json, and lyrics.txt.

comfyui-ZoeyTool Models

ZoeyTool is a collection of tools, not a single image-generation model. Its model-related nodes serve different creative purposes:

Model or model familyRoleWhen to use it
Helsinki-NLP translation modelsOne engine available in Pure Translator.When you want model-based translation for supported languages.
Tencent Hunyuan MT / HY-MT1.5Local translation with context and terminology support.When translated prompts need more guidance about wording.
Wan2.2The intended video-prompt workflow for the Wan2.2 Prompt Generator.When you want a more structured cinematic prompt.
Qwen2-VLThe reference-image encoding context for ZOEYTextEncodeQwenImageEditPlus.When working with multiple reference images in a Qwen image-edit workflow.
MiniMax H3Reference-guided video generation and masked video re-rendering.When making a reference-based video or replacing a tracked character.
SAM3.1Segments and tracks a prompted subject across video frames.When character replacement needs a mask and you have not supplied one manually.
YuE2Generates music and covers.When you want music from a description or a re-sung reference melody.
GGUF lyric-writing model, via llama.cppWrites lyrics when YuE2's AI lyric option is enabled.When you have a song idea but do not want to supply lyrics yourself.
Qwen3-ASRRecognizes lyric text from audio in the YuE2 workflow.When the lyric-recognition option is needed.
Seed-VCUsed for YuE2 voice conversion.When you want to change the generated vocal character.

The Local Detailer (Face/Hand) uses the MODEL and VAE you connect to it; it is not described as having a separate built-in refinement model.

Troubleshooting comfyui-ZoeyTool

A YuE2 song is shorter than the requested duration

  1. Check the actual duration reported on the node; the duration control is an upper bound.
  2. Shorten long lyrics or the style description if you need more of the budget available for music.
  3. Use the suggested lyric-line count beneath the duration slider as a guide.
  4. Run another take if the model ended early.

Pressing Run returns the same YuE2 audio

  1. Check whether the seed is fixed.
  2. Change the seed or another node input.
  3. Run the workflow again. With an unchanged fixed seed and inputs, ComfyUI may return cached audio without rerunning lyric writing or voice conversion.

YuE2 AI lyric writing is unexpectedly slow

The documented llama.cpp setup depends on machine-specific paths. In particular, if its CUDA binary directory is not available on PATH, llama.cpp can fall back to CPU without reporting an error. The relevant paths are defined near the top of nodes/zoey_yue2_studio.py; correcting them may require help from whoever configured your ComfyUI environment.

Character replacement changes part of the background

  1. Review the output mask to see which area is selected.
  2. Refine seg_prompt and the tracked-object selection if SAM3 chose the wrong subject.
  3. Adjust mask_grow and mask_feather to improve coverage and soften the edge.
  4. In your prompt, describe both the replacement character and the original scene.
  5. For precise control, connect a hand-made or externally generated mask instead of using SAM3.

A video replacement takes longer than expected

Check ref_image_size. The max option favors reference detail but is several times slower than match. Try match when speed is more important, then compare the result.

Frequently Asked Questions

Does ID Photo Background replace an image's background?
No. It outputs the selected background color as text for another prompt or background-replacement node.

Do I need to connect an image loader for every MiniMax H3 library asset?
No. The global asset library can load a saved asset when you reference it with an @L tag.

Can I select a video subject without SAM3?
Yes. Connect a manual or external mask to override SAM3 in the mask replacement workflow.

Can I adjust YuE2's sampling steps or CFG in the node?
No. The documented YuE2 pipeline keeps its sampling settings fixed rather than exposing them as artist-facing controls.

Learn More about comfyui-ZoeyTool

The extension is released under the MIT License.

comfyui-ZoeyTool Related Nodes

RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

comfyui-ZoeyTool detailed guide | ComfyUI