ComfyUI Music Tools

Made with ❤️ and GitHub Copilot

⭐ If you find this useful, please star the repository! ⭐

Vocal Naturalizer Usage

Audio Input → Music_MasterAudioEnhancement
  ├─ vocal_enhance: True
  ├─ naturalize_vocal: 0.5  ← Remove auto-tune/robotic effect
  ├─ deesser_amount: 0.5
  ├─ breath_smooth: 0.3
  └─ reverb_amount: 0.2
→ Audio Output

Naturalize Vocal Parameter Guide:

• 0.0: Disabled (original AI vocal)
• 0.3: Subtle (light humanization)
• 0.5: Balanced (recommended) ⭐
• 0.7: Aggressive (maximum humanization)
• 1.0: Extreme (may introduce artifacts)

AI Enhancement with MetricGAN+

Audio Input → Music_MasterAudioEnhancement
  ├─ ai_enhance: True
  ├─ ai_mix: 0.6
  └─ [other parameters...]
→ Audio Output

First run auto-downloads the model to ComfyUI/models/MusicEnhance/metricgan-plus-voicebank

Professional Mastering Chain

Audio Input 
→ Music_NoiseRemove (0.5)
→ Music_MasterAudioEnhancement
   ├─ EQ: bass +0dB, mid +0.5dB, high +1.5dB
   ├─ Clarity: 0.5
   ├─ Vocal Enhance: True
   ├─ Naturalize Vocal: 0.5
   └─ Target Loudness: -6 LUFS
→ Music_StereoEnhance (1.0)
→ Audio Output

Stem Separation & Mixing

Audio Input
  ↓
Music_StemSeparation (vocals) → [Process] ↘
Music_StemSeparation (drums)  → [Process] ↗ Music_StemRecombination
Music_StemSeparation (bass)   → [Process] ↗   ├─ vocals: 1.2
Music_StemSeparation (other)  → [Process] ↗   ├─ drums: 1.0
                                              ├─ bass: 0.9
                                              └─ other: 0.8
                                                  ↓
                                            Audio Output

📖 Documentation

Vocal Naturalizer Technical Details

The apply_vocal_naturalizer() function uses 5 techniques to humanize AI vocals:

1. Pitch Variation (Vibrato-like)

   • Adds subtle ~4.5 Hz vibrato
   • 0.2% pitch variation at maximum
   • Breaks rigid pitch quantization

2. Formant Variation

   • Random subtle variation in 200-3000 Hz band
   • Humanizes timbre and vocal character
   • Adds "life" to static formants

3. Metallic Artifact Removal

   • Reduces 6-10 kHz digital artifacts
   • 30% reduction of harsh frequencies
   • Less "digital" sound

4. Quantization Masking

   • Adds shaped noise (1-4 kHz)
   • Masks pitch "stair-step" artifacts
   • Very subtle (0.2% amplitude)

5. Pitch Transition Smoothing

   • Low-pass filtering on differential signal
   • Smooths abrupt note changes
   • Creates natural pitch glides

Performance: ~10ms per second of audio (~102x realtime)

Master Audio Enhancement Parameters

LUFS Standards

11. Music_StemSeparation - Separate audio into stems

    • Input: Audio data
    • Output: Separated stem audio
    • Parameters: Stem type (vocals, drums, bass, music)
    • Use Case: Extract individual components for separate processing

12. Music_StemRecombination - Recombine separated stems

    • Input: Four stem audio streams (vocals, drums, bass, music)
    • Output: Recombined mixed audio
    • Parameters: Volume control for each stem (0-2)
    • Features: Custom mixing with individual stem volume control

Installation

1. Clone this repository into your ComfyUI custom_nodes folder:

cd ComfyUI/custom_nodes
git clone https://github.com/yourusername/ComfyUI_MusicTools.git

2. Install dependencies:

pip install -r ComfyUI_MusicTools/requirements.txt

3. Restart ComfyUI

Usage

Basic Workflow

1. Load Audio - Use ComfyUI's audio loading node
2. Apply Processing - Connect audio through any Music nodes
3. Combine Effects - Chain multiple nodes together
4. Save/Output - Use ComfyUI's audio output nodes

Example Workflows

Noise Removal

Audio Input → Music_NoiseRemove → Audio Output

