4-bit quantization requires bitsandbytes. If you encounter issues:

# Standard installation
pip install bitsandbytes

Note: 4-bit quantization only supports SDPA and Eager attention types.

Device Selection

All nodes include a Device dropdown to control where inference runs:

Apple Silicon Users: ⚠️ MPS may cause mps_matmul errors during generation. If you encounter crashes, manually select cpu from the device dropdown.

4-bit Quantization: Requires CUDA GPU. Automatically disabled for CPU/MPS devices.

CPU Optimization: If using CPU mode with low utilization, set thread count:

import torch
torch.set_num_threads(8)  # Match your CPU cores

Precision by Device:

The model automatically uses optimal precision for each device:

• MPS uses fp16 for speed, but may still have compatibility issues
• CPU uses fp32 because PyTorch has limited fp16 support on CPU
• CUDA uses bfloat16 for optimal performance without quality loss

KugelAudio TTS

Generate speech from text with full control over generation parameters.

Inputs:

• text: Text to synthesize
• model: Model selection (auto-downloads on first run)
• device: Device selection (auto/cuda/mps/cpu)
• attention_type: Attention implementation (auto/sage_attn/flash_attn/sdpa/eager)
• use_4bit: Enable 4-bit quantization (~8GB VRAM, requires CUDA, SDPA/Eager only)
• cfg_scale: Guidance scale (1.0-10.0, default 3.0) - higher = more adherence to text
• max_new_tokens: Max generation length (512-4096, default 2048)
• language: Optional language hint (auto-detects if not set)
• keep_loaded: Keep model in VRAM (faster subsequent runs)
• output_stereo: Output stereo audio
• seed: Random seed for reproducibility (default 42)
• max_words_per_chunk: Split long text at sentence boundaries (100-500, default 250)
• do_sample: Enable sampling for varied output (default False)
• temperature: Sampling temperature (0.1-2.0, default 1.0)

KugelAudio Voice Clone

Clone any voice using a short reference audio sample (5-30 seconds recommended).

Same inputs as TTS plus:

• voice_prompt: Reference audio file for voice cloning
• Higher quality reference = better voice similarity

KugelAudio Multi-Speaker

Generate conversations with up to 6 speakers with automatic pause between speakers.

Inputs:

• text: Conversation text (use Speaker N: format, N=1-6)
• pause_between_speakers: Silence between speaker turns (0.0-2.0 seconds, default 0.2s)
• Voice inputs for each speaker (optional)
• All TTS options (cfg_scale, attention type, etc.)

Text Format:

Speaker 1: Hello, I'm the first speaker.
Speaker 2: Hi there, I'm the second speaker.
Speaker 3: I'm the third speaker!
Speaker 4: And I'm the fourth.
Speaker 5: Adding a fifth voice here!
Speaker 6: And the sixth speaker!

Optional voice inputs:

• speaker1_voice through speaker6_voice: Voice samples for each speaker

KugelAudio Watermark Check

All KugelAudio output contains an inaudible watermark using Facebook's AudioSeal technology. This node detects whether audio was generated by KugelAudio.

Returns:

• detected: String ("Detected" / "Not Detected")
• confidence: Float (0.0-1.0)

Audio Format:

• Input: Any sample rate, mono or stereo (auto-converted)
• Output: 24kHz mono (optionally stereo)

The 4-bit toggle quantizes the LLM component (7B parameters), keeping the diffusion head and tokenizers at full precision for best audio quality.

Attention Type Compatibility:

Tips:

• SageAttention: Fastest (CUDA only, GPU-optimized kernels)
• FlashAttention 2: Fast (CUDA only)
• SDPA: PyTorch optimized (all platforms)
• Eager: Standard/slowest (all platforms, required for 4-bit)

KugelAudio achieves state-of-the-art performance, beating industry leaders including ElevenLabs in rigorous human preference testing.

Human Preference Benchmark (A/B Testing): 339 human evaluations comparing KugelAudio against leading TTS models.

OpenSkill Ranking:

Model Specs:

RTF = Real-Time Factor (generation time / audio duration).

Voice cloning failed: 'Qwen2Config' object has no attribute 'pad_token_id'

run install_portable.bat in ComfyUI\custom_nodes\ComfyUI-KugelAudio

Out of Memory (OOM) Errors

