audio-separation-nodes-comfyui splits stems inside a ComfyUI graph

Why a ComfyUI node pack for stem separation

audio-separation-nodes-comfyui is a set of ComfyUI custom nodes for separating audio and manipulating it. The project description gives the two halves: separate stems such as vocals, bass, drums and other from audio, and recombine, tempo match, slice or crop audio.

The reason to package this as ComfyUI nodes rather than as a script is composability. In a node graph, a separated vocal stem is a value that flows into the next node. You can take the four stems and combine them with different arithmetic, replace the background music of a video with something else, or remix a track by recombining stems, all inside the same graph that generates the rest of the output.

The examples in the README show the intent clearly. There is a workflow for separating voices in a video, one for replacing background music with StableAudio-generated music, one for remixing songs with StableAudio, one for separating song vocals from audio, and one for extracting instrumentals from songs. Each is a JSON workflow file in the example_workflows directory, so they load directly into ComfyUI rather than being pseudocode.

One use case deserves a note because it is a copyright-adjacent one the author states plainly. The background music replacement example exists so that you can replace copyrighted BGM in a video with new BGM, and the README suggests setting the denoise low so the new music stays similar to the original. That is a legitimate editing technique for anyone who owns the video but not the music bed, and it works because the separation node gives you an instrumental stem you can throw away.

The primary language is Python, the licence is MIT, and the only tagged release listed is v2.0.0 from 2026-04-13, with the last push on 2026-08-17.

The node list and what each one actually does

The README's node table is short enough to take in at a glance, and every entry does one thing.

Audio Separation splits audio into four stems using Hybrid Demucs, the PyTorch audio model. Audio Combine combines two audio tracks by overlaying their waveforms, with add, mean, subtract, multiply and divide as the operations. Audio Crop trims audio to a specific start and end time. Audio Tempo Match matches the tempo of two tracks by time-stretching both to their average BPM. Audio Speed Shift time-stretches or time-compresses by a given rate. Audio Get Tempo reports the tempo in BPM using onset detection. Audio Video Combine replaces the audio of a video input with a new audio track.

Two of these deserve more attention because they are the ones with a real algorithmic payload. Tempo Match does not detect tempo and stretch, it stretches both inputs to their average BPM, which means the two tracks converge on a common speed while keeping their relative timing within each track. That is the operation you want when you are aligning a generated instrumental to an existing recording, and it is not the same thing as resampling one track to match the other.

Audio Combine is similarly worth reading precisely, because "combine" sounds more like a mixer than it is. The operations are arithmetic on waveforms. Subtract is the one that unlocks the other nodes: subtract the instrumental from the original and you are left with something close to the vocals, and that is exactly the workflow the README recommends for isolating an instrument that lives inside the Other stem.

Get Tempo uses onset detection rather than a beat tracker with a tempo prior, and it is the node that feeds Tempo Match a BPM value when you want one specific track's tempo to win rather than the average of two.

Four stems means Other is a mixed bag

The stem mapping table is where the limits of the approach are clearest, and the README is direct about it.

Bass contains bass guitar, sub-bass and low-frequency instruments. Drums contains drums, percussion and hi-hats. Vocals contains singing, speech and vocal harmonies. Other contains everything else, listed as guitars, keyboards, synths, strings and similar.

That Other row is the constraint. The model gives you four buckets, and one of them is a category rather than an instrument. A guitarist who wants a clean guitar track is told in the README to separate first and then use the Audio Combine node to subtract the unwanted elements, or to process the Other output further.

That advice works, and it is genuinely useful for the common case of removing a vocal from a mix. It is not the same as an instrument-level separation model, and the difference shows in the quality of the result. Subtracting a drums stem from Other leaves a mix of guitar, keys and strings together, with the subtraction artefacts of the removal baked in, whereas a model trained for guitar isolation would give you a guitar that was never mixed with anything else in the first place.

The vocals row also has a consequence worth stating: speech and singing share a bucket. A podcast or a video with narration will produce a vocal stem that contains the narration, and separating that from sung audio is not something these four outputs allow.

So the node set is a good fit for three well-defined jobs, vocals, bass and drums, and a broad fourth bucket for everything else.

Installing into custom_nodes and the dependency set

The installation is four steps, and the README states them plainly. If you run ComfyUI inside a virtual environment, make sure it is activated. Clone the repository into the ComfyUI/custom_nodes folder, cd into the cloned repository, and install the requirements.

The requirements are short:

librosa>=0.10.2,<1
torchaudio>=2.3.0
numpy
moviepy

librosa and torchaudio carry the audio work, numpy is the array layer, and moviepy is there for the video handling that the Audio Video Combine node needs. The pyproject.toml repeats the same four, and it also shows that the package is registered with the Comfy Registry, with a PublisherId and a DisplayName, which means it can be installed through that route as well as by cloning.

There is a mismatch between the two files worth noticing, because it will matter if you follow the pyproject rather than the requirements. The pyproject sets the ruff target version to py39 and the mypy python_version to 3.9, while the classifiers and the readme do not state a minimum Python version, and the package itself depends on torchaudio 2.3.0 or newer. The pyproject also configures a strict test setup, with pytest, coverage over src, and a coverage fail-under of 90, plus ruff and mypy configuration, so the project's own quality gates are stricter than a casual install would suggest.

