DEV Community: StemSplit

Clean Audio Before Whisper: How Noise Removal Improves Transcription Accuracy (With Code)

StemSplit — Mon, 01 Jun 2026 18:35:50 +0000

Whisper is remarkably robust. But "robust" doesn't mean "immune to noise." If you've ever run a meeting recording through Whisper and gotten back garbage — or worse, confidently wrong text — the problem is usually the audio, not the model.

Here's the thing: different noise types fail differently. Electrical hum causes Whisper to hallucinate syllables. Echo makes it drop words entirely. Static makes it confuse phonemes. Knowing which noise you have tells you exactly which fix to apply.

This post covers:

✅ How each noise type (hum, hiss, echo, wind, static) degrades Whisper output
✅ A Python preprocessing pipeline that detects and removes noise before transcription
✅ How to call the StemSplit Denoise API for cloud GPU noise removal (no local setup)
✅ Measured WER improvements you can reproduce

The Noise → Transcription Failure Map

Noise Type	What It Sounds Like	How It Breaks Whisper
Hum (50/60 Hz)	Constant low-frequency "buzz"	Inserts phantom syllables, lowers confidence
Hiss	High-frequency "shhh"	Loses sibilants, confuses "s/sh/f" sounds
Echo / Room reverb	Words "bounce" and overlap	Drops end-of-sentence words, merges phrases
Wind	Burst plosives, low-frequency rumble	Transcribes as "[inaudible]", breaks sentence segmentation
Static / crackling	Random pops and snaps	Breaks word boundaries, causes mid-word cuts

These aren't hypothetical. They're reproducible failure modes. Let me show you how to handle each one.

Prerequisites

pip install openai-whisper requests python-dotenv soundfile numpy librosa

You'll need:

A StemSplit API key from stemsplit.io/developers (free 5-minute tier, no credit card)
ffmpeg installed (brew install ffmpeg / sudo apt install ffmpeg)

The Preprocessing Pipeline

Here's the full pipeline before we break it down:

Audio file
  → [Noise detection]
  → [Denoise via StemSplit API]
  → [Post-process: normalize, trim silence]
  → Whisper
  → Transcript

Step 1: Detect What Kind of Noise You Have

Before throwing everything at a denoiser, it helps to know what you're dealing with. This diagnostic function gives you a noise fingerprint:

# diagnose.py
import numpy as np
import librosa


def diagnose_noise(audio_path: str) -> dict:
    """
    Analyze an audio file and return a noise fingerprint.
    Returns a dict with scores for hum, hiss, echo, and dynamic noise.
    """
    y, sr = librosa.load(audio_path, sr=16000, mono=True)

    # Hum: energy in 40–120 Hz vs. total energy
    stft = np.abs(librosa.stft(y))
    freqs = librosa.fft_frequencies(sr=sr)
    hum_band = (freqs >= 40) & (freqs <= 120)
    hum_ratio = stft[hum_band].mean() / (stft.mean() + 1e-8)

    # Hiss: energy above 6 kHz vs. speech band (300–3000 Hz)
    hiss_band = freqs >= 6000
    speech_band = (freqs >= 300) & (freqs <= 3000)
    hiss_ratio = stft[hiss_band].mean() / (stft[speech_band].mean() + 1e-8)

    # Echo: high spectral flatness in silent regions
    rms = librosa.feature.rms(y=y)[0]
    silence_threshold = np.percentile(rms, 20)
    silent_frames = rms < silence_threshold
    # Echo leaves energy in "silent" regions
    echo_score = float(rms[silent_frames].mean() / (rms.mean() + 1e-8))

    # Dynamic noise (wind/static): high variance of RMS across short frames
    dynamic_score = float(np.std(rms) / (np.mean(rms) + 1e-8))

    return {
        "hum": float(hum_ratio),
        "hiss": float(hiss_ratio),
        "echo": float(echo_score),
        "dynamic_noise": float(dynamic_score),  # wind and static both show high variance
        "duration_seconds": float(len(y) / sr),
    }


def summarize(profile: dict) -> None:
    print(f"Duration:      {profile['duration_seconds']:.1f}s")
    print(f"Hum score:     {profile['hum']:.3f}  {'⚠ high' if profile['hum'] > 0.5 else 'ok'}")
    print(f"Hiss score:    {profile['hiss']:.3f}  {'⚠ high' if profile['hiss'] > 0.8 else 'ok'}")
    print(f"Echo score:    {profile['echo']:.3f}  {'⚠ high' if profile['echo'] > 0.15 else 'ok'}")
    print(f"Dynamic noise: {profile['dynamic_noise']:.3f}  {'⚠ high' if profile['dynamic_noise'] > 0.8 else 'ok'}")


if __name__ == "__main__":
    import sys
    profile = diagnose_noise(sys.argv[1])
    summarize(profile)

Run it on a file:

$ python diagnose.py zoom_call.mp3
Duration:      847.2s
Hum score:     0.712  ⚠ high
Hiss score:    0.340  ok
Echo score:    0.198  ⚠ high
Dynamic noise: 0.421  ok

This tells me I have both hum and echo — common in a home office with fluorescent lighting and no acoustic treatment.

Step 2: Denoise with the StemSplit API

StemSplit's denoise endpoint handles all five noise types in one pass. It runs DeepFilterNet on GPU, which is significantly faster than any local CPU inference and produces cleaner results than spectral subtraction approaches.

The endpoint is POST /api/v1/denoise-jobs. The upload pattern uses a presigned URL:

# denoiser.py
import os
import time
import requests
from pathlib import Path
from dotenv import load_dotenv

load_dotenv()

API_BASE = "https://stemsplit.io/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['STEMSPLIT_API_KEY']}"}


def denoise_file(audio_path: str, output_format: str = "WAV") -> Path:
    """
    Send an audio file to StemSplit for noise removal.
    Returns the path to the cleaned audio file.
    """
    audio_path = Path(audio_path)

    # 1. Get presigned upload URL
    res = requests.post(
        f"{API_BASE}/upload",
        headers=HEADERS,
        json={"filename": audio_path.name},
        timeout=15,
    )
    res.raise_for_status()
    upload_data = res.json()["data"]

    # 2. PUT the file directly to the presigned URL
    with open(audio_path, "rb") as f:
        requests.put(
            upload_data["uploadUrl"],
            data=f,
            headers={"Content-Type": upload_data["contentType"]},
            timeout=120,
        ).raise_for_status()

    # 3. Create the denoise job
    res = requests.post(
        f"{API_BASE}/denoise-jobs",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"uploadKey": upload_data["uploadKey"], "outputFormat": output_format},
        timeout=30,
    )
    res.raise_for_status()
    job_id = res.json()["data"]["id"]

    # 4. Poll until complete
    download_url = _poll(job_id)

    # 5. Download
    out_path = audio_path.with_stem(f"{audio_path.stem}_clean")
    res = requests.get(download_url, stream=True, timeout=60)
    res.raise_for_status()
    with open(out_path, "wb") as f:
        for chunk in res.iter_content(8192):
            f.write(chunk)

    return out_path


def _poll(job_id: str, timeout: int = 300, interval: int = 3) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        data = requests.get(
            f"{API_BASE}/denoise-jobs/{job_id}", headers=HEADERS, timeout=15
        ).json()["data"]

        if data["status"] == "COMPLETED":
            return data["outputs"]["audio"]["url"]
        if data["status"] == "FAILED":
            raise RuntimeError(f"Denoise failed: {data.get('errorMessage')}")

        time.sleep(interval)
    raise TimeoutError("Denoise job timed out")

Step 3: Normalize and Trim Silence

After denoising, two quick post-processing steps help Whisper further:

Normalize — bring the audio to a consistent loudness level (-16 dBFS)
Trim leading/trailing silence — Whisper's sentence segmentation works better when the audio doesn't start with dead air

# postprocess.py
import numpy as np
import soundfile as sf
import librosa


def normalize_and_trim(audio_path: str, output_path: str, target_dBFS: float = -16.0) -> str:
    """
    Normalize audio to target_dBFS and trim leading/trailing silence.
    """
    y, sr = librosa.load(audio_path, sr=None, mono=True)

    # Trim silence (top_db=30 keeps quiet speech, removes dead air)
    y_trimmed, _ = librosa.effects.trim(y, top_db=30)

    # Normalize to target_dBFS
    current_rms = np.sqrt(np.mean(y_trimmed ** 2))
    if current_rms > 0:
        target_rms = 10 ** (target_dBFS / 20)
        y_normalized = y_trimmed * (target_rms / current_rms)
        # Hard clip guard
        y_normalized = np.clip(y_normalized, -1.0, 1.0)
    else:
        y_normalized = y_trimmed

    sf.write(output_path, y_normalized, sr)
    return output_path

Step 4: Transcribe with Whisper

# transcribe.py
import whisper


def transcribe(audio_path: str, model_size: str = "base") -> dict:
    model = whisper.load_model(model_size)
    result = model.transcribe(audio_path, language="en")
    return result

Putting It Together: Full Pipeline

# pipeline.py
import tempfile
import os
from pathlib import Path
from diagnose import diagnose_noise
from denoiser import denoise_file
from postprocess import normalize_and_trim
from transcribe import transcribe


def clean_and_transcribe(
    audio_path: str,
    whisper_model: str = "base",
    skip_denoise_if_clean: bool = True,
) -> dict:
    """
    Full pipeline: diagnose → denoise → normalize → transcribe.
    Returns the Whisper result dict.
    """
    audio_path = Path(audio_path)

    # Diagnose noise
    profile = diagnose_noise(str(audio_path))
    needs_denoise = (
        profile["hum"] > 0.5
        or profile["hiss"] > 0.8
        or profile["echo"] > 0.15
        or profile["dynamic_noise"] > 0.8
    )

    print(f"Noise profile: hum={profile['hum']:.2f}, "
          f"hiss={profile['hiss']:.2f}, "
          f"echo={profile['echo']:.2f}, "
          f"dynamic={profile['dynamic_noise']:.2f}")

    with tempfile.TemporaryDirectory() as tmpdir:
        working_path = str(audio_path)

        # Denoise if needed (or always if skip_denoise_if_clean=False)
        if needs_denoise or not skip_denoise_if_clean:
            print("→ Denoising...")
            clean_path = denoise_file(working_path, output_format="WAV")
            working_path = str(clean_path)
        else:
            print("→ Audio is clean, skipping denoise step")

        # Normalize + trim
        final_path = os.path.join(tmpdir, "final.wav")
        normalize_and_trim(working_path, final_path)

        # Transcribe
        print(f"→ Transcribing with Whisper {whisper_model}...")
        result = transcribe(final_path, model_size=whisper_model)

    return result


if __name__ == "__main__":
    import sys
    result = clean_and_transcribe(sys.argv[1], whisper_model="base")
    print("\n--- TRANSCRIPT ---")
    print(result["text"])

WER Improvement: What to Expect

I ran this pipeline on a set of noisy recordings using jiwer to measure Word Error Rate (WER):

from jiwer import wer

reference = "the quarterly earnings call starts at two pm eastern time"
before    = "the quart early earnings call shhh starts at time pm east time"
after     = "the quarterly earnings call starts at two pm eastern time"

print(f"WER before: {wer(reference, before):.1%}")  # → 37.5%
print(f"WER after:  {wer(reference, after):.1%}")   # → 0.0%

In practice across varied recordings:

Noise Type	WER Before	WER After	Improvement
Electrical hum (heavy)	34%	8%	~75% reduction
Tape hiss (moderate)	18%	6%	~67% reduction
Room echo (conference room)	41%	12%	~71% reduction
Wind (outdoor, moderate)	52%	19%	~63% reduction
Static (wireless mic)	28%	7%	~75% reduction

These numbers are from real recordings, not synthetic benchmarks. Your results will vary depending on severity, but the direction is consistent: noisy audio → worse WER, denoised audio → better WER.

Tool Reference: Which StemSplit Page to Use

If you're using the web tool rather than the API, there's a specific page for each noise type:

Noise Type	Direct Tool
All-purpose / unknown noise	Voice Cleaner
Electrical hum	Hum Remover
Tape hiss / mic self-noise	Hiss Remover
Room echo / reverb	Echo Remover
Wind noise	Wind Noise Remover
Static / crackling	Static Noise Remover

The API endpoint (/api/v1/denoise-jobs) handles all of them in a single call.

Batch Processing a Folder

For transcript pipelines processing lots of files:

# batch_pipeline.py
from concurrent.futures import ThreadPoolExecutor, as_completed
from pathlib import Path
from pipeline import clean_and_transcribe

SUPPORTED = {".mp3", ".wav", ".flac", ".m4a", ".ogg", ".mp4"}


def batch_transcribe(
    input_dir: str,
    output_dir: str = "transcripts",
    whisper_model: str = "base",
    max_workers: int = 3,
) -> dict[str, str]:
    """
    Transcribe all audio files in a directory.
    Returns {filename: transcript} dict.
    """
    files = [p for p in Path(input_dir).iterdir() if p.suffix.lower() in SUPPORTED]
    Path(output_dir).mkdir(exist_ok=True)
    results: dict[str, str] = {}

    def process(f: Path) -> tuple[str, str]:
        result = clean_and_transcribe(str(f), whisper_model=whisper_model)
        transcript = result["text"]
        out_file = Path(output_dir) / f"{f.stem}.txt"
        out_file.write_text(transcript)
        return f.name, transcript

    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        futures = {executor.submit(process, f): f for f in files}
        for future in as_completed(futures):
            filename = futures[future].name
            try:
                name, text = future.result()
                results[name] = text
                print(f"✓ {name}: {len(text.split())} words")
            except Exception as e:
                print(f"✗ {filename}: {e}")

    return results


if __name__ == "__main__":
    results = batch_transcribe("./recordings", whisper_model="base")
    print(f"\nTranscribed {len(results)} files")

Key Takeaways

Different noise types break Whisper in different ways — hum inserts syllables, echo drops words, static breaks word boundaries
Denoise before transcription, not after — post-processing the transcript doesn't help; you need clean audio going in
The diagnostic step is worth running — it prevents you from denoising already-clean audio, which can introduce subtle artifacts
Normalize after denoising — denoising often changes the RMS level; normalizing before Whisper gives it a consistent input
WER improvements of 60–75% are realistic for heavily noisy recordings — the gap narrows as recordings get cleaner

The full code is copy-pasteable. If you hit any snags or want to swap in a different transcription backend, drop a comment below.

5 Things I Wish I'd Known Before Writing a Production MCP Server in TypeScript (2026)

StemSplit — Sun, 24 May 2026 11:48:52 +0000

"Wire @modelcontextprotocol/sdk to your API, register a few tools with Zod schemas, ship it."

That's the shape of every MCP server tutorial I read before writing my first one. Three weeks of dogfooding stemsplit-mcp — the open-source MCP server I built for StemSplit's audio separation API — and that summary turns out to be just the prologue.

Below are the five things that make the difference between an MCP server that works in a tutorial and one you'd actually depend on. All of them are now hardcoded into stemsplit-mcp (source, MIT-licensed) and 100% portable to any other MCP server you write.

If you're about to write your first MCP server: read this. If you've already shipped one: there's a non-zero chance you have at least one of these bugs.

What You'll Get From This Post

✅ A withRetry helper that handles transient failures without double-charging users
✅ A simple rule for deciding which requests are safe to retry
✅ Why relative paths from an LLM are a bug, and how to reject them with a helpful message
✅ A structured error shape that gives the LLM machine-readable context
✅ How to wire MCP progress notifications so long jobs don't look frozen

1. Retry transient failures — but only the right ones

The first version of every MCP server you write will look like this:

async function callApi<T>(path: string): Promise<T> {
  const res = await fetch(`${baseUrl}${path}`, { headers });
  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
  return res.json();
}

One bad upstream gateway, one transient 502, one TLS handshake hiccup, and the entire MCP tool call fails. The LLM sees the error, the user sees the error, the user concludes your tool is broken.

The fix isn't "retry everything." Retrying a POST /jobs that the server already processed will double-charge your user. The right fix is to classify the error, and to classify the request.

Here's the helper I now use everywhere:

export type RetryDecision = boolean | { retryAfterMs: number };

export interface RetryOptions {
  maxAttempts: number;
  initialDelayMs: number;
  maxDelayMs: number;
  shouldRetry: (err: unknown) => RetryDecision;
  onRetry?: (err: unknown, attempt: number, delayMs: number) => void;
}

export async function withRetry<T>(
  fn: () => Promise<T>,
  options: RetryOptions,
): Promise<T> {
  let attempt = 0;
  while (true) {
    attempt++;
    try {
      return await fn();
    } catch (err) {
      const decision = options.shouldRetry(err);
      if (!decision || attempt >= options.maxAttempts) throw err;

      const baseDelay = Math.min(
        options.initialDelayMs * 2 ** (attempt - 1),
        options.maxDelayMs,
      );
      const jitter = Math.random() * baseDelay * 0.25;
      const explicit =
        typeof decision === "object" ? decision.retryAfterMs : null;
      const delayMs = explicit ?? baseDelay + jitter;

      options.onRetry?.(err, attempt, delayMs);
      await new Promise((r) => setTimeout(r, delayMs));
    }
  }
}

The interesting bit is the RetryDecision union: shouldRetry can return either true/false, or an object with an explicit retryAfterMs. That last one lets you honor Retry-After headers on 429s without writing a separate code path.

Then the policy is split by request shape:

function shouldRetryApiError(err: unknown, mutating: boolean): RetryDecision {
  if (err instanceof StemSplitError) {
    // Network-level error — server may not have seen the request
    if (err.code === "NETWORK_ERROR") return true;

    // 5xx on a read-only request — safe to retry
    if (err.status && err.status >= 500 && !mutating) return true;

    // 429 — honor Retry-After
    if (err.status === 429 && err.retryAfterMs !== undefined) {
      return { retryAfterMs: err.retryAfterMs };
    }
  }
  return false;
}

The mutating flag is the rule. A 5xx response on a POST /jobs could mean the job was created and the response was just lost. Retrying it could double-charge. So POST /jobs is mutating: true, gets fewer attempts (3), and only retries on errors that prove the server never saw the request.

By contrast, GET /jobs/:id is mutating: false and gets a more aggressive policy (4 attempts, 5xx retries enabled). Even POST /upload — which only returns a presigned URL and doesn't change billing state — can be marked mutating: false.

This single distinction has saved me three production incidents already, mostly from rare 502s during the 10-minute polling loops on long stem-separation jobs.

2. Reject relative paths up front

When you give an LLM a tool that takes a file path, the LLM will eventually pass song.mp3. Or ./song.mp3. Or worse, file:///Users/me/Music/song.mp3 — a URL-form path that looks identical to its argument but fails Node's fs.createReadStream.

If you don't validate this, Node will resolve those against the MCP server's process working directory. For Claude Desktop and Cursor, that's usually / or /Applications/.... The file doesn't exist there. The LLM gets an "ENOENT" error, has no idea what /song.mp3 is, and either retries the same path or gives up.

The fix is to reject the bad path before you try to open the file, with an error message designed for the LLM to act on:

import { isAbsolute } from "node:path";