Audio Enhancement Chain

Audio Input → Music_NoiseRemove → Music_LufsNormalizer → Music_Equalize → Audio Output

AI Music Enhance (MetricGAN+)

Audio Input → Music_MasterAudioEnhancement (ai_enhance=True, ai_mix=0.6) → Audio Output

• First run auto-downloads the model to ComfyUI/models/MusicEnhance/metricgan-plus-voicebank
• For offline use, download the Hugging Face repo speechbrain/metricgan-plus-voicebank and drop its files into that folder
• If torch/speechbrain are missing, the node falls back to the classic DSP-only chain

Stereo Mastering

Audio Input → Music_Equalize → Music_StereoEnhance → Music_LufsNormalizer → Audio Output

Creative Processing

Audio Input → Music_Compressor → Music_Reverb → Music_Gain → Audio Output

Professional Stem Separation & Mixing

Audio Input 
  ↓
Music_StemSeparation (extract vocals)
Music_StemSeparation (extract drums)
Music_StemSeparation (extract bass)
Music_StemSeparation (extract music)
  ↓
[Optional: Process each stem individually]
  ↓
Music_StemRecombination (remix with custom volumes)
  ↓
Audio Output

Vocal Enhancement from Stems

Audio Input
  ↓
Music_StemSeparation (vocals) → Music_Equalize (boost presence) ↘
Music_StemSeparation (drums) ↗
Music_StemSeparation (bass) ↗
Music_StemSeparation (music) ↗
  ↓
Music_StemRecombination (vocals volume +0.3)
  ↓
Audio Output

Instrumental Mix (Vocals Removal)

Audio Input
  ↓
Music_StemSeparation (vocals) → [DISCARD]
Music_StemSeparation (drums) ↘
Music_StemSeparation (bass) → Music_StemRecombination (vocals volume 0.0)
Music_StemSeparation (music) ↗
  ↓
Audio Output

Stem Separation Parameters

Stem Types

• Vocals: 200 Hz - 8 kHz, optimized for voice presence and clarity
• Drums: 0 - 6 kHz, includes percussion and transient detection
• Bass: 20 - 250 Hz, fundamental frequencies and low-end
• Music: Remaining frequencies, instruments and background elements

Recombination Volume Control

• 0.0: Mute (silence this stem)
• 0.5 - 1.0: Normal volume range
• 1.0: Default (unity gain)
• 1.2 - 1.5: Subtle boost
• 2.0: Maximum boost (double volume)

Stem Processing Tips

1. Extract stems individually for processing
2. Apply EQ, compression, or reverb to isolated stems
3. Adjust volume balance with Recombination node
4. Preserve original frequencies for natural sound
5. Use automation for dynamic mixing

Node Parameters Guide

Noise Removal Intensity

• 0.0: No noise removal (passes audio unchanged)
• 0.3: Subtle noise reduction
• 0.5: Balanced noise removal (recommended starting point)
• 0.8: Aggressive noise reduction
• 1.0: Maximum noise removal (may affect audio quality)

Stereo Enhancement Intensity

• 0.0: No enhancement (mono/original stereo)
• 0.5: Moderate enhancement
• 1.0: Strong stereo widening
• 2.0: Maximum enhancement (extreme width)

LUFS Standards

• -23 LUFS: Streaming platforms (Spotify, YouTube Music)
• -14 LUFS: Broadcast standard (EBU R128)
• -16 LUFS: Podcast standard
• -6 LUFS: Mastered music (recommended)

Compression Ratios

• 2:1: Gentle/transparent compression
• 4:1: Moderate compression (vocals)
• 8:1: Strong compression (limiting)
• 16:1: Brick-wall limiting

⚡ Performance Benchmarks

Processing 1 second of stereo audio (44.1kHz):

Total for 3-minute song: ~2 seconds (26x faster than original)

🎯 Use Cases

For AI Music Generators (Ace-Step, Suno, Udio)

• Remove robotic/auto-tune artifacts with Vocal Naturalizer
• Enhance vocal clarity and presence
• Master to commercial loudness standards
• Reduce digital artifacts and hiss

For Podcasters

• Remove background noise
• Normalize loudness to -16 LUFS
• Compress for consistent levels
• EQ for voice clarity

