deezer/spleeter · error · SpleeterError

{} binary not found

Error message

{} binary not found

What it means

`FFMPEGAudioAdapter.__init__` checks that both `ffmpeg` and `ffprobe` executables are on the PATH via `shutil.which`. If either binary is missing, a `SpleeterError` naming the missing binary is raised at adapter construction time, before any audio is loaded or written.

Source

Thrown at spleeter/audio/ffmpeg.py:62

    SUPPORTED_CODECS: Dict[Codec, str] = {
        Codec.M4A: "aac",
        Codec.OGG: "libvorbis",
        Codec.WMA: "wmav2",
    }
    """ FFMPEG codec name mapping. """

    def __init__(_) -> None:
        """
        Default constructor, ensure FFMPEG binaries are available.

        Raises:
            SpleeterError:
                If ffmpeg or ffprobe is not found.
        """
        for binary in ("ffmpeg", "ffprobe"):
            if shutil.which(binary) is None:
                raise SpleeterError("{} binary not found".format(binary))

    def load(
        _,
        path: Union[Path, str],
        offset: Optional[float] = None,
        duration: Optional[float] = None,
        sample_rate: Optional[float] = None,
        dtype: bytes = b"float32",
    ) -> Signal:
        """
        Loads the audio file denoted by the given path
        and returns it data as a waveform.

        Parameters:
            path (Union[Path, str]:
                Path of the audio file to load data from.
            offset (Optional[float]):
                (Optional) Start offset to load from in seconds.

View on GitHub (pinned to c8854001ac)

Solutions

1. Install ffmpeg system-wide (includes ffprobe): `apt-get install ffmpeg`, `brew install ffmpeg`, or `conda install ffmpeg`
2. If ffmpeg is already installed, add its directory to the PATH environment variable
3. Verify with `which ffmpeg ffprobe` (or `where` on Windows) that both resolve

Example fix

# before (Dockerfile)
FROM python:3.9-slim
RUN pip install spleeter
# after
FROM python:3.9-slim
RUN apt-get update && apt-get install -y ffmpeg
RUN pip install spleeter

import shutil
missing = [b for b in ('ffmpeg', 'ffprobe') if shutil.which(b) is None]
if missing:
    raise SystemExit(f'Missing binaries: {missing}. Install ffmpeg and ensure it is on PATH.')

import shutil
try:
    adapter = FFMPEGAudioAdapter()
except Exception as e:
    if 'binary not found' in str(e):
        raise SystemExit('Install ffmpeg: apt-get install ffmpeg / brew install ffmpeg')
    raise

When it happens

Trigger: Instantiating `FFMPEGAudioAdapter()` (directly or via `AudioAdapter.get('spleeter.audio.ffmpeg.FFMPEGAudioAdapter')`) on a machine where `ffmpeg` or `ffprobe` is not installed or not on PATH.

Common situations: Fresh Docker images or CI runners without ffmpeg, minimal virtualenvs/conda envs, Windows installs where ffmpeg was downloaded but not added to PATH.

Related errors

• An error occurs with ffprobe (see ffprobe output below) {}
• No stream was found with ffprobe
• output directory does not exists: {directory}
• FFMPEG error: {process.stderr.read()}
• Configuration file {descriptor} not found

AI-assisted analysis of deezer/spleeter@c8854001ac (2026-08-28). Data as JSON: /api/errors/c74fbf207e7b16d8. Report an issue: GitHub.