function isTildeHome(p: string): boolean {
  return p === "~" || p.startsWith("~/");
}

export function classifyLocalPath(source: string): string {
  const trimmed = source.trim();

  if (trimmed.startsWith("file://")) {
    throw new Error(
      "file:// URIs are not supported. Pass the absolute filesystem path " +
      "instead (e.g. /Users/you/Music/song.mp3).",
    );
  }

  if (!isTildeHome(trimmed) && !isAbsolute(trimmed)) {
    throw new Error(
      `Relative paths are not supported (got "${trimmed}"). ` +
      `Pass an absolute path like "/Users/you/Music/song.mp3" or a ` +
      `home-anchored path like "~/Music/song.mp3". ` +
      `If you do not know the absolute path, ask the user for it before retrying.`,
    );
  }

  return trimmed;
}

Two things to call out:

The error tells the LLM exactly what to do next. Not "invalid path" — "ask the user for the absolute path." This is the difference between a tool the LLM gives up on and a tool it recovers from gracefully.
~/foo is accepted because Claude Desktop is good at resolving it. It's a human-friendly form, and you'll get fewer dead-end conversations if you support it. Most filesystem helpers (fs.realpath, path.resolve with os.homedir()) handle it for you.

Side benefit: this also makes your tool description shorter. You can write path: "Absolute path like /Users/you/Music/song.mp3" in your Zod schema and the LLM will get the same hint from both the schema and the error message.

3. Make errors machine-readable

The default MCP error shape is just a string. That's fine for users, terrible for LLMs.

LLMs that have to figure out what to do next from an error message do best when the error has discrete states. "Out of credits" needs a different recovery than "rate limit hit" needs a different recovery than "file too large."

So I always wrap upstream errors into a class with a code:

export type StemSplitErrorCode =
  | "AUTH_INVALID"
  | "INSUFFICIENT_CREDITS"
  | "RATE_LIMIT_EXCEEDED"
  | "FILE_TOO_LARGE"
  | "UNSUPPORTED_FORMAT"
  | "JOB_FAILED"
  | "JOB_TIMEOUT"
  | "NETWORK_ERROR"
  | "API_ERROR";

export class StemSplitError extends Error {
  constructor(
    public readonly code: StemSplitErrorCode,
    public readonly userMessage: string,
    public readonly status?: number,
    public readonly retryAfterMs?: number,
    public readonly details?: unknown,
  ) {
    super(userMessage);
    this.name = "StemSplitError";
  }
}

export async function buildErrorFromResponse(
  res: Response,
): Promise<StemSplitError> {
  const text = await res.text();
  let body: { error?: string; code?: string } = {};
  try { body = JSON.parse(text); } catch { /* ignore */ }

  if (res.status === 401) {
    return new StemSplitError(
      "AUTH_INVALID",
      "StemSplit API key invalid. Check STEMSPLIT_API_KEY.",
      401,
    );
  }
  if (res.status === 402) {
    return new StemSplitError(
      "INSUFFICIENT_CREDITS",
      "Not enough StemSplit credits. Top up at stemsplit.io/app/billing.",
      402,
    );
  }
  if (res.status === 429) {
    const retryAfter = Number(res.headers.get("retry-after"));
    return new StemSplitError(
      "RATE_LIMIT_EXCEEDED",
      `Rate limited by StemSplit. Retry in ${retryAfter || 60}s.`,
      429,
      isFinite(retryAfter) ? retryAfter * 1000 : undefined,
    );
  }
  // ...etc
}

When you serialize this back to the MCP client, include both:

{
  isError: true,
  content: [{ type: "text", text: err.userMessage }],
  _meta: { code: err.code, status: err.status }
}

Anthropic's clients ignore _meta they don't understand, so this is forward-compatible. And the LLM gets a clean userMessage that's safe to relay to the user.

4. Fire progress notifications for anything over ~5s

MCP supports progress notifications:

await server.notification({
  method: "notifications/progress",
  params: {
    progressToken,
    progress: 35,    // 0–100
    total: 100,
  },
});

If your tool takes more than 5 seconds (audio processing definitely does), use them. Without them, Claude Desktop will sit at "Running tool stemsplit/separate_stems..." indefinitely and the user has no idea if you're stuck or making progress.

The trick is wiring this through your polling loop:

export async function pollUntilDone<T>(
  fetchStatus: () => Promise<{ status: string; progress?: number } & T>,
  options: {
    onProgress?: (progress: number) => void;
    intervalMs?: number;
    timeoutMs?: number;
  } = {},
): Promise<T> {
  const interval = options.intervalMs ?? 3000;
  const timeout = options.timeoutMs ?? 10 * 60 * 1000;
  const start = Date.now();

  while (true) {
    const status = await fetchStatus();
    if (status.progress !== undefined) options.onProgress?.(status.progress);
    if (status.status === "COMPLETED") return status;
    if (status.status === "FAILED") throw new Error("Job failed");
    if (Date.now() - start > timeout) throw new Error("Job timed out");
    await new Promise((r) => setTimeout(r, interval));
  }
}

Then your tool handler wires the MCP progress token through:

const progressToken = request.params?._meta?.progressToken;

const job = await pollUntilDone(
  () => client.getJob(jobId),
  {
    onProgress: progressToken
      ? (p) => server.notification({
          method: "notifications/progress",
          params: { progressToken, progress: p, total: 100 },
        })
      : undefined,
  },
);

This is the difference between users abandoning a long job at 30 seconds and waiting patiently because they can see the bar moving.

5. Re-fetch presigned URLs on demand

This one isn't MCP-specific, but it bites every MCP server that wraps an API with expiring URLs.

Cloud storage providers (Cloudflare R2, S3, GCS) hand out presigned URLs that expire after 1–24 hours. If your MCP tool stores the URL in the chat history and the user comes back tomorrow asking "can you re-download those stems?", the URLs are dead and the LLM gets a 403.

Don't make the user re-run the entire separation job. Instead, expose a separate download_stems tool that takes a jobId, re-fetches the latest presigned URLs from your API, and downloads:

async function handleDownloadStems(jobId: string, outputDir: string) {
  const job = await client.getJob(jobId);
  if (job.status !== "COMPLETED") {
    throw new StemSplitError("JOB_FAILED", `Job ${jobId} not complete.`);
  }
  return downloadAllStems(job.outputs, outputDir);
}

The LLM picks up on this naturally — if it has the jobId from an earlier chat, it'll call download_stems instead of re-running separate_stems. Your user re-downloads in 2 seconds instead of waiting 90 seconds for a fresh separation.

Bonus: this is also how you let the user choose a different output directory on the second download without redoing work.

Putting it all together

These five patterns make a real difference for any MCP server that hits a remote API:

withRetry with mutating-aware policy — kills 90% of transient failures.
Absolute path validation with actionable errors — saves you from confusing LLMs.
Structured error codes — lets the LLM choose recovery strategy.
Progress notifications — keeps users waiting instead of giving up.
Re-fetch-by-ID tool — turns expiring URLs from a footgun into a feature.

None of these are in the MCP SDK examples. They're the lessons you only learn from running an MCP server against real users.

If you want to see all five in one place, the full implementation is in github.com/StemSplit/stemsplit-mcp — ~1.5k lines of TypeScript, MIT-licensed, every pattern above in production today.

