@stemsplit/sdk

Official Node.js / TypeScript SDK for the StemSplit stem-separation API. Typed client with automatic file uploads, job-completion polling, YouTube / SoundCloud jobs, voice denoising, and webhook signature verification. Zero runtime dependencies.

npm install @stemsplit/sdk

import { StemSplit } from '@stemsplit/sdk';

const client = new StemSplit();  // reads STEMSPLIT_API_KEY

// From a URL
const job = await client.jobs.create({
  sourceUrl: 'https://example.com/song.mp3',
  outputType: 'FOUR_STEMS',
});
const done = await job.waitForCompletion();
await done.downloadAll('./stems/');
// → stems/vocals.mp3  stems/drums.mp3  stems/bass.mp3  stems/other.mp3

// From a local file
const job2 = await client.jobs.create({ audio: './song.mp3', outputType: 'BOTH' });
const done2 = await job2.waitForCompletion();
await done2.downloadAll('./out/');
// → out/vocals.mp3  out/instrumental.mp3

Quick links

• API key: stemsplit.io/app/settings/api — new accounts get 5 free minutes
• Developer guide: stemsplit.io/developers/guides/node
• API reference: stemsplit.io/developers/reference
• GitHub: github.com/StemSplit/node-stemsplit
• Changelog: CHANGELOG.md
• Python SDK: stemsplit-python

Features

• StemSplit class with typed sub-resources for every public endpoint
• Automatic file uploads — pass a file path, Buffer, Blob, or Uint8Array and the SDK handles the presigned-URL dance for you
• job.waitForCompletion() — polls until done, returns the completed job; throws typed JobFailedError / JobExpiredError
• job.downloadAll(dir) — downloads all stems to a directory in one call
• jobs.iterAll() — async generator for paginated iteration over all jobs
• YouTube and SoundCloud — separate stems directly from a URL, no download step required
• Voice denoising — remove background noise from recordings via denoiseJobs
• Webhook signature verification in two lines: webhooks.verifyAndParse(body, sig, secret)
• Typed error hierarchy with documented codes — AuthenticationError, InsufficientCreditsError, RateLimitError, JobFailedError, and more
• Automatic retries with exponential backoff + jitter on transient errors and 429 responses; honors Retry-After
• Zero runtime dependencies — uses Node.js built-ins only (node:crypto, node:fs, node:stream)
• Fully typed — ships .d.ts declarations; strict TypeScript clean

When to use this SDK vs alternatives

You want to …	Use
Call the hosted StemSplit API from Node.js / TypeScript	@stemsplit/sdk (this package)
Call the API from Python	stemsplit-python
Use the API from Claude Desktop, Cursor, Cline, or Windsurf	stemsplit-mcp
Wire StemSplit into n8n / Zapier / Make	The no-code guides
Run inference locally without an API key	demucs-onnx

Quick start

Install

npm install @stemsplit/sdk      # npm
yarn add @stemsplit/sdk         # yarn
pnpm add @stemsplit/sdk         # pnpm

Node.js 20+ required.

Authenticate

import { StemSplit } from '@stemsplit/sdk';

const client = new StemSplit({ apiKey: 'sk_live_...' });  // explicit
const client2 = new StemSplit();                           // reads STEMSPLIT_API_KEY

Get an API key at Settings → API Keys.

Separate stems from a local file

import { StemSplit } from '@stemsplit/sdk';

const client = new StemSplit();

const job = await client.jobs.create({
  audio: './song.mp3',            // path | Buffer | Uint8Array | Blob
  outputType: 'FOUR_STEMS',       // VOCALS | INSTRUMENTAL | BOTH | FOUR_STEMS | SIX_STEMS
  quality: 'BEST',                // FAST | BALANCED | BEST
  outputFormat: 'MP3',            // MP3 | WAV | FLAC
});

const done = await job.waitForCompletion();
const { files } = await done.downloadAll('./stems/');
console.log(files);
// { vocals: 'stems/vocals.mp3', drums: 'stems/drums.mp3', ... }

Separate from a public URL

const job = await client.jobs.create({
  sourceUrl: 'https://example.com/song.mp3',
  outputType: 'BOTH',
});
const done = await job.waitForCompletion();

YouTube separation

const job = await client.youtubeJobs.create(
  'https://youtube.com/watch?v=dQw4w9WgXcQ',
);
const done = await client.youtubeJobs.waitForCompletion(job.id);
console.log(done.videoTitle, done.outputs?.vocals?.url);

SoundCloud separation