For Musicians

• Professional mastering chain
• Stem separation for remixing
• Multi-band dynamics control
• Stereo enhancement

For Content Creators

• Quick audio cleanup
• Loudness normalization for platforms
• Add reverb and spatial effects
• Mix multiple audio sources

🔧 Technical Details

Audio Format

• Input: Float32 PCM audio tensors
• ComfyUI format: (1, samples, channels)
• Supports: Mono and stereo

Processing Methods

• Denoise: Spectral subtraction with STFT
• Limiter: True-peak with ndimage.maximum_filter1d
• Compression: Vectorized multiband dynamics
• EQ: Butterworth IIR filters
• Clarity: Transient shaper + harmonic exciter
• Vocal Naturalizer: Phase modulation + formant variation
• All operations: Optimized with NumPy vectorization

System Requirements

Minimum:

• Python 3.8+
• 4GB RAM
• CPU: Any modern processor

Recommended:

• Python 3.10+
• 8GB+ RAM
• CPU: Multi-core (4+ cores)
• GPU: NVIDIA (for AI enhancement)

Dependencies

numpy>=1.21.0
scipy>=1.7.0
pyloudnorm>=0.1.0
noisereduce>=2.0.0
torch>=1.9.0 (optional, for AI enhancement)
torchaudio>=0.9.0 (optional, for AI enhancement)
speechbrain>=0.5.0 (optional, for AI enhancement)
huggingface-hub>=0.10.0 (optional, for model downloads)

🐛 Troubleshooting

Common Issues

Audio sounds robotic/auto-tuned

• Increase naturalize_vocal parameter (try 0.7)
• Enable vocal enhancement
• Check AI enhance mix isn't too high

Clipping/distortion

• Lower target loudness (-9 to -12 LUFS)
• Reduce clarity amount
• Check input audio isn't already clipping

Noise removal too aggressive

• Lower denoise_intensity (try 0.3)
• Use "Hiss Only" mode instead of "Full Denoise"
• Process in multiple light passes

AI enhancement not working

• Install torch, torchaudio, speechbrain
• Check model downloaded to ComfyUI/models/MusicEnhance/
• Node falls back to DSP-only if dependencies missing

Slow processing

• Disable AI enhancement for faster processing
• All DSP functions are optimized (~100x realtime)
• AI enhancement is slower but optional

Performance Tips

1. Use "Hiss Only" denoise for speed (faster than full denoise)
2. Disable AI enhancement if not needed
3. Process shorter clips if experimenting
4. All vocal enhancement functions are optimized for speed
5. Limiter and compression use vectorized operations

📊 Comparison with Other Tools

🤝 Contributing

Contributions are welcome! Areas for improvement:

• Additional vocal effects (pitch correction, formant shifting)
• More stem separation models
• GPU acceleration for DSP functions
• Additional AI enhancement models
• UI improvements and presets

Development Setup

git clone https://github.com/jeankassio/ComfyUI_MusicTools.git
cd ComfyUI_MusicTools
pip install -r requirements.txt

Running Tests

python test_vocal_naturalizer.py
python test_limiter_speed.py
python test_vocal_enhance_speed.py

📝 Changelog

v1.0.0 (December 2025)

• ✨ Added Vocal Naturalizer for AI vocal humanization
• ⚡ Optimized all processing functions (26x faster)
• 🎛️ Master Audio Enhancement node with complete chain
• 🎤 Vocal-focused processing (de-esser, breath smoother, reverb)
• 🤖 AI enhancement with SpeechBrain MetricGAN+
• 🎼 Stem separation and recombination
• 📊 LUFS-based loudness normalization
• 🔊 True-peak limiter with lookahead
• 🎚️ Multiband compression (3 bands)
• ✨ Clarity enhancement suite

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with GitHub Copilot - AI pair programming for faster development
• ComfyUI community for inspiration and feedback
• SpeechBrain team for MetricGAN+ model
• Audio DSP community for best practices

📧 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: See VOCAL_NATURALIZER.md for detailed vocal naturalizer guide

⭐ Star History

If you find this project useful, please consider giving it a star! ⭐

Version: 1.0.0
Last Updated: December 2025
Status: Production Ready
Developed with: GitHub Copilot 🤖