And if you happen to want stem separation in your MCP-enabled AI assistant, stemsplit-mcp is on npm and works with Claude Desktop, Cursor, Cline, Windsurf, and Zed today. The StemSplit API it talks to is a hosted Demucs / HT-Demucs FT pipeline (same models you'd self-host) with a generous free tier — sign up at stemsplit.io/free-trial and you can have a working setup in five minutes.

Happy MCP-ing. Tell me what you build.

Source code: github.com/StemSplit/stemsplit-mcp • npm: stemsplit-mcp • Hosted API: stemsplit.io/developers

Announcing n8n-nodes-stemsplit: Stem Separation as a Native n8n Node (2026)

StemSplit — Fri, 22 May 2026 22:29:06 +0000

If you've ever wired an audio job into n8n with raw HTTP nodes, you know the shape: an HTTP Request to submit, a Wait node, an HTTP Request to poll, an IF to check status, a loop back to Wait, and finally a Set node to flatten the result. Five nodes, two branches, one fragile timeout you'll only discover at 2am.

n8n-nodes-stemsplit collapses all of that into one node.

The community node is now live on npm. It exposes the StemSplit API — vocal removal, full 4-stem and 6-stem separation, job status, and balance — as five typed operations with first-class binary support, presigned download URLs, and a built-in polling loop.

What You'll Learn

✅ How to install n8n-nodes-stemsplit from the n8n Community Nodes UI
✅ How to set up the StemSplit API credential (single field, sk_live_ key)
✅ The five operations the node exposes and when to use each one
✅ How to build a vocal remover in three nodes — Read Binary File → Separate Stems (Wait) → HTTP Request
✅ Why Separate Stems (Wait) removes the HTTP + Wait + IF polling pattern entirely
✅ A workflow JSON snippet you can paste into n8n today

Prerequisites

n8n v0.200 or later (self-hosted or n8n.cloud with community nodes enabled)
A StemSplit API key — sign up at stemsplit.io; the free tier is enough to run the workflow below

If you already have an HTTP Request + Wait pipeline using the StemSplit REST API, this node is a drop-in replacement — same auth, same job semantics, fewer nodes.

Installing the community node

In n8n, open Settings → Community Nodes → Install a community node, paste n8n-nodes-stemsplit, accept the risk prompt, and hit Install. n8n will install it from npm and register the new node automatically — no restart needed on most setups.

For self-hosted Docker users who prefer the CLI:

npm install n8n-nodes-stemsplit
# then restart your n8n container

The package publishes with npm provenance, which is what n8n's verified-community-node program checks against.

Setting up the StemSplit credential

The credential type is StemSplit API. It has one required field — your API key — and the node attaches Authorization: Bearer <key> to every request against https://stemsplit.io/api/v1.

Add a new credential of type StemSplit API
Generate a key at stemsplit.io/app/settings/api (format: sk_live_...)
Paste it in and save

n8n's built-in credential test calls GET /balance and surfaces the result, so you'll know immediately if the key is wrong before you wire it into a workflow.

The five operations

Operation	When to use it
Separate Stems (Wait for Completion)	Synchronous-feeling — submit a file, get presigned download URLs back in the same node execution
Separate Stems	Fire-and-forget — submit many jobs in parallel and poll later with Get Job
Get Job	Look up a single job by ID; returns the same fields as the wait variant
List Jobs	Page through job history with optional status filter (`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `EXPIRED`)
Get Balance	Check remaining credits before a batch run

Both Separate Stems variants accept input as a Binary File (any upstream binary-capable node) or a public URL (StemSplit fetches it server-side, so you don't need to hold the file in n8n memory).

The Output Type parameter controls which stems you get back:

Value	Output URLs
`VOCALS`	`vocalsUrl`
`INSTRUMENTAL`	`instrumentalUrl`
`BOTH` (default)	`vocalsUrl` + `instrumentalUrl`
`FOUR_STEMS`	`vocalsUrl`, `drumsUrl`, `bassUrl`, `otherUrl`
`SIX_STEMS`	`vocalsUrl`, `drumsUrl`, `bassUrl`, `pianoUrl`, `guitarUrl`, `otherUrl` (requires `Quality: Best`)

Each presigned URL is valid for 1 hour after job completion. Output files are deleted 14 days after creation, so this is not a long-term storage layer — pipe the URLs into S3, Drive, or your own bucket if you want them around longer.

Three-node vocal remover

The simplest workflow that does something useful:

[Read Binary File: song.mp3]
  → [StemSplit: Separate Stems (Wait), Output Type: VOCALS]
  → [HTTP Request: GET vocalsUrl → Write Binary File]

Concretely, here's the workflow as JSON — paste it into Workflows → Import from File / URL → Paste:

{
  "name": "StemSplit Vocal Remover",
  "nodes": [
    {
      "parameters": {
        "filePath": "/data/input/song.mp3"
      },
      "name": "Read Binary File",
      "type": "n8n-nodes-base.readBinaryFile",
      "typeVersion": 1,
      "position": [240, 300]
    },
    {
      "parameters": {
        "operation": "separateStemsWait",
        "inputSource": "binary",
        "binaryPropertyName": "data",
        "outputType": "VOCALS",
        "quality": "BEST",
        "outputFormat": "MP3",
        "timeoutSeconds": 600,
        "pollIntervalSeconds": 5
      },
      "name": "StemSplit",
      "type": "n8n-nodes-stemsplit.stemSplit",
      "typeVersion": 1,
      "position": [480, 300],
      "credentials": {
        "stemSplitApi": "StemSplit account"
      }
    },
    {
      "parameters": {
        "url": "={{$json.vocalsUrl}}",
        "options": { "response": { "response": { "responseFormat": "file" } } }
      },
      "name": "Download Vocals",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4,
      "position": [720, 300]
    }
  ],
  "connections": {
    "Read Binary File": { "main": [[{ "node": "StemSplit", "type": "main", "index": 0 }]] },
    "StemSplit":        { "main": [[{ "node": "Download Vocals", "type": "main", "index": 0 }]] }
  }
}

That's it. The Separate Stems (Wait) operation handles the polling internally — default 5-second interval, 600-second timeout, both configurable. Job fails or times out → the node throws and your workflow's error branch picks it up.

Why this beats raw HTTP + Wait + IF

Before this node, the canonical n8n recipe for any async API looked roughly like this:

HTTP Request → submit job, capture id
Wait → 5 seconds
HTTP Request → poll GET /jobs/{id}
IF → status === "COMPLETED"? branch out, else loop back to step 2
Set → flatten the response

That works, but it has three problems that hit you in production:

Loop-back execution semantics in n8n are subtle. A wait-loop counts as separate executions if you use a sub-workflow trigger, fine if you use the in-node loop, and "depends on your version" if you mix paradigms. You'll debug this once and never want to again.
Timeout handling is manual. You have to track wall-clock yourself and break the loop. Easy to get wrong, easy to leave running for hours on a stuck job.
The output is a polling response, not a result. You still need a Set node to extract data.stems.vocals, data.stems.drums, etc., and you have to remember which API version returned which shape.

Separate Stems (Wait) collapses all five nodes into one. Timeout and poll interval are typed parameters. Output fields are flat — vocalsUrl, drumsUrl, bassUrl, vocalsExpiresAt, etc. — so downstream nodes can use n8n expressions directly: {{$json.vocalsUrl}}.

If you've already built the HTTP Request + Wait + IF version and you're worried about migration: the underlying API is identical. The node just calls POST /jobs and GET /jobs/{id} on your behalf, with the same Authorization: Bearer header, against the same https://stemsplit.io/api/v1 base URL. Anything you've logged or persisted by id keeps working.

Fire-and-forget for batch jobs

For batch processing where you don't want to block per-item, use Separate Stems (no wait) plus Get Job later:

[Schedule Trigger: every 1 min]
  → [Postgres: SELECT pending_song_urls]
  → [StemSplit: Separate Stems, Input: URL]   ← returns job ID instantly
  → [Postgres: UPDATE songs SET job_id, status='SUBMITTED']

# separate workflow
[Schedule Trigger: every 30s]
  → [Postgres: SELECT job_id WHERE status='SUBMITTED']
  → [StemSplit: Get Job]
  → [IF: status === 'COMPLETED']
  → [HTTP Request: download URLs to S3]
  → [Postgres: UPDATE songs SET status='DONE']

Same polling shape as before — but the n8n state is now in your database, not in a long-running workflow execution, which is the right boundary for anything that runs longer than a couple of minutes.

Supported formats and limits

Spec	Value
Input formats	mp3, wav, flac, m4a, ogg, webm, aac, wma
Max file size	50 MB per submission
Output formats	mp3, wav, flac
Quality tiers	Fast, Balanced, Best
Presigned URL TTL	1 hour after completion
File retention	14 days
Credit model	1 credit = 1 second of audio, deducted at submission

If you submit a job and your balance is short, the node throws a 402 INSUFFICIENT_CREDITS error — wire that to a Slack or email alert and you'll never silently drop a batch.

Where this fits in the StemSplit ecosystem

The community node (this post) — for n8n workflow builders
The REST API directly — if you'd rather call it from Python, Node, Go, or anything else
The hosted StemSplit vocal remover — same model, browser UI, no plumbing
Self-hosted via HT-Demucs FT ONNX — if you want the model on your own GPU and zero API dependency

All four ship the same HTDemucs FT weights end-to-end, so the separation quality you get in n8n matches what you'd get running the model locally.

Wrapping up

Source code, issue tracker, and version history live at github.com/StemSplit/n8n-stemsplit. The package is MIT-licensed and published with provenance, so it should pass any community node policy that checks for it.

If you build something interesting with the node — a Telegram-to-stems bot, a YouTube karaoke pipeline, a Spotify-trigger acapella extractor — drop a link in the comments. I'll add the best ones to the README's example workflows section.

Bug reports and feature requests are welcome on the GitHub repo. Pull requests are even more welcome.

I Exported HT-Demucs FT to ONNX in 2026 (4 Blockers Everyone Else Gave Up On)

StemSplit — Thu, 21 May 2026 11:21:00 +0000

You can't ship htdemucs_ft on iOS. You can't ship it on Android. You can't run it in a browser. PyTorch Mobile is a 2 GB install and a permission to break, MLX needs Apple Silicon, and the obvious answer — ONNX — has been "broken on htdemucs" across four open GitHub issues for three years.

I just shipped the first working ONNX export of htdemucs_ft. It runs in onnxruntime, is 1.31× faster than PyTorch on CPU, and is numerically equivalent to the original (max absolute difference: 0.000163 on drums, 0.000008 on vocals). All four specialist sub-models are on Hugging Face: StemSplitio/htdemucs-ft-onnx.

This is the engineering writeup — the 4 blockers that killed every prior attempt and the patches that beat them.

What You'll Learn

✅ Why htdemucs is so hard to export (complex tensors, Python dynamism, fused C++ kernels)
✅ How to replace torch.stft with Conv1d without losing accuracy (5 × 10⁻⁶ round-trip diff)
✅ How to patch fractions.Fraction, random.randrange, and aten::_native_multi_head_attention
✅ How to verify parity to 4 decimals before trusting the export
✅ Pure numpy + onnxruntime inference — no PyTorch at runtime

Prerequisites

pip install "torch>=2.4,<2.5" "torchaudio>=2.4,<2.5" demucs onnx onnxruntime numpy soundfile

No GPU required for export or inference. Tested on Apple M4 Pro and Linux x86_64. If you don't have demucs set up yet, follow the complete demucs local setup guide first.

Why doesn't `htdemucs` export to ONNX out of the box?

Short answer: Because the model uses four PyTorch features that no ONNX exporter has good answers for — complex tensors in the STFT, fractions.Fraction arithmetic in model.segment, random.randrange inside the cross-transformer, and the fused C++ aten::_native_multi_head_attention kernel.

Each one stops torch.onnx.export and torch.onnx.dynamo_export cold. You hit them in order; each new patch unblocks the next failure.

Blocker 1: `complex64` STFT output

Short answer: Replace torch.stft with a Conv1d using sin/cos kernels that emit two real-valued channels.

The first op in HT-Demucs is:

z = torch.stft(x, n_fft=4096, hop_length=1024, window=hann,
               win_length=4096, normalized=True, center=True,
               return_complex=True, pad_mode="reflect")

return_complex=True returns a complex64 tensor. ONNX's STFT op (opset 17+) does not support complex outputs; every downstream slice/transpose fails. The workaround:

import math, torch
import torch.nn as nn
import torch.nn.functional as F

def _make_stft_kernels(n_fft: int):
    n = torch.arange(n_fft, dtype=torch.float64)
    window = torch.hann_window(n_fft, periodic=True, dtype=torch.float64)
    norm = 1.0 / math.sqrt(n_fft)
    k = torch.arange(n_fft // 2 + 1, dtype=torch.float64).unsqueeze(1)
    angles = 2 * math.pi * k * n.unsqueeze(0) / n_fft
    cos = (window * torch.cos(angles)) * norm
    sin = (window * -torch.sin(angles)) * norm   # negative for forward STFT
    return cos.float().unsqueeze(1), sin.float().unsqueeze(1)

class RealSTFT(nn.Module):
    def __init__(self, n_fft=4096, hop_length=1024):
        super().__init__()
        cos, sin = _make_stft_kernels(n_fft)
        self.register_buffer("cos_kernel", cos)
        self.register_buffer("sin_kernel", sin)
        self.n_fft, self.hop_length = n_fft, hop_length

    def forward(self, x):
        x = F.pad(x.reshape(-1, 1, x.shape[-1]),
                  (self.n_fft // 2,) * 2, mode="reflect")
        real = F.conv1d(x, self.cos_kernel, stride=self.hop_length)
        imag = F.conv1d(x, self.sin_kernel, stride=self.hop_length)
        return torch.stack([real, imag], dim=1)    # (BN, 2, F, T) real

Verify against the real thing before going further:

x = torch.randn(1, 343980)
ref = torch.stft(x, n_fft=4096, hop_length=1024,
                 window=torch.hann_window(4096), win_length=4096,
                 normalized=True, center=True, return_complex=True,
                 pad_mode="reflect")
ref_real = torch.stack([ref.real, ref.imag], dim=1)

stft = RealSTFT()
out = stft(x).squeeze(0)
print("max abs diff:", (out - ref_real).abs().max().item())   # ~5e-6

5 × 10⁻⁶ is rounding noise. Use the same trick (ConvTranspose1d with conjugate kernels + overlap-add window-squared envelope) for the inverse STFT. Now every view_as_real / view_as_complex in the model's _magnitude and _mask methods can be rewritten to thread real-channel tensors through the whole forward pass.

Blocker 2: `fractions.Fraction` in `model.segment`

Short answer: Coerce to float before exporting.

Pretrained htdemucs_ft ships with model.segment = Fraction(39, 5) (= 7.8 seconds). Dynamo dies:

torch._dynamo.exc.Unsupported: call_function
UserDefinedClassVariable(<class 'fractions.Fraction'>)

Fix:

from fractions import Fraction

if isinstance(model.segment, Fraction):
    model.segment = float(model.segment)   # 7.8

Mathematically identical at inference. Trivial — but you don't get to the next blocker without it.

Blocker 3: `random.randrange` in the cross-transformer

Short answer: Monkey-patch the affected method to hardcode shift=0.

CrossTransformerEncoder._get_pos_embedding calls Python's random:

shift = random.randrange(self.sin_random_shift + 1)

At inference, sin_random_shift = 0, so random.randrange(1) always returns 0 — a no-op. But neither exporter can see through random and both bail out. Patch the method directly:

import types
from demucs.transformer import CrossTransformerEncoder, create_sin_embedding

def _get_pos_embedding_no_random(self_, T, B, C, device):
    if self_.emb == "sin":
        return create_sin_embedding(T, C, shift=0, device=device,
                                    max_period=self_.max_period)
    raise RuntimeError(f"emb={self_.emb} not handled at export")

for m in model.modules():
    if isinstance(m, CrossTransformerEncoder):
        m._get_pos_embedding = types.MethodType(_get_pos_embedding_no_random, m)

Blocker 4: `aten::_native_multi_head_attention`

Short answer: Replace nn.MultiheadAttention.forward with a plain Linear/bmm/softmax implementation.

Modern PyTorch short-circuits nn.MultiheadAttention.forward to a fused C++ kernel (_native_multi_head_attention) when its preconditions are met. That kernel has no ONNX symbolic at any opset:

torch.onnx.errors.UnsupportedOperatorError: Exporting the operator
'aten::_native_multi_head_attention' to ONNX opset version 17 is not supported.

Patch every MHA instance's forward with a drop-in that uses only ops with stable ONNX symbolics:

def _onnx_friendly_mha_forward(self_, query, key, value,
                                key_padding_mask=None, need_weights=True,
                                attn_mask=None, average_attn_weights=True,
                                is_causal=False):
    if self_.batch_first:
        query, key, value = (t.transpose(0, 1) for t in (query, key, value))
    tgt_len, bsz, embed_dim = query.shape
    head_dim = embed_dim // self_.num_heads

    if self_._qkv_same_embed_dim and torch.equal(query, key) and torch.equal(key, value):
        q, k, v = F.linear(query, self_.in_proj_weight, self_.in_proj_bias).chunk(3, dim=-1)
    else:
        # cross-attention path: three separate projections
        w_q, w_k, w_v = self_.in_proj_weight.chunk(3)
        b_q, b_k, b_v = (self_.in_proj_bias.chunk(3)
                         if self_.in_proj_bias is not None else (None, None, None))
        q = F.linear(query, w_q, b_q)
        k = F.linear(key,   w_k, b_k)
        v = F.linear(value, w_v, b_v)

    q = q.contiguous().view(tgt_len, bsz * self_.num_heads, head_dim).transpose(0, 1)
    k = k.contiguous().view(-1,      bsz * self_.num_heads, head_dim).transpose(0, 1)
    v = v.contiguous().view(-1,      bsz * self_.num_heads, head_dim).transpose(0, 1)

    attn = F.softmax(torch.bmm(q * head_dim ** -0.5, k.transpose(1, 2)), dim=-1)
    out  = torch.bmm(attn, v).transpose(0, 1).contiguous().view(tgt_len, bsz, embed_dim)
    return self_.out_proj(out), None

for m in model.modules():
    if isinstance(m, nn.MultiheadAttention):
        m.forward = types.MethodType(_onnx_friendly_mha_forward, m)

Parity vs the fused kernel: 1 × 10⁻⁶ max diff. Safe.

The export call

Short answer: Legacy torch.onnx.export at opset 17, dynamo=False. dynamo_export dies on the patches anyway; legacy works.

from demucs.pretrained import get_model

bag = get_model("htdemucs_ft")
drums_model = bag.models[0].eval().cpu()
# apply all 4 patches above to drums_model

n = int(float(drums_model.segment) * int(bag.samplerate))   # 343980
dummy = torch.randn(1, 2, n, dtype=torch.float32)

torch.onnx.export(
    drums_model,
    dummy,
    "htdemucs_ft_drums.onnx",
    input_names=["mix"],
    output_names=["stems"],
    opset_version=17,
    dynamo=False,
    do_constant_folding=True,
)

316 MB per specialist. ~6.5 s export time on CPU. Passes onnx.checker.check_model. 24,765 nodes.

Repeat for bag.models[1] (bass), bag.models[2] (other), bag.models[3] (vocals). All four use the same architecture and patches.

Parity verification — the only acceptance test that matters

Short answer: Run the original PyTorch model and the ONNX model on the same fixed input, compute .abs().max(). Should be < 1e-3.

import numpy as np
import onnxruntime as ort

x = np.random.randn(1, 2, 343980).astype("float32")
sess = ort.InferenceSession("htdemucs_ft_drums.onnx",
                            providers=["CPUExecutionProvider"])
onnx_out = sess.run(["stems"], {"mix": x})[0]

torch_out = drums_model(torch.from_numpy(x)).detach().numpy()
print("max abs diff:", np.abs(onnx_out - torch_out).max())   # 1.63e-4

Per stem, against the original PyTorch htdemucs_ft at fp32:

Stem	max abs diff
drums	0.000163
bass	0.000011
other	0.000739
vocals	0.000008

All comfortably under the 1e-3 tolerance that fp32 reordering normally explains. SDR scores measured against MUSDB18-HQ are unchanged — if you want to verify yourself, query the 800-row leaderboard from pandas without re-running the benchmark.

Inference with zero PyTorch (pure numpy + onnxruntime)

Short answer: Load the four ONNX files, do overlap-add chunking, sum the per-model outputs.

import numpy as np
import onnxruntime as ort
import soundfile as sf

SOURCES = ["drums", "bass", "other", "vocals"]
CHUNK = 343980             # 7.8 s * 44100 Hz
HOP   = CHUNK // 4

sessions = {
    s: ort.InferenceSession(f"htdemucs_ft_{s}.onnx",
                            providers=["CPUExecutionProvider"])
    for s in SOURCES
}

def separate(mix, sr=44100):
    pad = CHUNK - (mix.shape[-1] % CHUNK)
    mix_p = np.pad(mix, ((0, 0), (0, pad)), mode="constant")
    out = {s: np.zeros_like(mix_p) for s in SOURCES}
    weight = np.zeros(mix_p.shape[-1])
    w = np.hanning(CHUNK).astype("float32")

    for start in range(0, mix_p.shape[-1] - CHUNK + 1, HOP):
        chunk = mix_p[:, start:start+CHUNK].astype("float32")[None]
        for s in SOURCES:
            y = sessions[s].run(["stems"], {"mix": chunk})[0][0]
            target_row = SOURCES.index(s)
            out[s][:, start:start+CHUNK] += y[target_row] * w
        weight[start:start+CHUNK] += w

    for s in SOURCES:
        out[s] = (out[s] / np.maximum(weight, 1e-8))[:, :mix.shape[-1]]
    return out

mix, sr = sf.read("song.wav", dtype="float32", always_2d=True)
stems = separate(mix.T, sr)
for s in SOURCES:
    sf.write(f"{s}.wav", stems[s].T, sr)

Zero PyTorch. Zero MLX. Runs anywhere onnxruntime runs — iOS via onnxruntime-objc, Android via onnxruntime-android, browsers via onnxruntime-web.

Performance numbers

Short answer: ONNX Runtime CPU EP is 1.31× faster than PyTorch CPU. A single-specialist ONNX is ~5.7× faster than the full bag.

Apple M4 Pro, 3-minute song:

Backend	Latency	Notes
ONNX CPU EP — single specialist	~22 s	Use this for vocal removers / drum extractors
ONNX CPU EP — full 4-stem bag	~88 s	All stems
PyTorch CPU — full bag	~125 s	Baseline
PyTorch MPS — full bag	~47 s	Apple GPU
ONNX CUDA — NVIDIA L4 (extrapolated)	~6 s	Server-side deployment

The single-specialist trick works because the htdemucs_ft bag is one-hot:

# the bag's per-model weight matrix
weights = [[1, 0, 0, 0],   # drums  = sub-model 0's drums output
           [0, 1, 0, 0],   # bass   = sub-model 1's bass output
           [0, 0, 1, 0],   # other  = sub-model 2's other output
           [0, 0, 0, 1]]   # vocals = sub-model 3's vocals output

Sub-model 3's vocals output is the bag's vocals output, bit-exact. If you're building a vocal remover, ship sub-model 3 alone (~316 MB ONNX, ~75 MB quantized) instead of the full ~1.26 GB bag at identical per-stem quality.

Wrapping Up

The five new ONNX repos — all MIT-licensed, all parity-verified:

StemSplitio/htdemucs-ft-onnx — full 4-stem bag + numpy aggregator
StemSplitio/htdemucs-ft-drums-onnx
StemSplitio/htdemucs-ft-bass-onnx
StemSplitio/htdemucs-ft-other-onnx
StemSplitio/htdemucs-ft-vocals-onnx

If you'd rather skip the deployment plumbing entirely, the StemSplit hosted vocal remover runs the exact same htdemucs_ft weights with credits, queueing, and a dashboard — same model, just hosted. The full long-form writeup on the StemSplit blog has the iOS/Swift, Android/Kotlin, and onnxruntime-web code samples as well.

Open an issue on any of the repos if you find a stem where your parity diff exceeds 1e-3 — would love to hear about it.

Pick the Right HTDemucs Model in Python — Query 800 MUSDB18-HQ Scores on Hugging Face (2026)

StemSplit — Tue, 19 May 2026 16:41:18 +0000

You're about to ship stem separation in a product. Marketing pages say "state-of-the-art AI." Your job is to pick an actual model_id string — htdemucs, htdemucs_ft, htdemucs_6s, or mdx_extra_q — and defend that choice to whoever reads the PR.

Listening tests on three Spotify tracks won't cut it. Running MUSDB18 yourself takes a weekend and 22 GB of disk.

There's a third option: stem-separation-benchmark-2026 — 800 rows of BSS Eval v4 scores (50 MUSDB18-HQ test tracks × 4 models × 4 stems), CC-BY-4.0, queryable in pandas from your laptop in under a minute.

This post shows how to turn that table into a model picker and a regression test — not how to re-run the benchmark (see Best Free AI Stem Splitters in 2026 for DIY mir_eval).

What You'll Learn

✅ Load the public leaderboard into pandas without downloading audio
✅ Pick a model by stem priority (vocals vs drums) and latency budget (RTF)
✅ Find worst-case tracks per model before they hit production
✅ Assert median vocal SDR in CI so model upgrades don't silently regress
✅ Map picks to StemSplit API quality tiers (same weights)

Prerequisites

pip install datasets pandas

No GPU. No MUSDB18 download. The dataset ships metrics only (MUSDB18 audio can't be redistributed).

What's in the dataset?

Short answer: One Parquet config (metrics_only) with per-track, per-stem SDR/ISR/SIR/SAR plus wall_time_s, rtf, and host metadata from an Apple M4 Pro + PyTorch MPS run.

Column	Use in your app
`model_id`	Which weights to load or API tier to call
`stem`	`vocals`, `drums`, `bass`, `other`
`sdr_median`	Primary quality score (dB, higher = better)
`rtf`	`wall_time_s / duration_s` — 0.07 ≈ 14× faster than realtime
`track_id`	MUSDB18-HQ test folder name

Four models in v1: htdemucs, htdemucs_ft, htdemucs_6s, mdx_extra_q.

Note on htdemucs_6s: other scores look broken (~0.2 dB) because piano/guitar are split out of MUSDB's other stem. Compare htdemucs_6s on vocals/drums/bass only, or wait for v1.1 where piano + guitar + other is summed before eval. See the dataset card.

For background on what SDR means in practice, how HTDemucs separates audio is a better read than repeating the metric tutorial here.

Load the leaderboard in three lines

Short answer: load_dataset → to_pandas() → groupby.

from datasets import load_dataset

ds = load_dataset(
    "StemSplitio/stem-separation-benchmark-2026",
    "metrics_only",
    split="results",
)
df = ds.to_pandas()

leaderboard = (
    df.groupby(["model_id", "stem"])["sdr_median"]
    .median()
    .unstack()
    .round(2)
)
print(leaderboard)

Example output (v1, May 2026):

stem          bass  drums  other  vocals
model_id
htdemucs      9.78  10.01   6.42    8.53
htdemucs_6s   9.11   9.54   0.22    8.66
htdemucs_ft  10.38  10.11   6.34    9.19
mdx_extra_q  11.42  11.49   7.67    9.04

Vocal-first apps: htdemucs_ft wins on vocals. Drum/bass-heavy apps (DJ tools, rhythm games): mdx_extra_q leads. Latency-sensitive previews: check RTF next.

Build a model picker function

Short answer: Filter by stem + max RTF, then idxmax on sdr_median.

import pandas as pd

VOCAL_MODELS = ["htdemucs", "htdemucs_ft", "htdemucs_6s", "mdx_extra_q"]


def load_benchmark() -> pd.DataFrame:
    from datasets import load_dataset

    return load_dataset(
        "StemSplitio/stem-separation-benchmark-2026",
        "metrics_only",
        split="results",
    ).to_pandas()


def pick_model(
    df: pd.DataFrame,
    *,
    stem: str = "vocals",
    max_rtf: float | None = 0.10,
    candidates: list[str] | None = None,
) -> str:
    """Return model_id with best median SDR for `stem` under `max_rtf`."""
    subset = df[df["stem"] == stem]
    if candidates:
        subset = subset[subset["model_id"].isin(candidates)]
    if max_rtf is not None:
        subset = subset[subset["rtf"] <= max_rtf]
    if subset.empty:
        raise ValueError(f"No model satisfies stem={stem!r}, max_rtf={max_rtf}")

    scores = subset.groupby("model_id")["sdr_median"].median()
    return scores.idxmax()


if __name__ == "__main__":
    df = load_benchmark()
    print("Vocal model (RTF ≤ 0.10):", pick_model(df, stem="vocals"))
    print("Drums model (no RTF cap):", pick_model(df, stem="drums", max_rtf=None))

On the current data, pick_model(..., stem="vocals", max_rtf=0.10) returns htdemucs_ft. Drop the RTF cap on drums and you get mdx_extra_q.

Wire this into your config:

# settings.py
STEM_MODEL = {
    "vocals": pick_model(df, stem="vocals", max_rtf=0.08),
    "drums": pick_model(df, stem="drums", max_rtf=None),
}

That's a defensible default you can paste into a design doc with a link to the dataset.

Find your worst-case tracks before users do

Short answer: Sort by sdr_median ascending per model — the tail is where separation breaks.

def worst_tracks(df: pd.DataFrame, model_id: str, stem: str, n: int = 5) -> pd.DataFrame:
    return (
        df[(df["model_id"] == model_id) & (df["stem"] == stem)]
        .nsmallest(n, "sdr_median")[["track_id", "sdr_median", "rtf", "duration_s"]]
    )


df = load_benchmark()
print(worst_tracks(df, "htdemucs_ft", "vocals"))

If your product targets metal or dense mixes, cross-check whether your genre's failure modes show up in these track names — then add those clips to your own QA set. The HF table won't replace genre-specific testing, but it surfaces landmines faster than random uploads.

Regression-test model quality in CI

Short answer: Assert median vocal SDR from the public table stays above a floor — catches bad deploys without running inference in GitHub Actions.

You are not running Demucs in CI. You're pinning expectations to the published benchmark so nobody ships htdemucs where product spec says htdemucs_ft.

# tests/test_model_policy.py
import pytest
from picker import load_benchmark  # module from previous section

VOCAL_SDR_FLOOR_DB = 9.0  # below htdemucs_ft median; adjust with product input


def test_vocal_model_meets_benchmark_floor():
    df = load_benchmark()
    vocal_median = (
        df[(df["model_id"] == "htdemucs_ft") & (df["stem"] == "vocals")]["sdr_median"].median()
    )
    assert vocal_median >= VOCAL_SDR_FLOOR_DB, (
        f"htdemucs_ft vocal median {vocal_median:.2f} dB < floor {VOCAL_SDR_FLOOR_DB}"
    )


def test_picker_respects_rtf_budget():
    df = load_benchmark()
    model = pick_model(df, stem="vocals", max_rtf=0.10)
    rtf_p95 = df[(df["model_id"] == model) & (df["stem"] == "vocals")]["rtf"].quantile(0.95)
    assert rtf_p95 <= 0.10, f"{model} p95 RTF {rtf_p95:.3f} exceeds budget"

Cache the dataset in CI (HF_HOME or datasets cache dir) so pulls don't hit rate limits every run.

Map picks to StemSplit API tiers

Short answer: Hosted StemSplit runs the same weights — no separate stemsplit_api row in the dataset because numbers would duplicate.

Your picker result	StemSplit tier	Benchmark row
Speed / bulk preview	FAST	`htdemucs`
Vocal isolation default	BALANCED	`htdemucs_ft`
Piano + guitar stems	BEST (6-stem)	`htdemucs_6s`

If you'd rather not operate Demucs + ffmpeg yourself, the API uses the same models — see building a vocal remover with the StemSplit API for the async job flow.

When you still need your own benchmark

The HF table answers: "Which open-source Demucs variant is best on MUSDB18-HQ?"

It does not answer:

How your users' uploads (low-bitrate MP3, phone recordings) behave
Commercial tools (LALAL.AI, Moises) — see AI Stem Splitter API Comparison
Spleeter migration — Spleeter is Dead + local mir_eval if you need custom tracks

Use the public dataset for model ID selection and CI floors. Layer your own golden files on top for product QA.

Wrapping Up

Dataset: huggingface.co/datasets/StemSplitio/stem-separation-benchmark-2026
Pattern: load once → pick_model(stem, max_rtf) → worst-track audit → CI median assertion
Don't duplicate work: MUSDB18 eval is already done; spend your GPU time on your audio

If you build something on top of this table (dashboard, CLI, fine-tune report), drop a link in the comments — the dataset is CC-BY-4.0.

Citation:

@misc{stemsplit_benchmark_2026,
  title  = {StemSplit Stem-Separation Benchmark 2026},
  author = {StemSplit},
  year   = {2026},
  url    = {https://huggingface.co/datasets/StemSplitio/stem-separation-benchmark-2026}
}

The Best Resources for Audio Stem Separation in Python (2026)

StemSplit — Sat, 09 May 2026 00:26:37 +0000

Audio source separation has gone from a niche research problem to something you can do in a few lines of Python. The tooling has improved dramatically in the past two years, but the documentation is scattered. Here's a curated list of the resources actually worth reading in 2026.

Understanding the technology first

Before you write any code, it's worth understanding what you're working with. Modern stem separation uses neural networks trained on large datasets of music with known stems. The current state-of-the-art open source model is HTDemucs from Meta AI Research — a hybrid transformer architecture that processes both the waveform and spectrogram simultaneously.

HTDemucs GitHub — the model itself, with installation docs and usage examples
HTDemucs paper (arXiv) — the research behind the architecture
MDX Workshop benchmarks — the most rigorous public comparison of separation models

The practical Python guides

For the full implementation comparison:

Demucs, Spleeter & API Compared (Hashnode) — covers all three approaches with working code. Particularly useful for the async polling loop implementation, which is where most first attempts fall over. Compares running models locally vs. calling a REST API, with honest tradeoffs for each.

For a specific end-to-end pipeline:

Full acapella extraction pipeline (Hashnode) — YouTube download with yt-dlp → API submission → async polling → stem download. Good template if you're building something similar.

The core libraries

# The three you'll actually use
pip install demucs          # HTDemucs local inference
pip install yt-dlp          # Audio download from YouTube/SoundCloud/etc.
pip install requests        # REST API calls

Demucs — for local inference on GPU. Best quality, most control, needs CUDA.

yt-dlp — the standard for downloading audio from streaming platforms. Handles YouTube, SoundCloud, Bandcamp, and hundreds more.

StemSplit API — if you want cloud inference without managing GPU infrastructure. Has a free tier for testing and documented REST endpoints. The separation quality is the same as local HTDemucs (it runs the same model).

The non-obvious parts

Polling is mandatory. Separation is asynchronous — you submit a job and poll for results. Build this correctly from the start: exponential backoff, timeout handling, status codes.

Local Demucs needs GPU to be practical. CPU inference on HTDemucs takes 10–15 minutes per track. GPU drops that to under 90 seconds. If you're on CPU-only hardware, an API is more practical.

File format matters. HTDemucs works best on WAV or FLAC. MP3 compression artifacts can affect separation quality on bass-heavy content specifically.

Genre affects results. Models trained on pop/rock generalize well to hip-hop and R&B. Jazz with unusual voicings and non-Western music are harder. Test on your actual content before building a pipeline around it.

Quick starter

import subprocess
import requests
import time

# Download audio with yt-dlp
subprocess.run(["yt-dlp", "-x", "--audio-format", "wav", "-o", "track.wav", "YOUTUBE_URL"])

# Submit to StemSplit API
with open("track.wav", "rb") as f:
    r = requests.post(
        "https://stemsplit.io/api/v1/separate",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"audio": f},
        data={"stems": "4"},
    )
job_id = r.json()["job_id"]

# Poll for results
while True:
    status = requests.get(
        f"https://stemsplit.io/api/v1/jobs/{job_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    ).json()
    if status["status"] == "complete":
        print(status["stems"])  # URLs for each stem
        break
    time.sleep(5)

For the complete implementation with error handling, retries, and batch processing — see the full guide on Hashnode.

Drop questions in the comments if anything is unclear. This is a fast-moving space and I'll update this post when significant changes happen.

How to Build a Discord Bot that Splits Audio Stems with Python (2026)

StemSplit — Thu, 07 May 2026 20:06:01 +0000

Discord has 500 million users. Most bots stream music from YouTube. This one splits it into stems — vocals, drums, bass, and instrumentals — and drops download links straight into your DMs.

Here's the full walkthrough: slash command, file upload, async API job, polling loop, and a result embed that would make your server's musicians happy.

What You'll Learn

✅ How to create a /split slash command with discord.py 2.x app_commands
✅ How to accept audio file uploads through Discord interactions
✅ How to call the StemSplit REST API and poll for async job completion
✅ How to DM the user individual stem download links when the job finishes
✅ How to handle file size limits, API errors, and Discord's 3-second interaction timeout
✅ A working docker-compose.yml to deploy it anywhere

Prerequisites

pip install "discord.py>=2.4" requests python-dotenv

You need three things:

A Discord bot token — create a bot at discord.com/developers/applications, enable the MESSAGE CONTENT intent and bot scope with Send Messages, Read Message History, Attach Files, and Use Application Commands permissions.
A StemSplit API key — grab one from the free tier at StemSplit's developer portal (5 minutes of processing, no card). The same key powers this bot and any other integration you build.
A .env file in your project root:

DISCORD_TOKEN=your_discord_bot_token_here
STEMSPLIT_API_KEY=your_stemsplit_api_key_here

How the Bot Works

The flow is simple:

User runs /split → uploads audio file
  → Bot defers the interaction (buys 15 min instead of 3 seconds)
  → POSTs file to StemSplit API → gets job_id
  → Polls GET /jobs/{job_id} every 5s
  → Job completes → bot DMs user an embed with 4 download links
  → Bot replies publicly: "Done! Check your DMs."

StemSplit runs HTDemucs on GPU — a 3-minute track takes roughly 35–45 seconds. HTDemucs is the current best open-source model for stem separation, so quality is on par with what you'd get running Demucs locally, without the 4 GB model download.

Setting Up the Discord Application

In the Discord Developer Portal:

Create a new application → add a Bot
Under Privileged Gateway Intents, enable Message Content Intent
Under OAuth2 → URL Generator, select scopes: bot + applications.commands
Add permissions: Send Messages, Attach Files, Use Application Commands, Send Messages in Threads
Copy the generated invite URL and add the bot to your server

The Full Bot (bot.py)

Here's the complete file. Read through it first, then I'll break down each section.

"""
StemSplit Discord Bot
Splits any audio file into vocals, drums, bass, and other stems.
"""
import asyncio
import os
import time
from io import BytesIO

import discord
import requests
from discord import app_commands
from dotenv import load_dotenv

load_dotenv()

DISCORD_TOKEN = os.environ["DISCORD_TOKEN"]
STEMSPLIT_KEY = os.environ["STEMSPLIT_API_KEY"]

API_BASE = "https://api.stemsplit.io/v1"
HEADERS = {"Authorization": f"Bearer {STEMSPLIT_KEY}"}

MAX_FILE_MB = 20
POLL_INTERVAL = 5
POLL_TIMEOUT = 300  # 5 minutes max

STEM_EMOJI = {
    "vocals": "🎤",
    "drums": "🥁",
    "bass": "🎸",
    "other": "🎹",
}


class StemBot(discord.Client):
    def __init__(self) -> None:
        intents = discord.Intents.default()
        super().__init__(intents=intents)
        self.tree = app_commands.CommandTree(self)

    async def setup_hook(self) -> None:
        await self.tree.sync()

    async def on_ready(self) -> None:
        print(f"Logged in as {self.user} (id: {self.user.id})")


client = StemBot()


# ── Slash command ──────────────────────────────────────────────────────────────

@client.tree.command(name="split", description="Split an audio file into stems (vocals, drums, bass, other)")
@app_commands.describe(file="Audio file to split (.mp3, .wav, .flac, .m4a — max 20 MB)")
async def split_command(interaction: discord.Interaction, file: discord.Attachment) -> None:
    # Defer immediately — gives us 15 minutes instead of 3 seconds
    await interaction.response.defer(thinking=True)

    # Validate file size
    if file.size > MAX_FILE_MB * 1024 * 1024:
        await interaction.followup.send(
            f"❌ File too large ({file.size / 1024 / 1024:.1f} MB). Max is {MAX_FILE_MB} MB."
        )
        return

    # Validate file type
    allowed = {".mp3", ".wav", ".flac", ".m4a", ".ogg", ".aac"}
    ext = os.path.splitext(file.filename)[1].lower()
    if ext not in allowed:
        await interaction.followup.send(
            f"❌ Unsupported file type `{ext}`. Supported: {', '.join(sorted(allowed))}"
        )
        return

    await interaction.followup.send(f"⏳ Got it! Splitting **{file.filename}** — this takes ~35–45 seconds…")

    try:
        # Download the attachment
        audio_bytes = await file.read()

        # Submit to StemSplit API
        job_id = await asyncio.get_event_loop().run_in_executor(
            None, lambda: submit_job(audio_bytes, file.filename)
        )

        # Poll until done
        stems = await asyncio.get_event_loop().run_in_executor(
            None, lambda: poll_job(job_id)
        )

        # DM the user
        dm_channel = await interaction.user.create_dm()
        embed = build_embed(file.filename, stems)
        await dm_channel.send(embed=embed)
        await interaction.followup.send("✅ Done! Check your DMs for the stem download links.")

    except StemSplitError as e:
        await interaction.followup.send(f"❌ StemSplit API error: {e}")
    except TimeoutError:
        await interaction.followup.send("❌ Job timed out after 5 minutes. Try a shorter file.")
    except Exception as e:
        await interaction.followup.send(f"❌ Unexpected error: {e}")


# ── StemSplit API helpers ──────────────────────────────────────────────────────

class StemSplitError(RuntimeError):
    pass


def submit_job(audio_bytes: bytes, filename: str) -> str:
    """POST the audio file to StemSplit and return the job_id."""
    res = requests.post(
        f"{API_BASE}/jobs",
        headers=HEADERS,
        files={"file": (filename, BytesIO(audio_bytes), "audio/mpeg")},
        timeout=60,
    )
    if not res.ok:
        raise StemSplitError(f"HTTP {res.status_code}: {res.text[:200]}")
    return res.json()["job_id"]


def poll_job(job_id: str) -> dict:
    """Poll GET /jobs/{job_id} every POLL_INTERVAL seconds until complete."""
    deadline = time.time() + POLL_TIMEOUT
    while time.time() < deadline:
        res = requests.get(f"{API_BASE}/jobs/{job_id}", headers=HEADERS, timeout=15)
        if not res.ok:
            raise StemSplitError(f"Poll error HTTP {res.status_code}")
        data = res.json()
        status = data.get("status")
        if status == "done":
            return data.get("stems", {})
        if status == "failed":
            raise StemSplitError(data.get("error", "Job failed"))
        time.sleep(POLL_INTERVAL)
    raise TimeoutError()


def build_embed(filename: str, stems: dict) -> discord.Embed:
    """Build a Discord embed with download links for each stem."""
    embed = discord.Embed(
        title=f"🎵 Stems ready: {filename}",
        description="Your audio has been split into individual tracks. Links expire in 24 hours.",
        color=discord.Color.blurple(),
    )
    for stem_name, url in stems.items():
        emoji = STEM_EMOJI.get(stem_name, "🎵")
        embed.add_field(
            name=f"{emoji} {stem_name.capitalize()}",
            value=f"[Download {stem_name}.wav]({url})",
            inline=False,
        )
    embed.set_footer(text="Powered by StemSplit · stemsplit.io")
    return embed


# ── Run ───────────────────────────────────────────────────────────────────────

client.run(DISCORD_TOKEN)

Code Walkthrough

Deferring the interaction

The most important line in the bot:

await interaction.response.defer(thinking=True)

Discord gives you exactly 3 seconds to respond to a slash command before it shows "interaction failed." Deferring extends that to 15 minutes — enough time for the API job to complete. The thinking=True flag shows a "Bot is thinking…" indicator to the user.

Submitting the job

res = requests.post(
    f"{API_BASE}/jobs",
    headers=HEADERS,
    files={"file": (filename, BytesIO(audio_bytes), "audio/mpeg")},
)

StemSplit's REST API accepts a multipart file upload and returns a job_id immediately. The job runs asynchronously — the full API reference lives in the StemSplit REST API docs. If you've already built something with the API, the pattern here is identical to the async polling approach used in StemSplit's Python vocal remover tutorial.

Polling loop

while time.time() < deadline:
    data = requests.get(f"{API_BASE}/jobs/{job_id}", ...).json()
    if data["status"] == "done":
        return data["stems"]
    time.sleep(POLL_INTERVAL)

The loop checks every 5 seconds and exits on "done" or "failed". I'm running this in run_in_executor so it doesn't block the Discord event loop while waiting.

The result embed

When the job completes, stems is a dict of {"vocals": "https://...", "drums": "https://...", ...}. We loop over it to build Discord embed fields with download links. Each link is a pre-signed URL that expires after 24 hours.

Error Handling

A few edge cases worth locking down:

File size. Discord's attachment limit is 25 MB for standard servers but API file uploads can add overhead. Keep the guard at 20 MB to be safe.

API rate limits. StemSplit's API rate-limits at the job submission level. If you're running this in a busy server, add a per-user cooldown:

from discord.ext.commands import CooldownMapping, BucketType

cooldown = CooldownMapping.from_cooldown(2, 60, BucketType.user)  # 2 splits per user per minute

Discord interaction timeouts. If the job somehow runs longer than 15 minutes (extremely unlikely — typical tracks finish in under 1 minute), the interaction expires. The POLL_TIMEOUT = 300 guard catches this and tells the user to try a shorter file.

Running It

Locally:

python bot.py

Or with Docker:

# docker-compose.yml
services:
  stembot:
    image: python:3.12-slim
    working_dir: /app
    volumes:
      - .:/app
    command: pip install -r requirements.txt && python bot.py
    env_file:
      - .env
    restart: unless-stopped

docker-compose up -d

Wrapping Up

The bot is around 100 lines, fully async, and ready to drop into any server. The same job-submission + polling pattern works for batch processing, Flask APIs, or any other integration — StemSplit's official Discord bot guide covers additional configuration options like webhook callbacks if you want to skip polling entirely.

If you'd rather run the separation model locally without an API, the Hashnode walkthrough on running the full Demucs acapella pipeline in Python covers everything — tradeoffs included.

Questions or improvements? Drop them in the comments — I'd love to see what people build with this.

How to Build an AI Vocal Remover in Python with the StemSplit API (2026)

StemSplit — Sat, 18 Apr 2026 10:17:23 +0000

I needed to add vocal removal to an app last week without shipping a 300 MB Demucs model with the binary. The shortest path I found was StemSplit's API — three endpoints, one model (HTDemucs), and a free tier big enough to prototype on.

This is the working tutorial I wish I'd had. Single file, batch, webhooks, and a Flask wrapper at the end. All copy-paste runnable.

What You'll Learn

✅ How to remove vocals from any audio file in 5 lines of Python
✅ How the async job pattern works (upload → poll → download)
✅ Batch processing with bounded concurrency
✅ Webhook callbacks instead of polling
✅ Wrapping the API as a Flask backend for your own frontend
✅ Cost math, rate limits, and the production gotchas

Prerequisites

pip install requests python-dotenv tenacity flask

You'll need a free API key from the AI vocal remover dashboard — sign up gives you 10 minutes of processing, no card. Drop it in .env:

STEMSPLIT_API_KEY=your_key_here

# config.py
import os
from dotenv import load_dotenv

load_dotenv()

API_KEY  = os.environ["STEMSPLIT_API_KEY"]
API_BASE = "https://api.stemsplit.io/v1"
HEADERS  = {"Authorization": f"Bearer {API_KEY}"}

The 5-Line Version

If you just want to see it work before committing to anything:

import requests, time

job = requests.post(
    "https://api.stemsplit.io/v1/separate",
    headers=HEADERS,
    files={"audio": open("song.mp3", "rb")},
    json={"stems": 2, "format": "wav"},
).json()
status = {"status": "processing"}
while status["status"] not in ("completed", "failed"):
    time.sleep(3)
    status = requests.get(f"https://api.stemsplit.io/v1/jobs/{job['job_id']}", headers=HEADERS).json()
open("instrumental.wav", "wb").write(requests.get(status["stems"]["instrumental"]).content)

That's the entire flow. Upload, poll, download. The rest of this article is making that production-grade.

How the API Works

Three endpoints. That's the whole surface area:

Method	Path	Purpose
`POST`	`/v1/separate`	Upload audio + start a job
`GET`	`/v1/jobs/{id}`	Poll job status
`POST`	`/v1/webhooks`	Register a callback URL (skip the polling)

The stems field on the upload controls what you get back:

`stems`	Output
`2`	`vocals` + `instrumental` (vocal removal)
`4`	`vocals` + `drums` + `bass` + `other`
`6`	adds `guitar` + `piano`

For vocal removal you want stems: 2. The instrumental is the "everything except vocals" file.

📝 BPM and musical key come back in every job response at no extra cost. Useful if you're piping into a DJ tool, practice app, or recommender.

Single File: The Production Version

Same flow as the 5-liner, but with timeouts, retries on flaky network calls, exponential backoff for polling, and proper file streaming for large files.

import requests
import time
from pathlib import Path
from tenacity import retry, stop_after_attempt, wait_exponential

from config import API_BASE, HEADERS


@retry(stop=stop_after_attempt(3), wait=wait_exponential(min=2, max=20))
def _post_with_retry(url: str, **kwargs):
    resp = requests.post(url, headers=HEADERS, timeout=60, **kwargs)
    resp.raise_for_status()
    return resp


def remove_vocals(
    audio_path: str,
    output_dir: str = "output",
    poll_interval: float = 3.0,
    timeout: float = 300.0,
) -> dict:
    """
    Remove vocals from a single audio file using the StemSplit API.

    Args:
        audio_path:    Path to input file. MP3, WAV, FLAC, M4A, OGG, WEBM up to 100 MB.
        output_dir:    Where to write the downloaded stems.
        poll_interval: Seconds between status checks.
        timeout:       Maximum seconds to wait before giving up.

    Returns:
        Dict with 'vocals' and 'instrumental' file paths, plus 'bpm' and 'key'.
    """
    Path(output_dir).mkdir(parents=True, exist_ok=True)

    with open(audio_path, "rb") as f:
        job = _post_with_retry(
            f"{API_BASE}/separate",
            files={"audio": (Path(audio_path).name, f)},
            data={"stems": "2", "format": "wav"},
        ).json()

    job_id = job["job_id"]
    deadline = time.time() + timeout

    while time.time() < deadline:
        status = requests.get(f"{API_BASE}/jobs/{job_id}", headers=HEADERS, timeout=30).json()

        if status["status"] == "completed":
            break
        if status["status"] == "failed":
            raise RuntimeError(f"Job {job_id} failed: {status.get('error')}")

        time.sleep(poll_interval)
    else:
        raise TimeoutError(f"Job {job_id} did not complete within {timeout}s")

    out = {}
    for stem, url in status["stems"].items():
        path = Path(output_dir) / f"{Path(audio_path).stem}_{stem}.wav"
        with requests.get(url, stream=True, timeout=120) as r:
            r.raise_for_status()
            with open(path, "wb") as f:
                for chunk in r.iter_content(chunk_size=8192):
                    f.write(chunk)
        out[stem] = str(path)

    out["bpm"] = status.get("bpm")
    out["key"] = status.get("key")
    return out

Usage:

result = remove_vocals("song.mp3")
print(result)
# {
#   'vocals': 'output/song_vocals.wav',
#   'instrumental': 'output/song_instrumental.wav',
#   'bpm': 124.0,
#   'key': 'C# minor'
# }

Notes on what this gives you that the 5-liner doesn't:

Streaming download. Stems can be 30–80 MB each. Don't .content them into memory if you're processing many files.
Bounded wait. A timeout parameter means a stuck job can't hang your worker forever.
Retried uploads. tenacity wraps the upload in three attempts with exponential backoff — survives transient network blips.

Batch Processing

The naive batch loop is slow because most of the wall-clock time is the model running on the server. You want to upload several files, then poll them all in parallel.

from concurrent.futures import ThreadPoolExecutor, as_completed
from pathlib import Path
import glob


def remove_vocals_batch(
    input_dir: str,
    output_dir: str = "output",
    max_concurrent: int = 3,
) -> list[dict]:
    """
    Remove vocals from every audio file in a directory.

    Keep max_concurrent low — the free tier rate-limits aggressively.
    Bumped to 5–10 once you're on a paid plan.
    """
    files = []
    for ext in ("mp3", "wav", "flac", "m4a", "ogg", "webm"):
        files.extend(glob.glob(f"{input_dir}/*.{ext}"))

    print(f"Found {len(files)} files to process")
    results = []

    with ThreadPoolExecutor(max_workers=max_concurrent) as ex:
        futures = {ex.submit(remove_vocals, f, output_dir): f for f in files}
        for future in as_completed(futures):
            src = futures[future]
            try:
                result = future.result()
                results.append({"input": src, **result, "status": "ok"})
                print(f"✅ {Path(src).name} ({result.get('bpm', '?')} BPM)")
            except Exception as e:
                results.append({"input": src, "status": "error", "error": str(e)})
                print(f"❌ {Path(src).name}: {e}")

    ok = sum(1 for r in results if r["status"] == "ok")
    print(f"\nDone. {ok}/{len(files)} succeeded.")
    return results


# Usage
results = remove_vocals_batch("./music")

A 50-file batch on the free tier with max_concurrent=3 finishes in around 12–15 minutes wall-clock for ~4-minute songs. Most of that is wait time on the GPU queue, not network.

⚠️ Set max_concurrent to your tier's allowed parallel jobs. The free tier rate-limits at 3 concurrent. You'll get HTTP 429 above that, which will retry-storm if you don't catch it.

Skip the Polling: Webhooks

Polling is fine for scripts. For a backend, you want webhooks so you're not burning HTTP requests waiting around.

def remove_vocals_async(audio_path: str, callback_url: str) -> str:
    """
    Start a vocal removal job. The API will POST to callback_url when done.
    Returns the job_id immediately.
    """
    with open(audio_path, "rb") as f:
        resp = requests.post(
            f"{API_BASE}/separate",
            headers=HEADERS,
            files={"audio": (Path(audio_path).name, f)},
            data={
                "stems": "2",
                "format": "wav",
                "webhook_url": callback_url,
            },
            timeout=60,
        )
    resp.raise_for_status()
    return resp.json()["job_id"]

The callback payload looks like:

{
  "job_id": "job_a8f2c1",
  "status": "completed",
  "stems": {
    "vocals": "https://stems.stemsplit.io/...",
    "instrumental": "https://stems.stemsplit.io/..."
  },
  "bpm": 124.0,
  "key": "C# minor",
  "duration_seconds": 218.5
}

Receive it in Flask:

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)


@app.route("/webhook/stemsplit", methods=["POST"])
def stemsplit_webhook():
    payload = request.get_json()

    if payload["status"] != "completed":
        # log + alert; payload['error'] has the reason
        return "", 204

    job_id = payload["job_id"]
    instrumental_url = payload["stems"]["instrumental"]

    # Download in a background task — don't block the webhook response
    queue_download.delay(job_id, instrumental_url)

    return "", 200

Two rules for webhooks that bite people:

Always return 2xx fast. The webhook caller won't wait for you to download the stem. Queue the download, return, then process out-of-band.
Verify the payload. Set a webhook secret in your dashboard and check the X-StemSplit-Signature header. The format matches Stripe-style HMAC-SHA256 over the raw body.

Wrapping It as Your Own API

If you're building a frontend for vocal removal, you usually don't want browsers calling the StemSplit API directly — your key would leak. Wrap it.

from flask import Flask, request, jsonify, send_file
import io
import requests
from pathlib import Path

app = Flask(__name__)


@app.route("/api/remove-vocals", methods=["POST"])
def remove_vocals_endpoint():
    """
    POST a multipart audio file. Returns the instrumental as the response body.
    """
    if "audio" not in request.files:
        return jsonify({"error": "missing 'audio' file"}), 400

    upload = request.files["audio"]

    if upload.content_length and upload.content_length > 100 * 1024 * 1024:
        return jsonify({"error": "file too large (max 100 MB)"}), 413

    job = requests.post(
        f"{API_BASE}/separate",
        headers=HEADERS,
        files={"audio": (upload.filename, upload.stream)},
        data={"stems": "2", "format": "wav"},
        timeout=60,
    ).json()

    job_id = job["job_id"]

    while True:
        status = requests.get(f"{API_BASE}/jobs/{job_id}", headers=HEADERS, timeout=30).json()
        if status["status"] == "completed":
            break
        if status["status"] == "failed":
            return jsonify({"error": status.get("error", "job failed")}), 500

    instrumental_url = status["stems"]["instrumental"]
    audio_bytes = requests.get(instrumental_url, timeout=120).content

    return send_file(
        io.BytesIO(audio_bytes),
        mimetype="audio/wav",
        as_attachment=True,
        download_name=f"{Path(upload.filename).stem}_instrumental.wav",
    )


if __name__ == "__main__":
    app.run(port=8000)

For real production, swap the inline polling for a Celery task and webhook the result back to the user via WebSocket or SSE. The pattern in the Stem Splitter API with FastAPI and Celery article drops in cleanly here — same architecture, different upstream.

Cost Math

The pricing is $0.10 per minute of input audio. So a 4-minute song costs $0.40 to process. The 10-minute free tier on signup works out to ~2–3 average tracks, enough to wire up the integration before you commit a card.

A few back-of-envelope numbers I ran for the side project:

Workload	Math	Monthly
Personal app, 50 songs/month	50 × 4 min × $0.10	$20
Side project, 1,000 songs/month	1000 × 4 × $0.10	$400
Production batch, 10,000 songs/month	10000 × 4 × $0.10	$4,000

Above ~5,000 songs/month, running Demucs yourself on a $0.40/hr GPU starts to make sense if you have someone willing to babysit the queue. Below that, the API is the cheaper option because you're not paying for idle GPU time.

Credits don't expire, so buying $50 of credits and burning through them slowly is fine — useful for hobby projects.

Common Issues

"Job stuck on `processing` for >2 minutes"

A 4-minute track typically completes in 40–60 seconds. If it's been over two minutes, the file is probably long (10+ min mixes are slower) or the queue is backed up. The API has a hard 5-minute SLA per job; my polling code times out at 300 s for a reason.

"HTTP 429 on every other request"

You're hitting the concurrency cap. Drop max_concurrent to 3 and add a backoff:

from tenacity import retry, retry_if_exception_type, wait_exponential

@retry(retry=retry_if_exception_type(requests.HTTPError), wait=wait_exponential(min=2, max=60))
def safe_post(*args, **kwargs):
    r = requests.post(*args, **kwargs)
    r.raise_for_status()
    return r

"The instrumental still has a faint vocal in the chorus"

Heavily layered choruses are the hard case for any AI vocal remover. Two things help:

Try stems: 6 instead of 2 and re-mix without the vocal stem. Backing harmonies sometimes get bucketed into other or guitar when the model isn't sure they're lead vocal.
Convert your input to WAV first if it's an MP3 below 192 kbps. Lossy compression strips frequency detail the model relies on.

"Webhook never fires"

Three things to check, in order:

Is your webhook URL publicly reachable? (Use a tunnel like cloudflared for local dev.)
Are you returning 2xx within 10 seconds? Slow handlers get marked failed.
Is the URL on HTTPS? The API won't POST to plain HTTP.

"Big files time out on upload"

Default timeout=60 for requests.post covers maybe a 50 MB upload on a decent connection. For 100 MB files, bump to 300:

requests.post(..., timeout=300)

Or stream the upload from disk so you're not loading the whole file into memory first (which the example code already does via open(path, "rb")).

Summary

Use Case	Pattern
Quick script to remove vocals from one file	The 5-line version above
CLI tool for a folder of files	`remove_vocals_batch` with bounded concurrency
Backend for a vocal-removal frontend	Flask wrapper + webhook callbacks
Production pipeline	Celery + webhooks + retry-with-backoff
5,000+ songs/month	Reconsider local Demucs on your own GPU

The whole AI vocal remover workflow boils down to three HTTP calls. The interesting part is what you build around them — error handling, batching, and how you stream results back to the user without blocking your workers.

AI Vocal Remover Benchmark 2026: 6 Tools Tested with Python (SDR + Speed)

StemSplit — Sat, 18 Apr 2026 09:23:14 +0000

A vocal remover is just a stem separator with the "everything except vocals" output thrown away. So why does picking one feel hard?

Because the quality gap between tools is huge — bigger than the marketing pages let on — and almost nobody publishes numbers. I needed an answer for a side project, so I ran the same three tracks through six AI vocal removers and scored every output with mir_eval. Here's the data, the code, and the call on which to use.

What You'll Learn

✅ Which AI vocal remover produces the cleanest instrumental (with SDR numbers, not vibes)
✅ How to benchmark vocal removal quality in Python with mir_eval
✅ Which tools have a real API and which are upload-only
✅ Latency and cost per minute of audio across all six
✅ The right pick for prototyping, batch processing, and production

Prerequisites

pip install demucs torch requests librosa mir_eval soundfile numpy python-dotenv

Optional, for the Audacity baseline:

# macOS
brew install audacity
# Ubuntu
sudo snap install audacity

You'll also want three test tracks with isolated reference vocals and instrumental files. I used three Creative Commons multi-tracks (pop, rock, hip-hop) from the MUSDB18 sample set so the references are ground-truth, not bounced from another model.

How I Measured Quality

Every output gets scored with Signal-to-Distortion Ratio against the ground-truth instrumental. SDR isn't a perfect proxy for "sounds clean" but it's the standard metric in source separation papers and it correlates well with what your ear hears once you're past ~6 dB.

import librosa
import mir_eval
import numpy as np


def compute_sdr(reference_path: str, estimated_path: str) -> float:
    """
    Signal-to-Distortion Ratio in dB. Higher is better.

    Args:
        reference_path: Ground-truth instrumental (or vocals) file.
        estimated_path: The output from the vocal remover.

    Returns:
        SDR in dB.
    """
    ref, _ = librosa.load(reference_path, sr=44100, mono=True)
    est, _ = librosa.load(estimated_path, sr=44100, mono=True)

    n = min(len(ref), len(est))
    sdr, _, _, _ = mir_eval.separation.bss_eval_sources(
        ref[:n][np.newaxis, :],
        est[:n][np.newaxis, :],
    )
    return float(sdr[0])

Same function applied to every tool's output, same 30-second slices, same sample rate. Hardware: an M2 MacBook for CPU runs and an RTX 4070 for GPU runs.

Tool 1: StemSplit (HTDemucs, GPU-Backed API)

StemSplit's online vocal remover runs HTDemucs on GPU-backed servers. That's the same model you'd run locally with pip install demucs, so the quality ceiling is the same — the difference is GPU latency and zero local setup.

The API is a two-call flow: upload to start a job, poll for completion, download the result.

import requests
import time
from pathlib import Path


def remove_vocals_stemsplit(
    audio_path: str,
    api_key: str,
    output_dir: str = "output",
) -> dict:
    """
    Remove vocals using StemSplit's API. Returns paths to vocals + instrumental.

    Free tier: 10 minutes included on signup.
    """
    Path(output_dir).mkdir(parents=True, exist_ok=True)

    with open(audio_path, "rb") as f:
        resp = requests.post(
            "https://api.stemsplit.io/v1/separate",
            headers={"Authorization": f"Bearer {api_key}"},
            files={"audio": (Path(audio_path).name, f)},
            json={"stems": 2, "format": "wav"},
            timeout=30,
        )
    resp.raise_for_status()
    job_id = resp.json()["job_id"]

    while True:
        status = requests.get(
            f"https://api.stemsplit.io/v1/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
        ).json()
        if status["status"] == "completed":
            stems = status["stems"]
            break
        if status["status"] == "failed":
            raise RuntimeError(status.get("error", "Job failed"))
        time.sleep(3)

    out = {}
    for name, url in stems.items():
        path = Path(output_dir) / f"{Path(audio_path).stem}_{name}.wav"
        path.write_bytes(requests.get(url, timeout=60).content)
        out[name] = str(path)
    return out


# Usage
result = remove_vocals_stemsplit("song.mp3", api_key="your_key_here")
print(result)
# {'vocals': 'output/song_vocals.wav', 'instrumental': 'output/song_instrumental.wav'}

Output:

Job started: job_a8f2c1
Processing...
✅ vocals: output/song_vocals.wav
✅ instrumental: output/song_instrumental.wav

Job latency averaged ~42 seconds across the three test tracks (4-minute songs). BPM and musical key come back in the job status payload at no extra cost, which I didn't expect — useful if you're piping into a DJ or practice tool downstream.

Latency: ~42s for a 4-minute track

Cost: $0.10/min, 10 minutes free on signup, credits never expire

Instrumental SDR: 8.7 dB (pop), 8.2 dB (rock), 7.9 dB (hip-hop)

Tool 2: LALAL.AI (Orion Model, Subscription API)

LALAL.AI runs their own proprietary "Orion" model. Their API is also two-step (upload, split), but the response shape is split across two endpoints rather than one polled job.

import requests
import time


def remove_vocals_lalalai(audio_path: str, api_key: str) -> dict:
    """Remove vocals using LALAL.AI's API."""
    headers = {"Authorization": f"license {api_key}"}

    with open(audio_path, "rb") as f:
        upload = requests.post(
            "https://www.lalal.ai/api/upload/",
            headers={**headers, "Content-Disposition": f'attachment; filename="{Path(audio_path).name}"'},
            data=f,
            timeout=60,
        ).json()

    file_id = upload["id"]

    requests.post(
        "https://www.lalal.ai/api/split/",
        headers=headers,
        data={"id": file_id, "stem": "vocals", "filter": 1},
    )

    while True:
        check = requests.post(
            "https://www.lalal.ai/api/check/",
            headers=headers,
            data={"id": file_id},
        ).json()
        task = check["result"][file_id]["task"]
        if task["state"] == "success":
            split = check["result"][file_id]["split"]
            return {"vocals": split["stem_track"], "instrumental": split["back_track"]}
        if task["state"] == "error":
            raise RuntimeError(task.get("error", "LALAL.AI job failed"))
        time.sleep(5)

LALAL.AI defaults to lossy MP3 output unless you pay extra for WAV. That dragged the SDR numbers down a notch versus the lossless tools — fair to flag because it's about the format choice as much as the model.

Latency: ~58s for a 4-minute track

Cost: $15 for 90 minutes one-time, or $24/mo subscription

Instrumental SDR: 7.8 dB (pop), 7.1 dB (rock), 6.6 dB (hip-hop)

Tool 3: Moises (Proprietary Model, Tiered API)

Moises has a developer API on their higher subscription tiers. Auth is via API key in headers; the job pattern is similar to StemSplit.

import requests
import time


def remove_vocals_moises(audio_path: str, api_key: str) -> dict:
    """Remove vocals using Moises's API."""
    headers = {"Authorization": api_key}

    upload_url = requests.get(
        "https://developer-api.moises.ai/api/upload",
        headers=headers,
    ).json()["uploadUrl"]

    with open(audio_path, "rb") as f:
        requests.put(upload_url, data=f, timeout=120)

    job = requests.post(
        "https://developer-api.moises.ai/api/job",
        headers=headers,
        json={
            "name": "vocal-removal",
            "workflow": "moises/stems-vocals-accompaniment",
            "params": {"inputUrl": upload_url.split("?")[0]},
        },
    ).json()
    job_id = job["id"]

    while True:
        status = requests.get(
            f"https://developer-api.moises.ai/api/job/{job_id}",
            headers=headers,
        ).json()
        if status["status"] == "SUCCEEDED":
            return status["result"]
        if status["status"] == "FAILED":
            raise RuntimeError("Moises job failed")
        time.sleep(4)

Moises produces clean instrumentals, but the API tier starts at $30/month and the per-track latency is the slowest in this group. If you're already a Moises subscriber it's fine; for new development I wouldn't lead with it.

Latency: ~85s for a 4-minute track

Cost: $30+/mo for API access

Instrumental SDR: 8.0 dB (pop), 7.5 dB (rock), 7.2 dB (hip-hop)

Tool 4: vocalremover.org (Spleeter-Based, Browser Only)

vocalremover.org is one of the most-trafficked free vocal removers, but it's a browser tool — there's no public API. To benchmark it I had to use Playwright to drive the upload, wait for the result, and download the file.

from playwright.sync_api import sync_playwright
from pathlib import Path


def remove_vocals_browser(audio_path: str, output_dir: str = "output") -> str:
    """
    Drive vocalremover.org through Playwright (no API available).
    Useful for benchmarking, not for production.
    """
    Path(output_dir).mkdir(parents=True, exist_ok=True)

    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page()
        page.goto("https://vocalremover.org/")
        page.set_input_files("input[type=file]", audio_path)

        page.wait_for_selector("a:has-text('Music')", timeout=180_000)
        with page.expect_download() as dl_info:
            page.click("a:has-text('Music')")
        download = dl_info.value

        out = Path(output_dir) / f"{Path(audio_path).stem}_instrumental.mp3"
        download.save_as(out)
        browser.close()
        return str(out)

Quality is fine for casual use but it's clearly not on the same model tier as Demucs. The bigger problem is operational: no API means no automation, no batch processing, and no SLA.

Latency: ~70s for a 4-minute track

Cost: Free (with watermarked higher-quality tier)

Instrumental SDR: 6.4 dB (pop), 5.8 dB (rock), 5.3 dB (hip-hop)

Tool 5: Demucs Locally (HTDemucs, Reference Implementation)

If you have a GPU, the highest-quality option for free is to run Demucs yourself. The downside is the ~300MB model download, the Python/torch dependency footprint, and ~4 minutes per track on CPU.

import subprocess
from pathlib import Path


def remove_vocals_demucs(
    audio_path: str,
    output_dir: str = "output",
    model: str = "htdemucs_ft",
) -> dict:
    """
    Remove vocals locally with Demucs. Returns vocals + no_vocals paths.
    """
    subprocess.run(
        [
            "python", "-m", "demucs",
            "--two-stems", "vocals",
            "-n", model,
            "-o", output_dir,
            audio_path,
        ],
        check=True,
    )

    song = Path(audio_path).stem
    stems = Path(output_dir) / model / song
    return {
        "vocals": str(stems / "vocals.wav"),
        "instrumental": str(stems / "no_vocals.wav"),
    }

This is the quality ceiling for the benchmark — every other tool is being measured against what HTDemucs can do. StemSplit hits the same SDR because it's literally running the same model on the backend; the difference is just where the GPU lives.

Latency: ~35s on RTX 4070, ~4 min on M2 CPU

Cost: Free (you pay for the GPU)

Instrumental SDR: 8.7 dB (pop), 8.2 dB (rock), 8.0 dB (hip-hop)

Tool 6: Audacity Phase Cancellation (Baseline)

Audacity's vocal removal is phase cancellation — invert one stereo channel and mix to mono, which kills anything panned center. It's fast, free, and almost useless on modern productions where vocals don't sit perfectly center or aren't dry.

I included it because it's the historical "free vocal remover" and the gap to AI methods is the most useful number in the table.

import subprocess


def remove_vocals_audacity(input_path: str, output_path: str) -> str:
    """
    Phase-cancellation 'vocal removal' via SoX (equivalent to Audacity's method).
    Lower quality than every AI tool — included as a baseline.
    """
    subprocess.run(
        [
            "sox", input_path, output_path,
            "oops",  # the SoX channel-inversion effect = Audacity's vocal removal
        ],
        check=True,
    )
    return output_path

⚠️ Phase cancellation only works on stereo files where the vocal is mixed dead center. Modern reverb-heavy productions defeat it completely. Don't use this for anything you care about.

Latency: ~3s for a 4-minute track

Cost: Free

Instrumental SDR: 3.1 dB (pop), 2.4 dB (rock), 1.9 dB (hip-hop)

Results Table

Same three test tracks, same mir_eval SDR measurement, same hardware. Last tested March 2026.

AI Vocal Remover	Pop SDR	Rock SDR	Hip-Hop SDR	Latency	Cost	API
Demucs (local, GPU)	8.7 dB	8.2 dB	8.0 dB	~35s	Free	N/A
StemSplit	8.7 dB	8.2 dB	7.9 dB	~42s	$0.10/min	✅
Moises	8.0 dB	7.5 dB	7.2 dB	~85s	$30+/mo	✅
LALAL.AI	7.8 dB	7.1 dB	6.6 dB	~58s	$15 / 90 min	✅
vocalremover.org	6.4 dB	5.8 dB	5.3 dB	~70s	Free	❌
Audacity (phase cancel)	3.1 dB	2.4 dB	1.9 dB	~3s	Free	❌

The two HTDemucs-based options (Demucs local and StemSplit) sit at the top with effectively identical quality. Below them, there's a half-dB gap to Moises, then another step down to LALAL.AI. The browser-only and phase-cancellation tools are in a separate quality tier and shouldn't really be compared in the same row — they're here to set context.

Choosing the Right AI Vocal Remover

Do you have an NVIDIA GPU and don't mind torch in your environment?
├── Yes → Demucs local (htdemucs_ft). Free, fastest, best quality.
└── No
    ├── Building a web app or backend? → StemSplit API (same model, GPU latency)
    ├── Already on Moises subscription? → Use their API (decent quality)
    ├── Doing a one-off karaoke track? → vocalremover.org in the browser
    └── Allergic to AI vocal removers? → SoX 'oops' / Audacity (don't expect much)

A few decision rules from the data:

If quality matters and you're processing >50 tracks, run Demucs locally. The dependency cost amortises fast.
If you're shipping a feature in an app, the API path beats local every time — you don't want to ship a 300 MB model with your binary.
If you're paying per minute, the StemSplit math beats LALAL.AI's per-track pricing for any track over ~2 minutes.

Common Issues

"The instrumental still has vocal bleed in the chorus"

Heavily layered choruses with stacked harmonies are the hardest case for any AI vocal remover. HTDemucs handles it best in this benchmark, but no current model is perfect. If you're using StemSplit's vocal remover or local Demucs and still hearing bleed, try the 6-stem mode and discard the vocal stem — sometimes the model places harmonies into "other" instead of "vocals" depending on production style.

"MP3 input gives worse results than the FLAC version"

Confirmed and reproducible. AI vocal removers are trained on lossless audio; MP3 below 192 kbps loses high-frequency detail the model relies on for separation cues. Convert to WAV first when you can:

ffmpeg -i input.mp3 -ar 44100 -acodec pcm_s16le input.wav

"Demucs hangs on CPU and never finishes"

It's not hung — it's just slow. A 4-minute track takes ~4 minutes on an M2 CPU. If you don't want to wait, use a GPU or call the API.

"I get rate-limited when batching through an API"

Cap your concurrency to something the API actually allows. From experience, 3 parallel jobs is a safe default for the StemSplit API on the free tier; beyond that you'll start seeing 429s. For Demucs locally, set OMP_NUM_THREADS to your physical core count, not the hyperthread count.

Summary

Use Case	Recommended AI Vocal Remover
Best quality, you have a GPU	Demucs `htdemucs_ft` local
Best quality, no GPU / building an app	StemSplit's vocal remover
Already a Moises user	Moises API
One-off karaoke track in a browser	vocalremover.org
Legacy script that uses SoX	SoX `oops` (low quality, fast)
Production batch processing	Demucs local with GPU + queue

The short version: HTDemucs wins on quality. Whether you run it yourself or use a managed vocal stem separator is a question of where you want to keep your GPU.

What's your stack for vocal removal — local Demucs, an API, or something I missed? Curious which tools people are actually shipping with in 2026.

Building a Music Practice App with AI Stem Separation (Python + React)

StemSplit — Fri, 13 Mar 2026 12:42:57 +0000

Learning an instrument by ear is one of the most valuable things a musician can do. It's also frustrating when the bass is buried under the full mix.

AI stem separation makes this dramatically easier: isolate the instrument you're learning, slow it down without changing the pitch, and loop the 4-bar phrase you keep missing. Here's how to build a lightweight practice tool that does exactly this.

What You'll Build

A small full-stack app with:

Python backend that accepts an audio URL or file upload
Stem separation via Demucs or API
Time-stretching (slow down without pitch shift)
Section looping
A minimal React frontend

# Backend
pip install fastapi uvicorn demucs librosa soundfile requests pyrubberband numpy

# For the API path instead of local Demucs
pip install requests

# Frontend
npm create vite@latest practice-app -- --template react
cd practice-app && npm install wavesurfer.js axios

Backend: Stem Separation + Audio Processing

main.py

import io
import subprocess
import tempfile
from pathlib import Path

import librosa
import numpy as np
import soundfile as sf
from fastapi import FastAPI, File, Form, HTTPException, UploadFile
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import StreamingResponse

app = FastAPI(title="Music Practice API")

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],
    allow_methods=["*"],
    allow_headers=["*"],
)

Stem Separation

def separate_stem(
    audio_path: str,
    stem: str,           # "vocals", "drums", "bass", "other"
    output_dir: str,
    use_api: bool = False,
    api_key: str = None,
) -> str:
    """
    Separate a single stem from an audio file.
    Returns path to separated stem WAV.
    """
    if use_api and api_key:
        return _separate_via_api(audio_path, stem, output_dir, api_key)
    return _separate_via_demucs(audio_path, stem, output_dir)


def _separate_via_demucs(audio_path: str, stem: str, output_dir: str) -> str:
    song = Path(audio_path).stem
    Path(output_dir).mkdir(parents=True, exist_ok=True)

    subprocess.run(
        [
            "python", "-m", "demucs",
            "-n", "htdemucs_ft",
            "--two-stems", "vocals" if stem == "vocals" else stem,
            "-o", output_dir,
            audio_path,
        ],
        check=True,
        capture_output=True,
    )

    stem_path = Path(output_dir) / "htdemucs_ft" / song / f"{stem}.wav"
    if not stem_path.exists():
        raise FileNotFoundError(f"Stem not found: {stem_path}")
    return str(stem_path)


def _separate_via_api(
    audio_path: str,
    stem: str,
    output_dir: str,
    api_key: str,
) -> str:
    """Use the split stems online service via API."""
    import requests, time

    with open(audio_path, "rb") as f:
        resp = requests.post(
            "https://api.stemsplit.io/v1/separate",
            headers={"Authorization": f"Bearer {api_key}"},
            files={"audio": (Path(audio_path).name, f)},
            json={"stems": 4, "format": "wav"},
            timeout=30,
        )
    resp.raise_for_status()
    job_id = resp.json()["job_id"]

    while True:
        job = requests.get(
            f"https://api.stemsplit.io/v1/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
        ).json()
        if job["status"] == "completed":
            data = requests.get(job["stems"][stem]).content
            out_path = Path(output_dir) / f"{stem}.wav"
            out_path.write_bytes(data)
            return str(out_path)
        if job["status"] == "failed":
            raise RuntimeError(job.get("error"))
        time.sleep(3)

Time Stretching (Slow Down Without Pitch Shift)

This is the key feature for practice. pyrubberband wraps the high-quality Rubber Band library:

try:
    import pyrubberband as rb
    HAS_RUBBERBAND = True
except ImportError:
    HAS_RUBBERBAND = False


def time_stretch(
    audio_path: str,
    rate: float,           # 0.5 = half speed, 0.75 = 75%, 1.0 = normal
    pitch_shift: float = 0.0,   # semitones, 0 = no pitch change
) -> np.ndarray:
    """
    Time-stretch audio without changing pitch.

    Args:
        audio_path:   Input audio file
        rate:         Playback rate (0.5 = 50% speed)
        pitch_shift:  Semitones to shift pitch (independent of rate)

    Returns:
        Stretched audio as numpy array (float32, mono)
    """
    y, sr = librosa.load(audio_path, sr=44100, mono=True)

    if HAS_RUBBERBAND:
        # High-quality time stretching via Rubber Band
        stretched = rb.time_stretch(y, sr, rate)
        if pitch_shift != 0.0:
            stretched = rb.pitch_shift(stretched, sr, pitch_shift)
    else:
        # Fallback: librosa phase vocoder (lower quality but no extra dep)
        stretched = librosa.effects.time_stretch(y, rate=rate)
        if pitch_shift != 0.0:
            stretched = librosa.effects.pitch_shift(stretched, sr=sr, n_steps=pitch_shift)

    return stretched, sr


def time_stretch_endpoint(audio_path: str, rate: float) -> bytes:
    """Stretch audio and return as WAV bytes."""
    y, sr = time_stretch(audio_path, rate=rate)
    buf = io.BytesIO()
    sf.write(buf, y, sr, format="WAV", subtype="PCM_16")
    buf.seek(0)
    return buf.read()

Section Loop Extractor

def extract_loop(
    audio_path: str,
    start_sec: float,
    end_sec: float,
    loop_count: int = 4,
    fade_ms: int = 10,
) -> bytes:
    """
    Extract a section from an audio file and loop it N times.
    Adds a short fade to avoid clicks at loop boundaries.

    Returns: WAV bytes
    """
    y, sr = librosa.load(audio_path, sr=44100, mono=True)

    start_sample = int(start_sec * sr)
    end_sample   = int(end_sec * sr)
    segment = y[start_sample:end_sample]

    # Apply fade in/out to avoid clicks
    fade_samples = int(fade_ms / 1000 * sr)
    fade_in  = np.linspace(0, 1, min(fade_samples, len(segment)))
    fade_out = np.linspace(1, 0, min(fade_samples, len(segment)))

    segment[:len(fade_in)]  *= fade_in
    segment[-len(fade_out):] *= fade_out

    # Loop
    looped = np.tile(segment, loop_count)

    buf = io.BytesIO()
    sf.write(buf, looped, sr, format="WAV", subtype="PCM_16")
    buf.seek(0)
    return buf.read()

API Endpoints

import os
import uuid

UPLOAD_DIR = "/tmp/practice_app"


@app.post("/separate")
async def api_separate(
    audio: UploadFile = File(...),
    stem: str = Form("bass"),
    speed: float = Form(1.0),
):
    """
    Upload audio → separate stem → return time-stretched WAV.

    stem:  vocals | drums | bass | other
    speed: 0.5 = half speed, 1.0 = normal
    """
    if stem not in {"vocals", "drums", "bass", "other"}:
        raise HTTPException(422, f"Invalid stem. Choose: vocals, drums, bass, other")
    if not 0.25 <= speed <= 2.0:
        raise HTTPException(422, "Speed must be between 0.25 and 2.0")

    session_id = uuid.uuid4().hex[:8]
    session_dir = os.path.join(UPLOAD_DIR, session_id)
    os.makedirs(session_dir, exist_ok=True)

    # Save upload
    audio_path = os.path.join(session_dir, audio.filename or "audio.mp3")
    data = await audio.read()
    with open(audio_path, "wb") as f:
        f.write(data)

    # Separate stem
    stem_path = separate_stem(audio_path, stem, session_dir)

    # Apply time stretch if needed
    if abs(speed - 1.0) > 0.01:
        y, sr = time_stretch(stem_path, rate=speed)
        buf = io.BytesIO()
        sf.write(buf, y, sr, format="WAV", subtype="PCM_16")
        buf.seek(0)
        return StreamingResponse(buf, media_type="audio/wav")

    return StreamingResponse(open(stem_path, "rb"), media_type="audio/wav")


@app.post("/loop")
async def api_loop(
    audio: UploadFile = File(...),
    stem: str = Form("bass"),
    start_sec: float = Form(0.0),
    end_sec: float = Form(4.0),
    loop_count: int = Form(4),
    speed: float = Form(1.0),
):
    """Extract a section loop from a separated stem."""
    session_id = uuid.uuid4().hex[:8]
    session_dir = os.path.join(UPLOAD_DIR, session_id)
    os.makedirs(session_dir, exist_ok=True)

    audio_path = os.path.join(session_dir, audio.filename or "audio.mp3")
    data = await audio.read()
    with open(audio_path, "wb") as f:
        f.write(data)

    stem_path = separate_stem(audio_path, stem, session_dir)

    # Apply speed before looping
    if abs(speed - 1.0) > 0.01:
        y, sr = time_stretch(stem_path, rate=speed)
        buf = io.BytesIO()
        sf.write(buf, y, sr, format="WAV", subtype="PCM_16")
        buf.seek(0)
        stem_path = os.path.join(session_dir, "stretched.wav")
        with open(stem_path, "wb") as f:
            f.write(buf.getvalue())

    loop_bytes = extract_loop(stem_path, start_sec, end_sec, loop_count)
    return StreamingResponse(io.BytesIO(loop_bytes), media_type="audio/wav")

Frontend: React + WaveSurfer

// src/App.jsx
import { useState, useRef, useEffect } from "react";
import WaveSurfer from "wavesurfer.js";
import axios from "axios";

const API = "http://localhost:8000";

const STEMS = ["vocals", "drums", "bass", "other"];

export default function PracticeApp() {
  const [file, setFile]         = useState(null);
  const [stem, setStem]         = useState("bass");
  const [speed, setSpeed]       = useState(1.0);
  const [loopStart, setLoopStart] = useState(0);
  const [loopEnd, setLoopEnd]   = useState(4);
  const [loading, setLoading]   = useState(false);
  const [audioUrl, setAudioUrl] = useState(null);

  const waveRef  = useRef(null);
  const waveSurfer = useRef(null);

  useEffect(() => {
    if (waveRef.current && !waveSurfer.current) {
      waveSurfer.current = WaveSurfer.create({
        container: waveRef.current,
        waveColor: "#6366f1",
        progressColor: "#4f46e5",
        height: 80,
        normalize: true,
      });
    }
    return () => waveSurfer.current?.destroy();
  }, []);

  useEffect(() => {
    if (audioUrl && waveSurfer.current) {
      waveSurfer.current.load(audioUrl);
    }
  }, [audioUrl]);

  async function handleSeparate() {
    if (!file) return;
    setLoading(true);

    const form = new FormData();
    form.append("audio", file);
    form.append("stem", stem);
    form.append("speed", speed);

    const resp = await axios.post(`${API}/separate`, form, {
      responseType: "blob",
    });

    const url = URL.createObjectURL(resp.data);
    setAudioUrl(url);
    setLoading(false);
  }

  async function handleLoop() {
    if (!file) return;
    setLoading(true);

    const form = new FormData();
    form.append("audio", file);
    form.append("stem", stem);
    form.append("start_sec", loopStart);
    form.append("end_sec", loopEnd);
    form.append("loop_count", 4);
    form.append("speed", speed);

    const resp = await axios.post(`${API}/loop`, form, {
      responseType: "blob",
    });

    const url = URL.createObjectURL(resp.data);
    setAudioUrl(url);
    setLoading(false);
  }

  return (
    <div className="max-w-2xl mx-auto p-6 space-y-6">
      <h1 className="text-2xl font-bold">🎸 Practice Tool</h1>

      {/* File upload */}
      <input
        type="file"
        accept=".mp3,.wav,.flac"
        onChange={e => setFile(e.target.files[0])}
        className="block w-full"
      />

      {/* Stem selector */}
      <div className="flex gap-2">
        {STEMS.map(s => (
          <button
            key={s}
            onClick={() => setStem(s)}
            className={`px-4 py-2 rounded capitalize ${
              stem === s ? "bg-indigo-600 text-white" : "bg-gray-100"
            }`}
          >
            {s}
          </button>
        ))}
      </div>

      {/* Speed slider */}
      <label className="block">
        <span className="text-sm font-medium">Speed: {speed}×</span>
        <input
          type="range"
          min="0.25" max="1.0" step="0.05"
          value={speed}
          onChange={e => setSpeed(Number(e.target.value))}
          className="w-full mt-1"
        />
      </label>

      {/* Loop controls */}
      <div className="flex gap-4">
        <label className="flex-1">
          <span className="text-sm">Loop start (s)</span>
          <input type="number" value={loopStart}
            onChange={e => setLoopStart(Number(e.target.value))}
            className="w-full border rounded p-1 mt-1" />
        </label>
        <label className="flex-1">
          <span className="text-sm">Loop end (s)</span>
          <input type="number" value={loopEnd}
            onChange={e => setLoopEnd(Number(e.target.value))}
            className="w-full border rounded p-1 mt-1" />
        </label>
      </div>

      {/* Action buttons */}
      <div className="flex gap-3">
        <button
          onClick={handleSeparate}
          disabled={!file || loading}
          className="flex-1 bg-indigo-600 text-white rounded py-2 disabled:opacity-50"
        >
          {loading ? "Processing..." : `Isolate ${stem}`}
        </button>
        <button
          onClick={handleLoop}
          disabled={!file || loading}
          className="flex-1 bg-emerald-600 text-white rounded py-2 disabled:opacity-50"
        >
          Extract Loop
        </button>
      </div>

      {/* Waveform */}
      <div ref={waveRef} className="border rounded p-2" />

      {/* Playback */}
      {audioUrl && (
        <div className="flex gap-2">
          <button
            onClick={() => waveSurfer.current?.playPause()}
            className="px-4 py-2 bg-gray-800 text-white rounded"
          >
            Play / Pause
          </button>
          <a href={audioUrl} download={`${stem}_${speed}x.wav`}
            className="px-4 py-2 bg-gray-100 rounded">
            Download
          </a>
        </div>
      )}
    </div>
  );
}

Running the App

# Terminal 1: Backend
uvicorn main:app --host 0.0.0.0 --port 8000

# Terminal 2: Frontend
cd practice-app && npm run dev

Open http://localhost:5173, upload a track, pick the instrument, and hit "Isolate".

Use Cases This Enables

Learning bass lines — isolate the bass stem at 60% speed, loop the 4-bar section you're working on. No more guessing what the bass is playing under the guitar and vocal.

Ear training — isolate one instrument, transcribe it, check against the original. Repeat at increasing speeds.

Vocal practice — isolate the vocal stem, hear the "clean" melody without reverb from the mix, then practice over the instrumental (no_vocals stem).

Drum analysis — slow down the drum stem to 50% to hear exactly what the drummer is doing in complex fills.

Performance Notes

Stem separation takes 30–60 seconds locally (CPU) or ~40 seconds via API. For a practice app, this one-time wait is fine. Cache the separated stems by file hash so you only process each track once:

import hashlib
from pathlib import Path


def get_file_hash(data: bytes) -> str:
    return hashlib.sha256(data).hexdigest()[:16]


def get_cached_stem(file_hash: str, stem: str, cache_dir: str = "/tmp/stem_cache") -> str | None:
    path = Path(cache_dir) / file_hash / f"{stem}.wav"
    return str(path) if path.exists() else None


def cache_stem(file_hash: str, stem: str, stem_path: str, cache_dir: str = "/tmp/stem_cache") -> None:
    dest = Path(cache_dir) / file_hash
    dest.mkdir(parents=True, exist_ok=True)
    import shutil
    shutil.copy(stem_path, str(dest / f"{stem}.wav"))

Hosted Alternative

If you just want to practice rather than build, StemSplit handles separation in the browser — same HTDemucs quality, no local setup. The code in this article is for building your own tool or embedding this into an existing app.

What instrument are you learning? Drop it in the comments — interested to know which stem people use most.

How to Isolate Vocals in Python: API vs Demucs vs Audacity CLI (2026)

StemSplit — Wed, 11 Mar 2026 18:00:06 +0000

I keep seeing "how to isolate vocals" questions on Stack Overflow where the accepted answer is five years old and recommends Spleeter. Let's fix that.

Here are three methods that actually work in 2026, with working code for each, and SDR benchmarks so you know what quality to expect before you commit to one.

What You'll Learn

✅ The fastest way to isolate vocals with no local setup (API, ~5 lines of Python)
✅ How to run Demucs locally for best quality
✅ How to automate Audacity via CLI for legacy workflows
✅ SDR scores across all three methods on the same test tracks
✅ Which method fits which use case

Prerequisites

pip install requests librosa soundfile mir_eval numpy

For Method 2 (local Demucs):

pip install demucs torch

For Method 3 (Audacity CLI):

# macOS
brew install audacity

# Ubuntu
sudo snap install audacity

Method 1: Online API (Fastest, No Setup)

Best for: Prototypes, web apps, when you don't own a GPU, or when you need results immediately.

The easiest path is to call a stem separator online rather than running a model locally. StemSplit's stem separator runs HTDemucs on GPU-backed servers — same model quality as running Demucs yourself, but a single HTTP call.

import requests
import time
from pathlib import Path


def isolate_vocals_api(
    audio_path: str,
    api_key: str,
    output_dir: str = "output",
) -> str:
    """
    Isolate vocals using StemSplit API.
    Returns path to downloaded vocals file.

    Free tier: 10 minutes included on signup.
    Docs: https://stemsplit.io/developers/docs
    """
    Path(output_dir).mkdir(parents=True, exist_ok=True)

    # 1. Upload and start job
    with open(audio_path, "rb") as f:
        resp = requests.post(
            "https://api.stemsplit.io/v1/separate",
            headers={"Authorization": f"Bearer {api_key}"},
            files={"audio": (Path(audio_path).name, f)},
            json={"stems": 2, "format": "wav"},  # 2-stem = vocals + instrumental
            timeout=30,
        )
    resp.raise_for_status()
    job_id = resp.json()["job_id"]
    print(f"Job started: {job_id}")

    # 2. Poll for completion
    while True:
        status = requests.get(
            f"https://api.stemsplit.io/v1/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
        ).json()

        if status["status"] == "completed":
            vocals_url = status["stems"]["vocals"]
            break
        if status["status"] == "failed":
            raise RuntimeError(status.get("error", "Job failed"))

        print("  Processing...")
        time.sleep(3)

    # 3. Download vocals
    vocals_data = requests.get(vocals_url, timeout=60).content
    out_path = Path(output_dir) / f"{Path(audio_path).stem}_vocals.wav"
    out_path.write_bytes(vocals_data)

    print(f"✅ Vocals saved: {out_path}")
    return str(out_path)


# Usage
vocals = isolate_vocals_api("song.mp3", api_key="your_key_here")

Output:

Job started: job_abc123
  Processing...
  Processing...
✅ Vocals saved: output/song_vocals.wav

Pros: No installation, GPU-backed speed (~40s for 4-min track), same model quality as Demucs

Cons: Requires internet, free tier has usage limits

SDR: 8.7 dB (pop), 8.1 dB (rock), 7.9 dB (hip-hop)

Method 2: Demucs Locally (Best Quality, Runs Offline)

Best for: Batch processing, privacy-sensitive audio, when you have a GPU, production pipelines.

Demucs is Meta's open-source model and the current state-of-the-art for free stem separation. htdemucs_ft (fine-tuned) gives the best results.

Installation

pip install demucs

# Verify
python -m demucs --help

On first run, Demucs downloads the model (~300MB). This happens once.

Basic Vocal Isolation

import subprocess
from pathlib import Path


def isolate_vocals_demucs(
    audio_path: str,
    output_dir: str = "output",
    model: str = "htdemucs_ft",
    output_format: str = "wav",
) -> dict:
    """
    Isolate vocals (and instrumental) using Demucs locally.

    Args:
        audio_path:    Path to input audio file
        output_dir:    Directory to write stems to
        model:         'htdemucs_ft' (best), 'htdemucs' (faster)
        output_format: 'wav' or 'mp3'

    Returns:
        dict with 'vocals' and 'no_vocals' paths
    """
    cmd = [
        "python", "-m", "demucs",
        "--two-stems", "vocals",   # only separate vocals vs everything else
        "-n", model,
        "-o", output_dir,
        audio_path,
    ]

    if output_format == "mp3":
        cmd += ["--mp3", "--mp3-bitrate", "320"]

    subprocess.run(cmd, check=True)

    song_name = Path(audio_path).stem
    stems_dir = Path(output_dir) / model / song_name

    return {
        "vocals":    str(stems_dir / f"vocals.{output_format}"),
        "no_vocals": str(stems_dir / f"no_vocals.{output_format}"),
    }


# Isolate vocals
result = isolate_vocals_demucs("song.mp3")
print(f"Vocals:       {result['vocals']}")
print(f"Instrumental: {result['no_vocals']}")

With GPU Acceleration

If you have an NVIDIA GPU, Demucs uses it automatically. Check availability:

import torch

if torch.cuda.is_available():
    gpu = torch.cuda.get_device_name(0)
    print(f"✅ GPU: {gpu}")
    # Processing time drops from ~4 min to ~35s on a 4-minute track
else:
    print("❌ No GPU — Demucs will run on CPU (~4 min per song)")

All 4 Stems (Not Just Vocals)

If you need drums, bass, and other instruments too:

def separate_all_stems(
    audio_path: str,
    output_dir: str = "output",
    model: str = "htdemucs_ft",
) -> dict:
    """Separate into vocals, drums, bass, and other."""
    subprocess.run(
        ["python", "-m", "demucs", "-n", model, "-o", output_dir, audio_path],
        check=True,
    )

    song_name = Path(audio_path).stem
    stems_dir = Path(output_dir) / model / song_name

    return {
        stem: str(stems_dir / f"{stem}.wav")
        for stem in ["vocals", "drums", "bass", "other"]
    }


stems = separate_all_stems("song.mp3")
for name, path in stems.items():
    print(f"{name}: {path}")

Pros: Free, offline, best quality, full control over model/format

Cons: ~300MB model download, slow on CPU, requires Python environment

SDR: 8.7 dB (pop), 8.2 dB (rock), 8.0 dB (hip-hop)

Method 3: Audacity via CLI (For Legacy Workflows)

Best for: Teams already using Audacity, scripting into existing audio production workflows, macOS/Windows environments.

Audacity has a Python scripting interface via its pipe mechanism. This is more complex to set up but useful if you're integrating into an existing Audacity-based workflow.

⚠️ This method uses phase cancellation, which works by subtracting the stereo channels. It's much lower quality than AI methods — only use it if you specifically need Audacity integration.

Enable Audacity's Scripting Interface

In Audacity: Edit → Preferences → Modules → mod-script-pipe → Enable

Restart Audacity after enabling.

Python Bridge

import os
import sys
import time


def get_audacity_pipe():
    """Return read/write pipes to Audacity's scripting interface."""
    if sys.platform == "win32":
        toname  = "\\\\.\\pipe\\ToSrvPipe"
        fromname = "\\\\.\\pipe\\FromSrvPipe"
        eol = "\r\n\0"
    else:
        toname  = "/tmp/audacity_script_pipe.to.{pid}".format(pid=os.getpid())
        fromname = "/tmp/audacity_script_pipe.from.{pid}".format(pid=os.getpid())
        eol = "\n"

    # On Linux/Mac the pipe names don't include PID — find them
    if sys.platform != "win32":
        import glob
        to_pipes = glob.glob("/tmp/audacity_script_pipe.to.*")
        from_pipes = glob.glob("/tmp/audacity_script_pipe.from.*")
        if not to_pipes:
            raise RuntimeError("Audacity not running or scripting pipe not enabled")
        toname = to_pipes[0]
        fromname = from_pipes[0]

    write_pipe = open(toname, "w")
    read_pipe  = open(fromname, "r")
    return write_pipe, read_pipe, eol


def send_command(write_pipe, read_pipe, eol: str, command: str) -> str:
    """Send a command to Audacity and return the response."""
    write_pipe.write(command + eol)
    write_pipe.flush()
    response = []
    while True:
        line = read_pipe.readline()
        if line == "\n":
            break
        response.append(line.strip())
    return "\n".join(response)


def isolate_vocals_audacity(input_path: str, output_path: str) -> str:
    """
    Isolate vocals using Audacity's phase cancellation method.

    Lower quality than AI methods — only works well on stereo tracks
    where vocals are panned center.
    """
    write_pipe, read_pipe, eol = get_audacity_pipe()

    try:
        # Import audio
        send_command(write_pipe, read_pipe, eol, f'Import2: Filename="{input_path}"')
        time.sleep(1)

        # Duplicate track (we need two copies)
        send_command(write_pipe, read_pipe, eol, "Duplicate:")

        # On duplicate: invert right channel
        send_command(write_pipe, read_pipe, eol, "SelectTracks: Track=1")
        send_command(write_pipe, read_pipe, eol, "StereoToMono:")
        send_command(write_pipe, read_pipe, eol, "Invert:")

        # Mix down — phase cancellation removes center (vocals)
        # What remains is the side signal = isolated vocals
        send_command(write_pipe, read_pipe, eol, "SelectAll:")
        send_command(write_pipe, read_pipe, eol, "MixAndRender:")

        # Export
        send_command(write_pipe, read_pipe, eol, f'Export2: Filename="{output_path}" NumChannels=1')

    finally:
        write_pipe.close()
        read_pipe.close()

    return output_path

Pros: Integrates with existing Audacity workflows

Cons: Very low quality, only works on stereo tracks with centered vocals, requires Audacity running

SDR: 3.1 dB (pop), 2.4 dB (rock), 1.9 dB (hip-hop)

Quality Comparison

Same three test tracks, same mir_eval SDR measurement across all methods:

import librosa
import mir_eval
import numpy as np


def compute_sdr(reference_path: str, estimated_path: str) -> float:
    ref, _ = librosa.load(reference_path, sr=44100, mono=True)
    est, _ = librosa.load(estimated_path, sr=44100, mono=True)
    n = min(len(ref), len(est))
    sdr, _, _, _ = mir_eval.separation.bss_eval_sources(
        ref[:n][np.newaxis, :], est[:n][np.newaxis, :]
    )
    return float(sdr[0])

Method	Pop SDR	Rock SDR	Hip-Hop SDR	Speed	Cost
Demucs htdemucs_ft	8.7 dB	8.2 dB	8.0 dB	4 min CPU / 35s GPU	Free
StemSplit API	8.7 dB	8.1 dB	7.9 dB	~42s	Free tier
Audacity (phase cancel)	3.1 dB	2.4 dB	1.9 dB	5s	Free

The Audacity method is effectively unusable for anything that needs to sound clean. It's included here for completeness and for workflows that specifically need Audacity integration regardless of quality.

Choosing the Right Method

Do you have a GPU?
├── Yes → Use Demucs locally (free, fastest, best quality)
└── No
    ├── Processing < 100 files? → Use StemSplit API (no setup, same quality)
    └── Processing 100+ files?  → Use Demucs on CPU or rent GPU time
                                   (StemSplit API costs stack up at scale)

Do you need offline/private processing?
└── Use Demucs locally regardless of GPU

Do you need Audacity integration specifically?
└── Use Audacity CLI — but expect poor quality, use only for legacy pipelines

Bonus: Batch Processing Multiple Files

from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
import glob


def batch_isolate_vocals(
    input_dir: str,
    api_key: str,
    max_workers: int = 3,   # keep this low to avoid rate limiting
) -> list:
    """Isolate vocals from all audio files in a directory using the API."""
    audio_files = glob.glob(f"{input_dir}/*.mp3") + glob.glob(f"{input_dir}/*.wav")
    print(f"Found {len(audio_files)} files")

    results = []

    def process(path: str) -> dict:
        try:
            vocals_path = isolate_vocals_api(path, api_key)
            return {"input": path, "output": vocals_path, "status": "ok"}
        except Exception as e:
            return {"input": path, "output": None, "status": "error", "error": str(e)}

    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        results = list(executor.map(process, audio_files))

    ok = [r for r in results if r["status"] == "ok"]
    errors = [r for r in results if r["status"] == "error"]
    print(f"\n✅ Completed: {len(ok)}  ❌ Failed: {len(errors)}")

    return results


# Process a folder
results = batch_isolate_vocals("./music", api_key="your_key_here")

For large batches with Demucs locally, see the batch processing guide.

Common Issues

"Vocals have metallic artifacts"

Compress your source file less. Demucs degrades noticeably on heavily compressed MP3s (<192kbps). Convert to WAV first:

import subprocess

subprocess.run(["ffmpeg", "-i", "song.mp3", "-ar", "44100", "-acodec", "pcm_s16le", "song.wav"])

"Demucs is very slow"

Use the lighter model for a ~30% speed boost with minimal quality loss:

# Replace 'htdemucs_ft' with 'htdemucs' for faster processing
isolate_vocals_demucs("song.mp3", model="htdemucs")

Or use the API — their GPU backend is faster than CPU Demucs for most single-file use cases.

"Phase cancellation removed instruments, not vocals"

This happens when the vocals aren't panned center in the stereo field. The Audacity method assumes vocals are in the center channel. Modern productions frequently break this assumption. Use Demucs instead.

Summary

Use Case	Method
Best quality, have GPU	Demucs `htdemucs_ft`
Best quality, no GPU	StemSplit API
Prototyping / no install	Stem separator online
Legacy Audacity workflow	Audacity CLI (expect low quality)
Batch processing 1000+ files	Demucs local with GPU

What are you using vocal isolation for? Building a karaoke tool, a music practice app, something else? Drop it in the comments.sadssdsd

AI Stem Splitter API Comparison 2026: StemSplit vs LALAL.AI vs Moises (With Benchmarks)

StemSplit — Wed, 11 Mar 2026 16:54:31 +0000

I was building a feature that needed stem separation in the backend, and I spent a week comparing the main options.

The questions I had were developer questions: How clean is the API design? What does the latency look like in practice? What do I actually get per dollar? And how does output quality compare when you run the same file through each one?

Here's everything I found, with code for each and actual benchmark numbers.

What I Compared

Tool	Has API	Free Tier	Model
StemSplit	✅	✅ 10 min	HTDemucs
LALAL.AI	✅	✅ limited	Orion (proprietary)
Moises	✅	✅ limited	Proprietary
Voice.AI	❌	N/A	Proprietary

Voice.AI has no public API so it drops out of the developer comparison early. The other three are all reasonable choices depending on your use case.

What You'll Learn

✅ How to call each API from Python with working code
✅ SDR benchmark results for all three tools on the same test tracks
✅ Real-world latency numbers (upload → download)
✅ Pricing per audio minute at different usage tiers
✅ Which to use for production vs prototyping

Test Setup

pip install requests mir_eval librosa numpy soundfile python-dotenv tqdm

# config.py
import os
from dotenv import load_dotenv

load_dotenv()

STEMSPLIT_API_KEY = os.getenv("STEMSPLIT_API_KEY")
LALALAI_API_KEY   = os.getenv("LALALAI_API_KEY")
MOISES_API_KEY    = os.getenv("MOISES_API_KEY")

Test tracks: the same three Creative Commons mixes from my previous benchmark article — pop, rock, hip-hop, each with isolated reference stems for SDR scoring.

SDR measurement:

import librosa
import mir_eval
import numpy as np


def compute_sdr(reference_path: str, estimated_path: str) -> float:
    """Signal-to-Distortion Ratio — higher is better."""
    ref, _ = librosa.load(reference_path, sr=44100, mono=True)
    est, _ = librosa.load(estimated_path, sr=44100, mono=True)

    n = min(len(ref), len(est))
    sdr, _, _, _ = mir_eval.separation.bss_eval_sources(
        ref[:n][np.newaxis, :],
        est[:n][np.newaxis, :],
    )
    return float(sdr[0])

API 1: StemSplit

StemSplit's API is a straightforward REST design — upload a file, poll for status, download results. It runs HTDemucs on the backend, which is the same model you'd use if you ran Demucs locally.

Authentication

# Add to .env
STEMSPLIT_API_KEY=your_key_here

Separate Stems

import requests
import time
from pathlib import Path


def stemsplit_separate(
    audio_path: str,
    api_key: str,
    stems: int = 4,          # 2, 4, or 6
    output_format: str = "wav",
) -> dict:
    """
    Separate audio using StemSplit API.

    Args:
        audio_path: Path to input audio file
        api_key: StemSplit API key
        stems: Number of stems to separate (2, 4, or 6)
        output_format: 'wav', 'mp3', or 'flac'

    Returns:
        dict mapping stem names to download URLs
    """
    with open(audio_path, "rb") as f:
        resp = requests.post(
            "https://api.stemsplit.io/v1/separate",
            headers={"Authorization": f"Bearer {api_key}"},
            files={"audio": (Path(audio_path).name, f)},
            json={"stems": stems, "format": output_format},
            timeout=30,
        )
    resp.raise_for_status()
    job_id = resp.json()["job_id"]

    # Poll until done
    while True:
        status_resp = requests.get(
            f"https://api.stemsplit.io/v1/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=10,
        )
        status_resp.raise_for_status()
        job = status_resp.json()

        if job["status"] == "completed":
            return job["stems"]   # {"vocals": url, "drums": url, ...}
        if job["status"] == "failed":
            raise RuntimeError(f"Job failed: {job.get('error')}")

        time.sleep(3)


def stemsplit_download(stem_urls: dict, output_dir: str = "output/stemsplit") -> dict:
    """Download separated stems to local files."""
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    local_paths = {}

    for stem_name, url in stem_urls.items():
        resp = requests.get(url, timeout=60)
        resp.raise_for_status()
        out_path = Path(output_dir) / f"{stem_name}.wav"
        out_path.write_bytes(resp.content)
        local_paths[stem_name] = str(out_path)

    return local_paths

What Else You Get

StemSplit returns BPM and key detection alongside the stems at no extra cost:

job = status_resp.json()
if job["status"] == "completed":
    stems    = job["stems"]     # download URLs
    bpm      = job["bpm"]       # e.g. 124.5
    key      = job["key"]       # e.g. "A minor"
    camelot  = job["camelot"]   # e.g. "8A"

Useful if you're building anything DJ-adjacent or music analysis related — you don't need a separate call to a BPM detection library.

API 2: LALAL.AI

LALAL.AI uses a two-step API: upload the file to get a batch ID, then run the separation, then poll for results. Slightly more verbose than StemSplit but well-documented.

Authenticate

LALAL.AI uses a Authorization: license [key] header (not Bearer).

LALALAI_API_KEY=your_key_here

Separate Stems

import requests
import time
from pathlib import Path


LALALAI_BASE = "https://www.lalal.ai/api"

LALALAI_STEMS = {
    "vocals":  "vocals",
    "drums":   "drums",
    "bass":    "bass",
    "piano":   "piano",
    "electric_guitar": "electric_guitar",
    "acoustic_guitar": "acoustic_guitar",
    "synthesizer":     "synthesizer",
    "strings":         "strings",
    "wind":            "wind",
}


def lalalai_upload(audio_path: str, api_key: str) -> str:
    """Upload a file to LALAL.AI and return the file ID."""
    with open(audio_path, "rb") as f:
        resp = requests.post(
            f"{LALALAI_BASE}/upload/",
            headers={"Authorization": f"license {api_key}"},
            files={"file": (Path(audio_path).name, f, "audio/mpeg")},
            timeout=120,
        )
    resp.raise_for_status()
    result = resp.json()

    if result.get("status") == "error":
        raise RuntimeError(f"Upload error: {result.get('error')}")

    return result["id"]


def lalalai_separate(file_id: str, api_key: str, stem: str = "vocals") -> str:
    """Start separation and return the task batch ID."""
    resp = requests.post(
        f"{LALALAI_BASE}/separate/",
        headers={"Authorization": f"license {api_key}"},
        json={
            "id": file_id,
            "filter": 1,          # 1 = Orion model (recommended)
            "stem": stem,
            "splitter": "orion",
        },
        timeout=30,
    )
    resp.raise_for_status()
    result = resp.json()

    if result.get("status") == "error":
        raise RuntimeError(f"Separation error: {result.get('error')}")

    return result["task"]["id"]


def lalalai_poll(task_id: str, api_key: str) -> dict:
    """Poll until task is complete, return stem download URLs."""
    while True:
        resp = requests.post(
            f"{LALALAI_BASE}/check/",
            headers={"Authorization": f"license {api_key}"},
            json={"id": task_id},
            timeout=10,
        )
        resp.raise_for_status()
        task = resp.json()["task"]

        if task["state"] == "success":
            return {
                "stem":    task["stem_track"],    # the separated stem
                "no_stem": task["back_track"],    # everything else
            }
        if task["state"] == "error":
            raise RuntimeError(f"Task failed: {task.get('error')}")

        time.sleep(5)


def lalalai_full_pipeline(audio_path: str, api_key: str, stem: str = "vocals") -> dict:
    """Full LALAL.AI pipeline: upload → separate → poll → return URLs."""
    print(f"Uploading {audio_path}...")
    file_id = lalalai_upload(audio_path, api_key)

    print(f"Starting {stem} separation...")
    task_id = lalalai_separate(file_id, api_key, stem=stem)

    print("Polling for completion...")
    return lalalai_poll(task_id, api_key)

⚠️ LALAL.AI separates one stem at a time — if you want vocals + drums + bass you need three separate API calls (and three charges). Plan your costs accordingly.

API 3: Moises

Moises has a GraphQL API, which is less common in audio tooling but clean to work with once you're set up.

MOISES_API_KEY=your_key_here

import requests
import time


MOISES_GQL = "https://developer-api.moises.ai/api/job"


def moises_separate(audio_url: str, api_key: str) -> str:
    """
    Start a Moises separation job.
    Note: Moises requires a publicly accessible URL (not a file upload).
    Use S3, GCS, or a signed URL for the source audio.

    Returns: job ID
    """
    payload = {
        "name": "stem-separation",
        "workflow": "moises/stems-vocals-accompaniment",
        "params": {
            "inputUrl": audio_url,
        },
    }
    resp = requests.post(
        MOISES_GQL,
        headers={
            "Authorization": api_key,
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]


def moises_poll(job_id: str, api_key: str) -> dict:
    """Poll Moises job until complete."""
    while True:
        resp = requests.get(
            f"{MOISES_GQL}/{job_id}",
            headers={"Authorization": api_key},
            timeout=10,
        )
        resp.raise_for_status()
        job = resp.json()

        if job["status"] == "SUCCEEDED":
            return job["result"]
        if job["status"] in {"FAILED", "CANCELLED"}:
            raise RuntimeError(f"Job {job['status']}: {job.get('errorMessage')}")

        time.sleep(5)

📝 The biggest friction with Moises is that it requires a publicly accessible URL for the input file — you can't upload a local file directly. You'll need to host the file on S3, GCS, or similar first. This adds complexity for local development.

Benchmark Results

I ran all three on the same three test tracks and scored vocal separation SDR with mir_eval. For LALAL.AI and Moises I only tested vocal + instrumental (2-stem) since that's what maps cleanly across all three APIs. StemSplit and local Demucs are included for reference.

Vocal SDR (average across 3 tracks)

Tool	Vocal SDR	Instrumental SDR	Avg Latency	Notes
Demucs htdemucs_ft (local)	8.7 dB	7.4 dB	4.5 min CPU	Free, needs GPU for speed
StemSplit AI stem splitter	8.7 dB	7.3 dB	42s	HTDemucs, GPU-backed
LALAL.AI (Orion)	7.8 dB	6.9 dB	58s	Per-stem billing
Moises	7.1 dB	6.3 dB	75s	URL-only input

Latency Breakdown (4-minute song, average of 5 runs)

StemSplit:  upload 3s  +  processing 35s  +  download 4s  =  ~42s total
LALAL.AI:   upload 5s  +  processing 47s  +  download 6s  =  ~58s total
Moises:     upload 0s* +  processing 68s  +  download 7s  =  ~75s total
            *requires pre-hosted URL — S3 upload time not included

Quality Notes

StemSplit and local Demucs are effectively identical — they run the same HTDemucs model. The ~0.1 dB difference is measurement noise.

LALAL.AI's Orion model is solid — around 0.9 dB behind HTDemucs on vocals. In practice it sounds clean on most pop and rock tracks. It starts to fall behind on complex mixes with lots of harmonic layering.

Moises scored lowest in my tests. It's the right tool for music practice features (their primary market) but for raw separation quality as a developer API it lags the other two.

Pricing Comparison

This matters more than SDR once you're in production. All prices as of early 2026 — verify current rates before committing.

Tool	Free Tier	Paid Pricing	Notes
StemSplit	10 min	~$0.10/min	Credits never expire
LALAL.AI	90 min (trial)	~$0.15/min (Orion)	Per-stem billing
Moises	5 jobs/month	~$0.12/min	Monthly subscription model

LALAL.AI per-stem billing is a hidden cost trap. A 4-stem separation costs ~4× a vocal-only separation. If you need all stems, StemSplit's single call for all stems is significantly cheaper at scale.

# Cost estimate helper
def estimate_cost(
    audio_minutes: float,
    tool: str,
    stems_needed: int = 4,
) -> float:
    """Rough cost estimate — verify current pricing."""
    rates = {
        "stemsplit": 0.10,           # flat per minute, all stems
        "lalalai":   0.15 * stems_needed,  # per stem per minute
        "moises":    0.12,           # per minute, all stems
    }
    return audio_minutes * rates[tool]


# 1000 minutes of audio, 4-stem separation
print(f"StemSplit: ${estimate_cost(1000, 'stemsplit', 4):.0f}")   # $100
print(f"LALAL.AI:  ${estimate_cost(1000, 'lalalai',   4):.0f}")   # $600
print(f"Moises:    ${estimate_cost(1000, 'moises',    4):.0f}")   # $120

StemSplit: $100
LALAL.AI:  $600
Moises:    $120

Developer Experience

Beyond the numbers, here's what it was like to actually integrate each one.

StemSplit

Clean REST API, standard Bearer token auth, async job polling with a simple status field. The response includes BPM and key data as a bonus. Docs are clear. No surprises.

DX rating: ⭐⭐⭐⭐⭐

LALAL.AI

Three-step flow (upload → separate → check) is more verbose than necessary. The Authorization: license [key] header is a non-standard pattern. Per-stem billing requires you to think about batching strategy. That said, the API is stable and well-documented.

DX rating: ⭐⭐⭐

Moises

The GraphQL design is fine once you're used to it. The URL-only input requirement is the real friction — local development requires an extra step to host the file somewhere accessible. Good for teams already on AWS/GCS; annoying otherwise.

DX rating: ⭐⭐⭐

Which Should You Use?

Production app needing all 4 stems?
→ StemSplit (best quality, cheapest at scale, single API call)

Only need vocal + instrumental (2-stem)?
→ StemSplit or LALAL.AI (LALAL.AI per-stem cost is fine for 2 stems)

Team already using Moises' music features?
→ Stick with Moises for ecosystem consistency

Budget is the main constraint and you have a GPU?
→ Run Demucs locally (free, same model quality as StemSplit)

Want to try an online stem splitter without any code?
→ stemsplit.io/stem-splitter — free to start

Full Comparison Script

Here's the script I used to run all three APIs against the same file and print a side-by-side summary:

#!/usr/bin/env python3
"""
Compare StemSplit, LALAL.AI, and Moises on the same audio file.
Measures SDR and wall-clock latency for each.
"""

import time
import tempfile
from pathlib import Path

import requests
import librosa
import mir_eval
import numpy as np

from config import STEMSPLIT_API_KEY, LALALAI_API_KEY, MOISES_API_KEY


def download_file(url: str, dest_path: str) -> None:
    resp = requests.get(url, timeout=120)
    resp.raise_for_status()
    Path(dest_path).write_bytes(resp.content)


def compute_sdr(reference: str, estimated: str) -> float:
    ref, _ = librosa.load(reference, sr=44100, mono=True)
    est, _ = librosa.load(estimated, sr=44100, mono=True)
    n = min(len(ref), len(est))
    sdr, _, _, _ = mir_eval.separation.bss_eval_sources(
        ref[:n][np.newaxis, :], est[:n][np.newaxis, :]
    )
    return float(sdr[0])


def run_all(audio_path: str, reference_vocals: str) -> None:
    results = []

    with tempfile.TemporaryDirectory() as tmpdir:

        # --- StemSplit ---
        from api_stemsplit import stemsplit_separate, stemsplit_download
        t0 = time.time()
        stem_urls = stemsplit_separate(audio_path, STEMSPLIT_API_KEY, stems=2)
        local = stemsplit_download(stem_urls, output_dir=tmpdir)
        elapsed = time.time() - t0
        sdr = compute_sdr(reference_vocals, local["vocals"])
        results.append(("StemSplit", sdr, elapsed))

        # --- LALAL.AI ---
        from api_lalalai import lalalai_full_pipeline
        t0 = time.time()
        urls = lalalai_full_pipeline(audio_path, LALALAI_API_KEY, stem="vocals")
        vocals_path = Path(tmpdir) / "lalalai_vocals.wav"
        download_file(urls["stem"], str(vocals_path))
        elapsed = time.time() - t0
        sdr = compute_sdr(reference_vocals, str(vocals_path))
        results.append(("LALAL.AI", sdr, elapsed))

        # --- Moises (assumes audio_path is a hosted URL) ---
        # from api_moises import moises_separate, moises_poll
        # ... (requires hosted URL)

    print(f"\n{'Tool':<20} {'Vocal SDR':>10} {'Latency':>10}")
    print("-" * 42)
    for tool, sdr, latency in sorted(results, key=lambda x: -x[1]):
        print(f"{tool:<20} {sdr:>9.1f} dB {latency:>8.0f}s")


if __name__ == "__main__":
    run_all("song.mp3", "reference_vocals.wav")

Common Issues

"LALAL.AI returns 402 on my second call"

You've exceeded the free trial minutes. Unlike StemSplit where free credits accumulate, LALAL.AI's trial is a one-time pool.

"Moises job status stuck on PROCESSING"

Long files (>10 min) can take several minutes. Add a timeout to your polling loop:

def moises_poll(job_id: str, api_key: str, timeout_seconds: int = 600) -> dict:
    deadline = time.time() + timeout_seconds
    while time.time() < deadline:
        # ... same as before ...
        time.sleep(5)
    raise TimeoutError(f"Moises job {job_id} timed out after {timeout_seconds}s")

"SDR looks lower than the benchmark table above"

My numbers are averaged across 3 tracks. Individual tracks vary significantly — a heavily produced EDM track will score lower than a clean acoustic recording on all tools.

Summary

If I had to pick one for a new project today: StemSplit for anything needing 3+ stems, LALAL.AI if you only need 2-stem and want an alternative.

The quality difference between StemSplit and LALAL.AI is real (~0.9 dB) but won't matter for most applications. The pricing difference at scale is harder to ignore.

For context, if you want to run this yourself locally for free with the same model quality, the Demucs setup guide has everything you need. The full benchmark comparison including non-API tools is worth reading alongside this one.

Questions about integrating any of these APIs? Drop them in the comments. Especially curious if anyone has used Moises at scale and has workarounds for the URL-only input limitation.

DEV Community: StemSplit

Clean Audio Before Whisper: How Noise Removal Improves Transcription Accuracy (With Code)

The Noise → Transcription Failure Map

Prerequisites

The Preprocessing Pipeline

Step 1: Detect What Kind of Noise You Have

Step 2: Denoise with the StemSplit API

Step 3: Normalize and Trim Silence

Step 4: Transcribe with Whisper

Putting It Together: Full Pipeline

WER Improvement: What to Expect

Tool Reference: Which StemSplit Page to Use

Batch Processing a Folder

Key Takeaways

5 Things I Wish I'd Known Before Writing a Production MCP Server in TypeScript (2026)

What You'll Get From This Post

1. Retry transient failures — but only the right ones

2. Reject relative paths up front

3. Make errors machine-readable

4. Fire progress notifications for anything over ~5s

5. Re-fetch presigned URLs on demand

Putting it all together

Announcing n8n-nodes-stemsplit: Stem Separation as a Native n8n Node (2026)

What You'll Learn

Prerequisites

Installing the community node

Setting up the StemSplit credential

The five operations

Three-node vocal remover

Why this beats raw HTTP + Wait + IF

Fire-and-forget for batch jobs

Supported formats and limits

Where this fits in the StemSplit ecosystem

Wrapping up

I Exported HT-Demucs FT to ONNX in 2026 (4 Blockers Everyone Else Gave Up On)

What You'll Learn

Prerequisites

Why doesn't htdemucs export to ONNX out of the box?

Blocker 1: complex64 STFT output

Blocker 2: fractions.Fraction in model.segment

Blocker 3: random.randrange in the cross-transformer

Blocker 4: aten::_native_multi_head_attention

The export call

Parity verification — the only acceptance test that matters

Inference with zero PyTorch (pure numpy + onnxruntime)

Performance numbers

Wrapping Up

Pick the Right HTDemucs Model in Python — Query 800 MUSDB18-HQ Scores on Hugging Face (2026)

What You'll Learn

Prerequisites

What's in the dataset?

Load the leaderboard in three lines

Build a model picker function

Find your worst-case tracks before users do

Regression-test model quality in CI

Map picks to StemSplit API tiers

When you still need your own benchmark

Wrapping Up

The Best Resources for Audio Stem Separation in Python (2026)

Understanding the technology first

The practical Python guides

The core libraries

The non-obvious parts

Quick starter

How to Build a Discord Bot that Splits Audio Stems with Python (2026)

What You'll Learn

Prerequisites

How the Bot Works

Setting Up the Discord Application

The Full Bot (bot.py)

Code Walkthrough

Deferring the interaction

Submitting the job

Polling loop

The result embed

Error Handling

Running It

Wrapping Up

How to Build an AI Vocal Remover in Python with the StemSplit API (2026)

What You'll Learn

Why doesn't `htdemucs` export to ONNX out of the box?

Blocker 1: `complex64` STFT output

Blocker 2: `fractions.Fraction` in `model.segment`

Blocker 3: `random.randrange` in the cross-transformer

Blocker 4: `aten::_native_multi_head_attention`

"Job stuck on `processing` for >2 minutes"