The repository layout follows the ComfyUI convention with an __init__.py at the root, a src directory holding the node implementations, an example_workflows directory, a tests directory, and a CHANGELOG, CONTRIBUTING and SECURITY file.

The video path needs a change to ComfyUI itself

The one part of this project that reaches outside its own repository is video input, and the README flags it twice with the same note.

In order to load videos into the LoadAudio node, you have to change a specific line in your ComfyUI install to include the video's extension, for example .mp4. The note links to that line in ComfyUI's own nodes_audio.py, and it appears on both the voice separation example and the background music replacement example, which are the two workflows that take a video as input.

This is a modification to the ComfyUI source, not a configuration option, and it is the kind of thing that a ComfyUI upgrade can silently undo. That is a real operational cost of these workflows, and it is worth knowing before you build a pipeline around them.

The Audio Video Combine node is the other half of the video story. It replaces the audio of a video input with a new audio track, which is what makes the background music replacement workflow possible: separate the stems, generate or choose a replacement instrumental, and swap it in.

The Audio Crop node, described in the README as slicing and cropping audio, is the third piece that matters for video work, since it lets you take a segment rather than the whole track. Between the separation node, the crop node and the video combine node, a ComfyUI graph can do a full voice isolation and re-mux of a video, and the two example workflows in the repository show exactly that shape.

Two documented failure modes and what they mean

The troubleshooting section covers two problems, and both are worth reading before you start, because one of them will probably happen to you.

The first is a BadZipFile error with a message about failing to find the central directory. The README explains that this means the Hybrid Demucs model checkpoint was corrupted during download, and the fix is to delete the cached file and restart ComfyUI to trigger a fresh download. The cache location is in the torch hub checkpoints directory, with a separate form for Windows:

# Default location (Linux/macOS)
rm ~/.cache/torch/hub/checkpoints/*.th

# Windows
del %USERPROFILE%\.cache\torch\hub\checkpoints\*.th

This is worth understanding as a class of problem rather than a single bug. The separation model is downloaded on first use, and a large download over a flaky connection is exactly the kind of thing that produces a partial file. The model file is cached rather than re-fetched every run, so a corrupted download persists until you clear it.

The second is a ConnectionResetError on Windows, where the README is reassuring: it is harmless Windows asyncio noise, it does not affect audio separation results, and it comes from Python's ProactorEventLoop closing connections, so it can be safely ignored. The example traceback is shown so you can match it against what you see.

Neither of these is a defect in the separation logic. They are the two environmental issues a node pack that downloads a model and runs an async event loop is likely to hit on a fresh Windows machine.

Where this node pack is the wrong tool

The boundaries come from the model and the platform, and they are clear enough to state as a decision rule.

If you need one instrument isolated rather than four buckets, this is the wrong tool. The Other stem mixes guitars, keyboards, synths and strings, and while the README's subtract-and-process route is a reasonable workaround, it is a workaround on a four-stem output rather than an instrument-level model. The same applies to separating speech from singing, which the vocals bucket does not distinguish.

If you need the result outside ComfyUI, this is also the wrong tool. The nodes produce values inside a graph, and there is no standalone command line interface documented for running separation outside ComfyUI. A user who wants a script that takes a folder of tracks and writes stem files would have to drive ComfyUI itself.

The video limitation cuts both ways. The video workflows require editing ComfyUI's source, which is a poor foundation for an unattended pipeline where ComfyUI gets upgraded by a package manager rather than by you.

The alternative approach is instructive by contrast. A command line separation tool, invoked directly on a file, avoids the graph layer, the ComfyUI source patch and the interactive workflow entirely, and it gives you the same four Hybrid Demucs stems with more control over batching and output paths. The difference in approach is that this node pack treats separation as one step in a larger generative pipeline, where a video, a generated music bed and a re-mux all need to line up, and a standalone tool treats it as a job in its own right. The video workflows in the example_workflows directory, replacing background music and isolating voices from a video, are the cases where the graph integration pays for itself.

Editorial conclusion

Adopt audio-separation-nodes-comfyui if you build ComfyUI workflows for music or video and want stem separation as a graph node rather than a separate preprocessing step, and if four stems plus waveform arithmetic cover what your workflow needs. Do not adopt it if you need a specific instrument isolated on its own, since guitar, keyboards, synths and strings all land in the Other stem and isolating one of them means post-processing the separated output yourself. Verify first that your ComfyUI install has the four Python dependencies present, that the Hybrid Demucs checkpoint downloads and caches cleanly on your machine, since a corrupted download is the most common failure the README documents, and that you understand the video case needs one line changed in ComfyUI's own nodes_audio.py before the LoadAudio node will accept a video file.

Frequently asked questions

Official sources

1. christian-byrne/audio-separation-nodes-comfyui on GitHub
2. Issues
3. License: MIT
4. README
5. Releases