demucs

Music source separation element using demucs.

By default the element makes use of the (demucs)pip-demucs Python module, which must be available locally. It is possible to install the module via pip or use a virtualenv via uv or similar.

Alternatively, the element can connect to a small Python service that does the actual processing. The service is provided as part of the plugin and has to be started separately, either on the same machine or another machine. It can handle multiple sessions from multiple plugin instances in parallel.

The service can be run with uv in a virtualenv via uv run service/main.py. See uv run service/main.py --help for more configuration options.

Selecting a specific Python version (inprocess feature)

When built with the inprocess feature, the plugin embeds the Python interpreter directly. The Python version is determined at compile time by pyo3. To select a specific version, set the PYO3_PYTHON environment variable when building:

 PYO3_PYTHON=python3.13 cargo build --features inprocess

At runtime, if the Python packages (such as torch and demucs) are installed in a non-default location, set PYTHONPATH to the site-packages directory containing them:

 PYTHONPATH=/path/to/python3.13/site-packages gst-launch-1.0 ...

Example pipeline outputting only vocals

 gst-launch-1.0 uridecodebin uri=file:///path/to/music/file ! audioconvert ! demucs name=demucs   demucs.src_vocals ! queue ! audioconvert ! autoaudiosink

This will separate the vocals from the audio input and only play back the vocals.

Example pipeline outputting the original audio without vocals

 gst-launch-1.0 uridecodebin uri=file:///path/to/music/file ! audioconvert ! tee name=t ! queue max-size-time=0 max-size-bytes=0 max-size-buffers=2 ! demucs name=demucs model-name=htdemucs   demucs.src_vocals ! queue ! audioamplify amplification=-1 ! mixer.sink_0   t. ! queue max-size-time=9000000000 max-size-bytes=0 max-size-buffers=0 ! mixer.sink_1   audiomixer name=mixer ! audioconvert ! autoaudiosink

This will separate the vocals from the audio input and then subtract it from the input audio by using audioamplify to invert the samples and audiomixer to mix it into the input.

GObject
    ╰──GInitiallyUnowned
        ╰──GstObject
            ╰──GstElement
                ╰──demucs

audio/x-raw:
           rate: [ 32000, 48000 ]
       channels: 2
         layout: interleaved
         format: F32LE

audio/x-raw:
           rate: [ 32000, 48000 ]
       channels: 2
         layout: interleaved
         format: F32LE

“chunk-duration” guint64

“model-name” gchararray

“overlap” gfloat

“processing-latency” guint64

“url” gchararray