README.md

September 8, 2026 · View on GitHub

Comfy-MSS

ComfyUI custom nodes for pymss, a Python music source separation package.

demo

Nodes

  • MSS Separate: separates a ComfyUI AUDIO stream with catalog MSS/non-VR pymss models.
  • MSS Separate List: list-output variant of MSS Separate.
  • Custom MSS Separate: separates audio with user-provided MSS models from the custom model folder.
  • Custom MSS Separate List: list-output variant of Custom MSS Separate.
  • VR Separate: separates a ComfyUI AUDIO stream with VR/UVR pymss models.
  • VR Separate List: list-output variant of VR Separate.
  • MSS Params: optional parameter input for MSS Separate and Custom MSS Separate.
  • VR Params: optional parameter input for VR Separate.
  • Load Audio: loads one audio file and outputs both the audio stream and the file name without extension.
  • Audio Invert Phase: inverts audio input a and outputs -a.
  • Audio Normalize: normalizes only when the peak is above 0 dBFS.
  • Audio Ensemble: combines 2 to 10 audio inputs with selectable ensemble algorithms and weights.
  • Save Audio: saves ComfyUI AUDIO streams as wav, flac, or mp3.

Important

Workflows created in v1.0.x are not backward-compatible with v1.1.0+ workflows due to node type renaming.

Installation

Clone or download this repository, put it into your ComfyUI custom_nodes folder. The custom nodes load automatically when you start ComfyUI. Make sure to install pymss in the same Python environment as ComfyUI. Or you can use comfyui_manager to install this custom node.

ComfyUI/custom_nodes
        └──comfy-mss
            ├── comfy_mss
            ├── web
            ├── nodes.py
            └── ...

Project Structure

  • comfy_mss: main package folder.
  • web: frontend files.
  • examples: example ComfyUI workflows.
  • nodes.py: defines custom nodes.
  • requirements.txt: Python dependencies.

Separation Nodes

Model Folder

Model files default to: ComfyUI/models/pymss. The folder is created automatically when the custom node loads.

The separator nodes do not expose model folder widgets, so shared workflows do not contain machine-specific model paths. The model folder can be changed with environment variables:

  • COMFY_MSS_MODEL_DIR
  • PYMSS_MODEL_DIR

You can also configure an extra ComfyUI model path by copying extra_model_paths.yaml.example to extra_model_paths.yaml and adding an independent pymss config group:

comfy-mss:
  pymss: E:/AI/Pymss-Studio/models

The outer comfy-mss is only the config group name. The inner pymss is the actual ComfyUI model folder key used by comfy-mss. Custom models are always stored in the custom directory below each registered pymss model folder.

If multiple pymss model folders are registered, comfy-mss scans them when checking whether catalog models are already downloaded. Downloads use the default pymss folder.

MSS/VR Separate

MSS Separate and VR Separate inputs:

  • audio: ComfyUI AUDIO.
  • model_name: pymss catalog model name.
  • device: auto, cpu, cuda, mps, or mlx.
  • download_missing: defaults to true.
  • source: modelscope, huggingface, or hf-mirror, select huggingface if you have access to HuggingFace.
  • params: optional params node output.
  • device_ids: defaults to 0.
  • debug: prints pymss debug and timing information when enabled.

The list variants, MSS Separate List and VR Separate List, use the same inputs and model menu behavior as their matching separate nodes. Instead of creating one audio/text output pair per stem, they return two list outputs:

  • audios: separated stem audio list.
  • stem_names: matching stem name list.

Custom MSS Separate

Custom MSS Separate supports MSST models only; VR/UVR models are not supported by this custom-model workflow. It scans the custom folder located under the pymss model root: <pymss_model_dir>/custom (for example, E:/AI/Pymss-Studio/models/custom when pymss is E:/AI/Pymss-Studio/models). Each custom model needs its own direct child folder. The node displays that folder's name, and only lists folders containing both a supported model file and a YAML config file, for example:

custom/
  my_model_name/
    weights_name.ckpt
    config_name.yaml

Config files must use .yaml. The node reads training.instruments from the YAML to determine dynamic stem outputs:

training:
  instruments:
    - Vocals
    - Instrumental

Custom MSS Separate inputs:

  • audio: ComfyUI AUDIO.
  • model_name: detected custom model pair.
  • model_type: pymss architecture type, such as mel_band_roformer, bs_roformer, mdx23c, or htdemucs. VR/UVR is not supported.
  • device: auto, cpu, cuda, mps, or mlx.
  • params: optional MSS Params output.
  • device_ids: defaults to 0.
  • debug: prints pymss debug and timing information when enabled.

Click Refresh Models after adding, removing, or changing custom model files. If no valid custom model pair exists, the node hides unused stem outputs.

Custom MSS Separate List uses the same inputs and model menu behavior as Custom MSS Separate, but returns audios and stem_names as list outputs.

Params Nodes

MSS Params

  • batch_size: defaults to 1.
  • overlap_size: defaults to Default.
  • chunk_size: defaults to Default.
  • normalize: defaults to false.
  • enable_tta: defaults to false.
  • standardize: defaults to false.

Default for overlap_size and chunk_size means the selected model's YAML values are used. Enter a positive integer to override either value.

normalize enables pymss output peak normalization. standardize enables pymss MSS input standardization.

VR Params

  • batch_size: defaults to 1.
  • window_size: defaults to 512.
  • aggression: defaults to 5.
  • enable_tta: defaults to false.
  • high_end_process: defaults to false.
  • enable_post_process: defaults to false.
  • post_process_threshold: defaults to 0.2.
  • normalize: defaults to false.

Audio Nodes

Load Audio

Load Audio is based on ComfyUI's built-in audio loader, but it also outputs audio_name, the selected file name without extension. The frontend adds the same upload button behavior as the official loader.

Audio Invert Phase and Normalize

Audio Invert Phase multiplies the waveform by -1.

Audio Normalize checks the peak level. If the peak is above 1.0, it scales the audio to 0.999; otherwise it leaves the audio unchanged.

Audio Ensemble

Audio Ensemble inputs:

  • input_count: dynamically selects 2 to 10 audio inputs.
  • ensemble_type: avg_wave, median_wave, min_wave, max_wave, avg_fft, median_fft, min_fft, or max_fft.
  • audio_1 to audio_10: dynamic audio inputs.
  • weight_1 to weight_10: dynamic numeric weights, defaulting to 1.

Only the selected number of audio inputs and matching weights are shown. The ensemble algorithms are delegated to pymss' native ensemble implementation.

Save Audio

Save Audio is an output node. It saves audio directly and does not need a downstream node.

Inputs:

  • audio: ComfyUI AUDIO.
  • output_format: wav, flac, or mp3.
  • sample_rate: 32000, 44100, or 48000; defaults to 44100.
  • filename: optional forced text input. Connect a composed file name such as audio_name + "_" + stem_name.

Save behavior:

  • Files are always saved in ComfyUI's default output folder.
  • If filename is not connected or is empty, saved files fall back to audio_YYYYMMDD_HHMMSS.
  • Existing files are not overwritten. If a target path already exists, comfy-mss appends a numeric suffix.

Format-specific options are shown dynamically:

  • wav: FLOAT, PCM_24, PCM_16
  • flac: PCM_24, PCM_16
  • mp3: 128k, 192k, 256k, 320k

Contributions

Contributions are welcome! Please open an issue or submit a pull request.