Comfyui-breeze-tts Introduction
Comfyui-breeze-tts adds Breeze TTS 2 speech generation to ComfyUI. You can write dialogue, choose how the voice should sound, and generate audio that you can use alongside your visual workflows. It supports creating a voice from a written description, using a reference recording to preserve a speaker’s voice, and directing how individual lines are delivered.
The extension is an unofficial set of ComfyUI nodes, not a BreezeBlue product. Its current node version is 0.3.7; the separate desktop bundle remains at 0.3.6.
The model is limited to the research, educational, and non-commercial uses permitted by its license. Read MODEL_LICENSE and confirm the license in the model loader before generating audio.
How Comfyui-breeze-tts Works
Think of a workflow as a small recording studio with four steps:
- Load the model. The model loader makes Breeze TTS 2 available to the other nodes.
- Prepare a performance. A voice node combines your dialogue with a voice description, a reference recording, or delivery instructions. It produces a request, not audio yet.
- Choose generation settings. These settings control how the audio is sampled and let you specify a Seed.
- Generate audio. The audio-generation node takes the model, request, and settings and produces a standard ComfyUI
AUDIOoutput.
For example, you could describe a calm narrator and generate an introduction for a video. To keep the sound of a particular speaker, you could instead provide a short reference recording and its exact transcript, then give each line a different delivery instruction.
The extension includes four canvas-ready example workflows in examples/:
| Workflow | Use it for |
|---|---|
voice_design_workflow.json | Creating a voice from a written description |
voice_clone_workflow.json | Using a reference speaker’s voice |
voice_direction_workflow.json | Using a reference voice with delivery directions |
voice_bundle_workflow.json | Using a .t8voice.zip voice bundle exported by the desktop version |
Drag a *_workflow.json file onto the ComfyUI canvas, or open it through Workflow → Open. Files ending in *_api.json are for scripts and the /prompt HTTP API; they are not canvas workflows.
Comfyui-breeze-tts Features
Voice design, cloning, and direction
| Node | What you provide | What it helps you do |
|---|---|---|
T8 模型加载器 (Model Loader) | Model options and license confirmation | Load Breeze TTS 2 for the workflow |
T8 声音设计 (Voice Design) | Dialogue, a voice description, and CFG | Create speech guided by a description of the desired voice |
T8 声音克隆 (Voice Clone) | Dialogue, reference audio, and its exact transcript | Generate new dialogue using the reference speaker’s voice |
T8 声音导演 (Voice Direction) | A reference voice, transcript, and natural-language directions | Guide how a line is delivered while retaining the reference voice |
T8 生成设置 (Generation Settings) | Sampling settings and Seed | Adjust generation behavior |
T8 生成音频 (Generate Audio) | A loaded model, voice request, and settings | Produce ComfyUI audio and generation information |
For cloning and direction, the transcript must accurately match what is spoken in the reference audio. Reference audio is limited to 60 seconds. In the Voice Clone node, leaving the optional instruction blank uses the pure Clone path; filling it in switches to Direction.
A Seed and the sampling settings can affect the result, so the same dialogue and voice instructions may produce a different performance when you change them. Voice descriptions and directions are also prompts rather than guarantees: listen to the generated audio and adjust the wording or settings to suit your scene.
Inline voice events
You can place a voice-event cue directly in the dialogue text field of a Design, Clone, Direction, or Voice Bundle node. No extra node is needed.
| Event | English cue | Chinese cue |
|---|---|---|
| Laugh | (laugh) | [笑] |
| Cough | (cough) | [咳嗽] |
| Clear throat | (clears throat) | [清嗓子] |
| Sigh | (sigh) | [叹气] |
For example: [清嗓子] 接下来宣布今天的安排。 or (sigh) I thought we had more time.
These cues are passed to Breeze TTS 2 as generation prompts. How strongly an event comes through can vary with the dialogue, direction, sampling settings, and Seed. The four canvas workflows include a syntax reminder, and the request nodes show guidance when you hover over them.
Desktop voice bundles and line-by-line expression
The T8 桌面音色包 (Desktop Voice Bundle) node reads a .t8voice.zip voice bundle exported by the desktop version. Give it the bundle’s local absolute path and the dialogue for the current line. It outputs a request for Generate Audio, a standard ComfyUI reference-audio output, and voice information.
The T8 逐句情感 (Line-by-Line Emotion) node lets you adjust one line without changing the request feeding other branches of your workflow. Its modes are:
inherit: Keep the bundle’s existing voice description or direction.override: Replace the default direction for this line. With a cloned voice, the request becomes a Direction request while retaining the same reference speaker.neutral: Use a clear, natural, neutral direction while retaining the reference speaker’s identity.
You can also connect a Design, Clone, or Direction request directly to this node. These controls use natural-language direction, not an eight-dimensional emotion slider.
Voice bundles are treated as untrusted files. The node reads them without extracting their contents to disk and checks their contents, sizes, hashes, and reference-audio duration. For the most reliable decoding across platforms, the author recommends exporting reference audio as WAV or FLAC.
Comfyui-breeze-tts Models
The extension uses BreezeBlue/Breeze-TTS-2. The provided context does not identify separate model choices for voice design, cloning, and direction; these are different ways of making requests to the same model.
On first use, the Model Loader can download the official model at a fixed revision. If you already have the model files, the expected local location is:
ComfyUI/models/breeze_tts/BreezeBlue_Breeze-TTS-2
Before loading, the extension checks the model configuration, tokenizer, codec, weight index, and referenced weight files. If a download was interrupted, enabling download_if_missing allows it to continue. A failed check reports the missing or damaged file and a repair path.
The official runtime uses BF16. The author recommends an NVIDIA Ampere (SM80) or newer GPU. The extension uses the Torch version supplied by ComfyUI rather than installing its own.
What's New with Comfyui-breeze-tts
- Node version 0.3.7: Fixes Issue #2, a CUDA error (
wrapper_CUDA__index_select) that could occur after repeated runs or after GPU memory was unloaded. The fix addresses a mismatch between CPU weights and CUDA inputs in a special text-embedding layer. This release is a node patch; restart ComfyUI after updating the nodes. - Behavior retained from 0.3.5: The Model Loader can automatically recover its cache. The extension retains the official Voice Clone, Voice Design, and Voice Direction request paths, eight combinable nodes, four canvas workflows, and inline voice-event cues.
- Desktop bundle version 0.3.6: The separate desktop bundle remains at this version; the 0.3.7 release does not update it.
No additional version-by-version changes are documented in the provided information.
Troubleshooting Comfyui-breeze-tts
The workflow says reference.wav is missing
This is expected when you first open the Clone or Direction example: the workflow does not include someone else’s reference recording.
- Close the missing-media notice.
- Find the
LoadAudionode. - Select and upload your own reference audio.
- Enter an accurate transcript of everything spoken in that recording.
- Run the workflow again.
Nodes appear red or “missing” after importing a workflow
- Confirm that the node folder is
ComfyUI/custom_nodes/comfyui-breeze-tts-T8. - Restart ComfyUI.
- Import a file ending in
*_workflow.json, not*_api.json.
A voice-bundle workflow cannot find its file
Replace the example path in the Voice Bundle node with the absolute path to a real .t8voice.zip file on the machine running ComfyUI. If the file is rejected, check that it is an intact desktop-exported bundle. For reference-audio compatibility, try a bundle exported with WAV or FLAC audio.
The model does not load
- Read the specific missing-file or damaged-file message shown by the loader.
- If a download was interrupted, set
download_if_missing=trueand try again. - If you placed files manually, check the model location shown above and address the file named in the error.
- Make sure you have read and confirmed the model license in the loader.
Generation stops because an input is invalid
Check the field named in the error. Dialogue and required reference transcripts cannot be empty; temperature and repetition penalty must be positive; and the generation settings must contain the required fields. Clone and Direction requests also need valid ComfyUI audio and an accurate reference transcript.
A CUDA error appears after several runs
Update the nodes to 0.3.7 and restart ComfyUI. This release specifically fixes the documented wrapper_CUDA__index_select error associated with repeated runs or GPU-memory unloading.
Frequently asked questions
Can I use voice cloning without a transcript?
No. Voice Clone and Voice Direction require an accurate, word-for-word transcript of the reference recording.
Can I use a reference recording longer than 60 seconds?
No. The node checks the original recording’s duration before sending it for GPU processing.
Do I need a separate node for a laugh or sigh?
No. Put a supported event cue directly in the dialogue text. The generated effect may vary.
Can I give different lines different directions without changing my original voice request?
Yes. The Line-by-Line Emotion node makes a new request, leaving its upstream request and other branches unchanged.
Can I drag an *_api.json example onto the canvas?
No. Use *_workflow.json for the canvas. The API examples are for scripts or /prompt calls.
Is this an official BreezeBlue extension?
No. It is an unofficial ComfyUI integration. Check THIRD_PARTY_NOTICES.md for attribution and MODEL_LICENSE for model-use terms.
Learn More about Comfyui-breeze-tts
- Comfyui-breeze-tts GitHub repository: Extension source, example workflows, license files, and issue tracking.
- Breeze TTS core project: Background on the underlying project.
- ComfyUI-Breeze-TTS-2: Project credited for portions of the adapted inference path.
For a hands-on starting point, open one of the four examples/*_workflow.json files and follow its on-canvas guidance.