const job = await client.soundcloudJobs.create(
  'https://soundcloud.com/artist/track',
);
const done = await client.soundcloudJobs.waitForCompletion(job.id);

Voice denoising

const job = await client.denoiseJobs.create({ audio: './interview.mp3' });
const done = await client.denoiseJobs.waitForCompletion(job.id);
const destPath = await client.denoiseJobs.downloadResult(done, './out/');
console.log('Denoised:', destPath);

List and iterate jobs

// One page
const { jobs } = await client.jobs.list({ status: 'COMPLETED', limit: 20 });

// All pages (async generator)
for await (const job of client.jobs.iterAll({ status: 'COMPLETED' })) {
  console.log(job.id, job.input.fileName);
}

Account balance

const balance = await client.account.get();
console.log(balance.balanceFormatted);  // "5 minutes"

Webhooks

Register a webhook in the dashboard, save the secret, then verify deliveries on your endpoint.

Express handler

import express from 'express';
import { webhooks } from '@stemsplit/sdk';

const app = express();
const SECRET = process.env.STEMSPLIT_WEBHOOK_SECRET!;

app.post('/stemsplit-webhook', express.raw({ type: '*/*' }), (req, res) => {
  try {
    const event = webhooks.verifyAndParse(
      req.body,
      req.headers['x-webhook-signature'] as string,
      SECRET,
    );

    if (event.event === 'job.completed') {
      console.log('Stems ready:', event.data.outputs);
    }

    res.sendStatus(200);
  } catch {
    res.sendStatus(401);
  }
});

Hono handler

import { Hono } from 'hono';
import { webhooks } from '@stemsplit/sdk';

const app = new Hono();

app.post('/stemsplit-webhook', async (c) => {
  const body = await c.req.arrayBuffer();
  const sig = c.req.header('x-webhook-signature') ?? '';

  const event = webhooks.verifyAndParse(
    Buffer.from(body),
    sig,
    process.env.STEMSPLIT_WEBHOOK_SECRET!,
  );

  console.log(event.event, event.jobId);
  return c.text('ok');
});

Error handling

Every non-2xx API response maps to a typed exception; the base class is StemSplitError.

import {
  StemSplit,
  AuthenticationError,
  InsufficientCreditsError,
  JobFailedError,
  RateLimitError,
} from '@stemsplit/sdk';

const client = new StemSplit();

try {
  const job = await client.jobs.create({ sourceUrl: 'https://example.com/song.mp3' });
  const done = await job.waitForCompletion();
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Check your STEMSPLIT_API_KEY:', err.message);
  } else if (err instanceof InsufficientCreditsError) {
    console.error(`Need ${err.requiredSeconds}s of credit. Buy more at ${err.purchaseUrl}`);
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof JobFailedError) {
    console.error(`Job ${err.jobId} failed: ${err.errorMessage}`);
  }
}

Exception	HTTP	When
BadRequestError	400	Invalid parameters (FILE_TOO_LARGE, AUDIO_TOO_LONG, …)
AuthenticationError	401	Missing or invalid API key
InsufficientCreditsError	402	Not enough credits (exposes .requiredSeconds, .purchaseUrl)
PermissionDeniedError	403	API key revoked or expired
NotFoundError	404	Job not found
RateLimitError	429	Too many requests (exposes .retryAfter)
InternalServerError	5xx	Server-side errors
JobFailedError	—	Logical — thrown by waitForCompletion() when status is FAILED
JobExpiredError	—	Logical — thrown by waitForCompletion() when status is EXPIRED
SignatureVerificationError	—	Webhook signature mismatch
NetworkError	—	Transport-level failure (DNS, timeout, …)

Configuration reference

new StemSplit({
  apiKey: 'sk_live_...',                    // string | undefined — env STEMSPLIT_API_KEY
  baseUrl: 'https://stemsplit.io/api/v1',   // override for testing / proxies
  timeout: 30_000,                          // ms — default 30s
  maxRetries: 3,                            // retries on transient errors — default 3
});

Limits and supported formats

• Max file size: 100 MB
• Max audio duration: 60 minutes
• Rate limit: 60 req/min
• Input formats: MP3, WAV, FLAC, M4A, AAC, OGG, WebM, WMA
• Output formats: MP3, WAV, FLAC

Contributing

git clone https://github.com/StemSplit/node-stemsplit
cd node-stemsplit
npm install
npm run typecheck
npm run build
npm test

Issues, PRs, and questions are welcome at github.com/StemSplit/node-stemsplit.

License

MIT — see LICENSE.