demucs-node

Node.js/TypeScript wrapper for Meta's Demucs audio source separation tool. Separate any song into vocals, drums, bass, and other stems with a simple function call.

Prerequisites

Demucs must be installed on your system:

pip install demucs torchcodec

Install

npm install demucs-node

Quick Start

import { separate } from "demucs-node";

const result = await separate("song.mp3");

console.log(result.stems);
// {
//   vocals: "/absolute/path/to/separated/htdemucs/song/vocals.wav",
//   drums:  "/absolute/path/to/separated/htdemucs/song/drums.wav",
//   bass:   "/absolute/path/to/separated/htdemucs/song/bass.wav",
//   other:  "/absolute/path/to/separated/htdemucs/song/other.wav"
// }

API

separate(input, options?)

Separates audio file(s) into stems. Returns a CancellablePromise.

// Single file
const result = await separate("song.mp3");

// Batch
const results = await separate(["song1.mp3", "song2.wav"]);

// With options
const result = await separate("song.mp3", {
  model: "htdemucs_ft",     // Model to use (default: "htdemucs")
  outputDir: "./output",     // Output directory (default: "separated" next to input)
  outputFormat: "mp3",       // "wav" | "mp3" | "flac" (default: "wav")
  twoStems: true,            // Vocals + accompaniment only (default: false)
  device: "cpu",             // "cpu" | "cuda" (default: auto)
  onProgress: (p) => {       // Progress callback (0-100)
    console.log(`${p}%`);
  },
});

// Cancellation
const job = separate("long-song.wav");
job.cancel(); // Sends SIGTERM, rejects with AbortError

checkDemucs()

Checks if Demucs is installed and returns version info.

import { checkDemucs } from "demucs-node";

const info = await checkDemucs();
// { available: true, version: "4.0.1" }
// or
// { available: false, installInstructions: "Install Demucs with: pip install demucs" }

Options

| Option | Type | Default | Description | |---|---|---|---| | model | string | "htdemucs" | Demucs model (htdemucs, htdemucs_ft, mdx, mdx_extra) | | outputDir | string | "separated" | Output directory for stems | | outputFormat | string | "wav" | Output format (wav, mp3, flac) | | twoStems | boolean | false | Two-stem mode (vocals + accompaniment) | | device | string | auto | Force "cpu" or "cuda" | | onProgress | function | — | Progress callback receiving 0–100 |

Result

interface SeparationResult {
  inputFile: string;              // Absolute path to input
  stems: Record<string, string>;  // Stem name → absolute path
  model: string;                  // Model used
}

Supported Formats

Input: .wav, .mp3, .flac, .ogg Output: .wav, .mp3, .flac

License

MIT