pymss-project-comfy-mss/README.md

<h1 align="center">Comfy-MSS</h1>
<div align="center">
    ComfyUI custom nodes for <a href="https://pypi.org/project/pymss/">pymss</a>, a Python music source separation package.<br>
    <br>
    <img src="comfy-mss.png" alt="demo" style="max-width:100%;">
</div>

## 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.

This revision requires `pymss>=2.1.6` for BS PolarFormer support (`pymss-core` 0.1.9).
Until those releases are published, development requires the matching local pymss
and pymss-core checkouts; the new requirement cannot yet be installed from PyPI.
From this repository, install the two sibling checkouts with ComfyUI's Python:
`python -m pip install -e ../pymss-core -e ../pymss`.

```bash
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:

```yaml
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.

All separation nodes resample incoming audio to the sample rate declared by the selected model before inference.
Returned ComfyUI `AUDIO` values carry that model sample rate. This keeps the frequency and time axes aligned
with the model's training configuration; downstream save nodes may still explicitly convert the result to another output rate.

For catalog versions that do not include a model's complete stem list, an undownloaded model keeps the node's generic
output slots instead of deleting possible residual stems. After its YAML config is available, use `Refresh Models` to
replace those placeholders with the configured stem names. Execution always reads the complete stem list from the loaded model.

### 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:

```text
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:

```yaml
training:
  instruments:
    - Vocals
    - Instrumental
```

`Custom MSS Separate` inputs:

- `audio`: ComfyUI `AUDIO`.
- `model_name`: detected custom model pair.
- `model_type`: defaults to `auto`, which is passed to pymss for architecture detection. Detection rules are maintained in pymss-core. Unknown or ambiguous configurations raise `ModelTypeDetectionError` (a `RuntimeError` subclass) through ComfyUI's normal execution error handling; select the architecture explicitly to continue. 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.

Existing workflows keep their saved `model_type`; explicit selections take precedence over automatic detection. Models without identifying YAML fields still require a manual architecture selection.

## 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.

Mono inputs are expanded to match multichannel inputs, and a single-item batch is broadcast to the largest input batch.
Other incompatible channel or batch counts raise an error instead of silently dropping audio data.

### 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.