1. Enable 4-bit quantization: Reduces VRAM from ~19GB to ~8GB
2. Use SDPA or Eager attention: Required with 4-bit mode
3. Reduce max_words_per_chunk: Lower chunk size reduces peak memory
4. Restart ComfyUI: Sometimes VRAM doesn't release properly
5. Close other GPU applications: Free up GPU memory
6. Use SageAttention (CUDA only): Most memory-efficient attention type

bitsandbytes Installation Fails

Windows:

pip install bitsandbytes

Linux:

pip install bitsandbytes

macOS (Apple Silicon):

pip install bitsandbytes

Note: 4-bit quantization on macOS with MPS may have limited compatibility.

Model Download Fails

1. Check internet connection
2. Try manual download:

   huggingface-cli download kugelaudio/kugelaudio-0-open --local-dir ComfyUI/models/kugelaudio/kugelaudio-0-open
   

3. Set HF_TOKEN environment variable if using gated model

Manual Package Installation (Portable ComfyUI)

If the auto-installer fails or you need to reinstall the bundled package:

Find your Python path:

• Standard: python
• Portable Windows: python_embeded\python.exe

Install the bundled package:

# Navigate to the custom node folder
cd ComfyUI/custom_nodes/ComfyUI-KugelAudio

# Install using portable Python (replace /path/to/ComfyUI with your actual path) or run .bat file
C:\path\to\ComfyUI\python_embeded\python.exe -m pip install ./kugelaudio-open

# For standard Python installation
python -m pip install ./kugelaudio-open

Verify installation:

C:\path\to\ComfyUI\python_embeded\python.exe -c "import kugelaudio_open; print('kugelaudio-open installed successfully')"

Note: The bundled package is located at ComfyUI/custom_nodes/ComfyUI-KugelAudio/kugelaudio-open/

Audio Quality Issues

1. Static/noise: Disable 4-bit quantization, use full precision
2. Robot voice: Increase cfg_scale (try 3.0-5.0)
3. Clipping/distortion: Lower cfg_scale (try 2.0-3.0)
4. Slow generation: Use SageAttention with CUDA GPU

Attention Type Warnings

If you see warnings about attention types:

• 4-bit mode requires SDPA or Eager
• Auto mode will automatically select the best compatible option
• SageAttention and FlashAttention require CUDA

Device Selection & Compatibility

Apple Silicon (MPS) Issues:

• MPS may cause mps_matmul errors during generation
• If you see "incompatible dimensions" or "LLVM ERROR", select cpu from the Device dropdown
• MPS is auto-detected but not always stable with this model

CPU Mode:

• Select cpu from the Device dropdown
• 4-bit quantization requires CUDA (automatically disabled on CPU)
• Set PyTorch threads for better utilization:

  import torch
  torch.set_num_threads(8)  # Match your CPU cores
  

• Expect significantly slower generation than GPU

Forcing Specific Device:

• Use the Device dropdown in any KugelAudio node
• auto: Tries CUDA → MPS → CPU (with warnings for MPS)
• cuda: NVIDIA GPU only
• mps: Apple Silicon GPU only (may have issues)
• cpu: CPU only (most compatible)

Long Text Not Processing

1. Set max_words_per_chunk to split long text (recommended: 200-300)
2. Check for proper sentence-ending punctuation
3. Progress bar shows stage completion in ComfyUI console

Multi-Speaker Not Working

1. Format text exactly: Speaker N: Text (N = 1-6)
2. Ensure voice inputs are provided if using voice cloning
3. Each line must have a speaker prefix
4. Maximum 6 speakers (1-6)

Watermark Detection Issues

• Watermark detection works on generated audio only
• Very short audio clips may have reduced detection accuracy
• Output shows "Detected" or "Not Detected" as string

✅ Appropriate Uses

• Accessibility: Text-to-speech for visually impaired users
• Content Creation: Podcasts, videos, audiobooks, e-learning
• Voice Assistants: Chatbots and virtual assistants
• Language Learning: Pronunciation practice and language education
• Creative Projects: With proper consent and attribution

❌ Prohibited Uses

• Creating deepfakes or misleading content
• Impersonating individuals without explicit consent
• Fraud, deception, or scams
• Harassment or abuse
• Any illegal activities

Limitations

• VRAM Requirements: Requires ~19GB VRAM for full precision, ~8GB with 4-bit quantization
• Speed: Approximately 1.0x real-time on modern GPUs
• Voice Cloning Quality: Best results with 5-30 seconds of clear reference audio
• Language Quality Variation: Quality may vary across languages based on training data distribution