ComfyUI-Drama3 Introduction
A Drama 3 script with performance directions highlighted, ready to become spoken audio in ComfyUI.
ComfyUI-Drama3 brings Fish Audio Drama 3, a 35-billion-parameter text-to-speech model, into ComfyUI. You can turn a written script into spoken audio, clone a voice from a few seconds of reference speech, and direct a cast of up to 16 speakers within the same script.
Instead of treating your text as a plain narration, you can write performance instructions alongside the dialogue. Directions such as [sighs], [laughs], and [whispering] tell the model how you want a moment to sound.
For AI artists, this makes the extension useful for projects such as:
- Character dialogue: assign different voices to characters in an illustrated story or scene.
- Expressive narration: add emotional delivery, pauses, and whispered passages to a voiceover.
- Voice exploration: let the model invent a voice when you do not have a reference recording.
- Recurring characters: save a prepared voice and reuse it in later workflows without loading the original clip again.
- Longer productions: choose dialogue-generation and speed settings that suit an extended script.
The extension runs natively in ComfyUI on NVIDIA graphics cards with as little as 8 GB of GPU memory, although the model also requires substantial system RAM. An 8 GB graphics card does not mean that the entire model is only 8 GB; see ComfyUI-Drama3 Models for the memory requirements.
Listen to examples · Browse model files · Read the node reference
How ComfyUI-Drama3 Works
Think of the workflow as a small recording studio:
- Your script provides the words and stage directions.
- A reference recording, when supplied, provides an example of the voice and its delivery.
- Speaker labels assign lines to the cast.
- Drama 3 performs the script.
- An audio codec converts the model’s audio representation into sound you can hear.
1. Prepare a voice—or let the model invent one
You have two starting points:
Voice cloning: provide a few seconds of clean speech. The workflow uses that recording as a voice reference.
Text-to-speech without a reference: write your text and let the model create a voice. A speaker without an assigned voice also receives a model-invented voice.
A reference clip influences more than vocal identity. It also influences delivery: a flat, neutral clip can lead to a similarly flat performance. Choose a reference that suits the character and tone you want.
2. Match the reference audio to its transcript
For voice cloning, the model needs both the reference speech and the words spoken in it.
The provided workflow uses Qwen3-ASR to transcribe the clip. “ASR” means automatic speech recognition: it listens to audio and writes down the words. Load Reference Audio cuts at a pause, helping the audio excerpt and its transcript match.
This matters because an incomplete or mismatched transcript can contribute to silent or unfinished takes.
3. Write the performance into the script
You can combine spoken text with speaker labels and natural-language directions:
<|speaker:0|> [whispering] Don't move. I think it heard us.
<|speaker:1|> [laughs] It's only the cat. <whisper>Your face, though.</whisper>
<|speaker:0|> [sighs] Fine. You win.
Here, two characters take turns speaking. The first whispers, the second laughs and whispers only part of a line, and the first finishes with a sigh.
4. Choose how the lines are performed
Drama 3 can generate lines independently or let them hear surrounding dialogue.
Independent lines are useful when keeping voices separate is your priority. Context-aware modes let characters react to previous or surrounding lines, but their voices may drift or blend unless you use voice guidance.
5. Turn the performance into audio
Drama 3 generates an encoded audio representation, and its codec turns that representation into playable sound.
The model uses a mixture of specialized components called experts. The downloadable model variants store these experts differently, changing file size, memory needs, and speed. They are complete versions of the same model—not separate character or style models.
Scope note: Fish Audio’s broader Drama 3 documentation also describes capabilities such as local audio editing, infilling, multi-turn revision, and streaming. The supplied ComfyUI extension documentation does not establish those as available extension features. This README focuses on the documented ComfyUI workflows and controls.
ComfyUI-Drama3 Features
Voice cloning from short reference audio
Use Load Reference Audio to provide a clean speech clip for the voice-cloning workflow.
For a more dependable reference:
- Use clearly audible speech.
- Choose an excerpt cut between sentences rather than through a word.
- Make sure the transcript covers every spoken word.
- Consider whether the reference delivery matches your intended performance.
For example, a calm reference may suit a restrained narrator, while a more expressive reference may be a better starting point for an animated character.
Voice generation without a reference
You do not need a voice clip for every project. The text-to-speech example workflow lets the model invent a voice.
This is useful when you want to explore a character’s sound before choosing or preparing a reference recording.
Save and reuse voices
Save Drama 3 Voice stores an encoded voice as a small file of a few KB in:
output/drama3_voices
Load Drama 3 Voice brings it back without requiring the original clip.
In the provided voice-cloning workflow, unmute Save Drama 3 Voice when you want to keep the prepared voice. This gives you a reusable voice reference for recurring characters.
Up to 16 speakers in one script
Speaker numbers run from 0 to 15. The voice connected to voiceN on Drama 3 Generate corresponds to <|speaker:N|> in the script.
For example:
| Script label | Voice slot |
|---|---|
<|speaker:0|> | voice0 |
<|speaker:1|> | voice1 |
<|speaker:2|> | voice2 |
A speaker with no assigned voice receives one invented by the model.
Natural-language performance directions
Directions use ordinary language rather than a fixed list of emotion presets. You can describe the performance you want, though the exact interpretation is generated by the model.
| Script element | What it does | Example |
|---|---|---|
| Speaker label at the start of a line | Assigns the line to a character | <|speaker:0|> Hello. |
| Bracketed sound or pause | Requests an event at that point in the script | [sighs], [laughs], [pause] |
| Direction at the start of a line | Sets the delivery for that line | [with bright eager excitement] We found it! |
| Paired delivery tags | Shapes only the enclosed words | <whisper>Keep this secret.</whisper> |
| Director-note format | Separates a delivery instruction from the spoken line | Direction: icy calm. followed by Line: So this is goodbye. |
| Language hint after a line | Suggests a language without speaking the hint | [language: pt] |
Text in round parentheses is spoken. Do not use (whispering) when you intend it as an unspoken stage direction.
For the full script syntax, see Appendix C of the Fish Audio Drama 3 technical report.
Four dialogue-generation modes
The speakers setting on Drama 3 Generate controls how the script is performed.
| Mode | How it works | Voice separation | Dialogue interaction |
|---|---|---|---|
| one take per line — default | Generates each line independently | Keeps voices apart | Lines do not hear one another |
| one take per line, hearing the line before | Each line hears the preceding take | The second voice can drift unless guided | Lines can react to the previous line |
| one take per speaker | Generates all of one speaker’s lines together, then restores script order | Keeps voices apart | Speakers do not hear one another |
| together | Generates the script as one take | Voices can blend unless guided | Lines hear the surrounding dialogue |
How to choose:
- Start with one take per line when distinct character voices matter most.
- Try hearing the line before when you want a reply to respond to the preceding performance.
- Use one take per speaker to generate each character’s lines as a group.
- Try together when you want the scene performed with shared dialogue context.
Voice guidance for context-aware dialogue
In hearing the line before and together modes:
- Assign a voice to every speaker.
- Set
voice_guidanceto 1.0 on Drama 3 Generate.
This helps keep the voices distinct while preserving dialogue interaction. The trade-off is approximately twice the rendering time for those takes.
Faster long-script rendering
For a long script using one take per line, connect Drama 3 Speed Options and set:
lines_at_once = 4
This processes multiple lines at once. In the author’s reported test, a ten-minute, two-voice story rendered in 111 seconds instead of 225 seconds.
The option is off by default because it changes what a given seed generates. If you enable it, do not expect an otherwise identical seeded result to remain unchanged.
ComfyUI-Drama3 Models
Choosing a Drama 3 model file
All four files contain the complete Drama 3 model. They differ in how the routed experts—about 90% of the model—are stored.
The practical choice is between memory use, speed, and closeness to the original expert weights. All four completed the same proportion of takes in the author’s tests, but that does not mean every generated waveform is identical.
The filenames below link to .safetensors files.
| Model file | Best suited to | File size | Approx. system RAM |
|---|---|---|---|
drama3_fp8experts_bf16 | Fish Audio’s own expert weights, particularly on a 24 GB graphics card | 38.6 GB | 48 GB |
drama3_int8experts_bf16 | Similar quality with better performance on smaller graphics cards | 38.7 GB | 48 GB |
drama3_w6a8experts_bf16 | A middle ground: about 6 GB smaller than FP8, with results close to it | 32.7 GB | 40 GB |
drama3_w4a8experts_bf16 | The fastest reported option, or a system with about 32 GB RAM | 24.6 GB | 32 GB |
GPU memory and system RAM are different resources. Check both when deciding which file your computer can handle.
Reported generation speeds
Speed is measured as seconds of generated speech per second of processing:
- 1.0× means real time.
- 2.0× means roughly two seconds of speech generated per second.
- 0.6× means slower than real time.
| Model | 24 GB GPU memory | 12 GB GPU memory | 8 GB GPU memory |
|---|---|---|---|
| FP8 experts | 2.7× | 1.0× | 0.6× |
| INT8 experts | 2.7× | 1.5× | 0.9× |
| W6A8 experts | 3.2× | 1.3× | 0.7× |
| W4A8 experts | 3.8× | 2.0× | 1.0× |
These are the author’s RTX 4090 measurements. The 12 GB and 8 GB tests limited available GPU memory by having another process occupy the rest of the card; they are not measurements from separate 12 GB and 8 GB graphics cards. Your results may differ.
See the speed reference for measurement details.
Supporting models
| Component | Role in the workflow |
|---|---|
drama3_codec.safetensors | Drama 3’s audio codec, used to turn encoded audio into sound; the codec file is about 1.6 GB |
qwen3_asr_1.7b_bf16.safetensors | Transcribes reference voice clips for voice cloning |
The wider Qwen3-ASR family supports speech recognition and language identification across 30 languages and 22 Chinese dialects. That describes the transcription model’s capabilities, not a verified list of languages supported by this extension’s speech generation.
The supplied workflow specifies the 1.7B Qwen3-ASR file. Other upstream Qwen models, including its 0.6B recognizer and forced aligner, are not documented here as interchangeable extension options.
Compatibility baseline: ComfyUI v0.40 or newer.
Using ComfyUI-Drama3 Workflows
Once the extension and required model files are available, the example workflows provide a practical starting point without building a graph from scratch.
Clone a voice
- Drag
drama3_voice_clone.jsoninto ComfyUI. - Choose a clean speech clip in Load Reference Audio.
- Enter your script in Drama 3 Generate.
- Queue the workflow.
- Listen for complete speech, suitable delivery, and the intended voice.
- Unmute Save Drama 3 Voice if you want to reuse the prepared voice later.
Generate speech without a clip
- Open
drama3_text_to_speech.json. - Enter your text.
- Add performance directions if needed.
- Queue the workflow and listen to the model-invented voice.
Build a two-character scene
- Assign your prepared voices to
voice0andvoice1. - Label the dialogue with
<|speaker:0|>and<|speaker:1|>. - Start with one take per line for clear voice separation.
- If you want conversational reactions, switch to a context-aware mode and use
voice_guidance1.0 with a voice assigned to each speaker.
What's New with ComfyUI-Drama3
Update using Fish Audio’s 2026-10-29 retrained weights
The documented update combines retrained model weights with improvements to reliability, decoding speed, and dialogue controls.
| Change | Why it matters |
|---|---|
| Complete takes increased from 69 to 108 out of 120 in testing | Fewer attempts are lost to incomplete speech |
| Silent takes fell from 48 to 1 in the reported comparison | More generations produce usable audio |
| Smaller model files are now tuned using the model’s own speech | The compact variants have updated tuning |
| Faster decoding across the reported GPU-memory configurations | Less waiting between takes |
| Parallel line generation | Long scripts can render in roughly half the time in the reported example |
voice_guidance for context-aware dialogue | Characters can react to one another while keeping their voices more distinct |
These figures are test results, not guarantees that every script will finish correctly.
Compatibility when moving to the updated weights
Update the nodes before using the new model files. Older nodes reject the updated weights with
unexpected ['line_head.weight'].
Important compatibility details:
- The first release’s model files are preserved in the
v1/folder. - The newer nodes can still load those older files.
- Previously saved voices continue to work.
- The codec file is unchanged.
- Older saved workflows may retain
top_k = 30; set it to 0 when addressing silent or incomplete generations.
Troubleshooting ComfyUI-Drama3
Model loading fails with unexpected ['line_head.weight']
Cause: the model file uses the updated weights, but the nodes are older.
- Update the ComfyUI-Drama3 nodes.
- Restart ComfyUI.
- Load the model again.
A take goes silent or speaks only part of the script
- Confirm that you are using a model file based on the 2026-10-29 weights.
- Set
top_kto 0 on the generation node. Older workflows may still use 30. - Check that the reference transcript includes every word spoken in the clip.
- Use clean reference speech with boundaries between sentences.
- Use Load Reference Audio and Qwen3-ASR to help keep the selected clip and transcript matched.
- Try a new seed and generate another take.
Characters swap voices or begin sounding alike
- Check that each script speaker number matches the intended
voiceNslot. - Assign a voice to every character.
- Use one take per line if voice separation is your main priority.
- If you need dialogue interaction, choose hearing the line before or together.
- Set
voice_guidanceto 1.0 in those context-aware modes.
Expect approximately twice the rendering time when using that guidance setting.
Generation runs out of memory
- Lower
expert_cache_gbon Load Drama 3. - Check whether the shortage concerns GPU memory or system RAM.
- If system RAM is the limiting resource, choose a smaller model file.
- Compare your system with the approximate RAM requirements in the model table.
The W4A8 file is the smallest documented option, but it still requires approximately 32 GB of system RAM.
The first run takes several minutes
The first run reads the entire model file from disk once. Because these files are large, that initial load can take time.
- Allow the first load to finish.
- Check subsequent runs before treating the delay as a fault.
- If memory errors also occur, lower
expert_cache_gbor choose a smaller model as appropriate.
Later runs are reported to start in seconds.
The delivery sounds flat
- Listen to the reference clip’s performance.
- Choose a reference with delivery closer to your intended result.
- Add a clear direction such as
[with bright eager excitement]or[whispering]. - Generate another take and compare.
The model copies aspects of the reference delivery, so directions do not remove the importance of a suitable clip.
Frequently asked questions
Do I need a voice recording?
No. Use the text-to-speech workflow to generate an invented voice.
Can I reuse a voice without keeping the clip in the workflow?
Yes. Save it with Save Drama 3 Voice, then restore it with Load Drama 3 Voice.
How many characters can I include?
Up to 16, using speaker numbers 0–15.
Are instructions in parentheses silent?
No. Parenthesized text is spoken. Use the documented direction formats instead.
Why did the same seed sound different after enabling faster line generation?
lines_at_once changes what a seed generates. It is disabled by default for that reason.
Does the smallest file contain only part of Drama 3?
No. All four variants contain the complete model.
Does an 8 GB graphics card mean I only need 8 GB of memory overall?
No. GPU memory and system RAM are separate. Even the smallest model has an approximate 32 GB system-RAM requirement.
Learn More about ComfyUI-Drama3
Start with listening and workflow examples
- Demo and listening page: hear performances and compare them with their scripts.
- Voice-cloning workflow: a starting point for working from reference speech.
- Text-to-speech workflow: explore generated voices without a reference recording.
- Complete extension reference: descriptions of every node and setting, memory handling, measurements, and implementation details.
Listen to generated performances alongside their scripts, with directions highlighted.
The demo page credits its reference material. Cloned examples use public-domain films from 1948 and 1954 and recordings from the CSTR VCTK and Google FLEURS research speech collections; other demo voices are invented by the model.
Explore the underlying models
- ComfyUI-ready Drama 3 model files: compare the available model variants.
- Fish Audio Drama 3 model page: background on the underlying speech model.
- Drama 3 technical report: deeper explanations of the model and its evaluation.
- Script syntax, Appendix C: detailed guidance on performance instructions.
- Qwen3-ASR documentation: information about the transcription model used to prepare reference clips.
ComfyUI-Drama3 License and Responsible Use
The extension includes components under different licenses:
- Extension code: GNU GPL v3, except where otherwise noted.
- Components ported from Fish Audio, including its tokenizer and configuration: Fish Audio Community License.
- Components adapted from Qwen’s
qwen-asr: Apache License 2.0. - Component details: NOTICE.
Drama 3’s weights and outputs fall under the Fish Audio Community License. The supplied documentation describes free research and non-commercial use, and commercial use below USD 500,000 in annual revenue. A hosted text-to-speech service requires a license from Fish Audio. Read the license before using the model or its outputs commercially.
Do not clone the voice of an identifiable person without their consent.
Drama 3 and its codec are by Fish Audio; Qwen3-ASR is by the Qwen team. The author’s ComfyUI extension is not affiliated with or endorsed by either organization.
