Stem Splitting in Node.js.
Ein typisierter Node- und TypeScript-Client für AI Stem Splitter. Installieren Sie über npm oder JSR, laufen Sie auf Node, Bun oder Deno, und shippen Sie ein funktionierendes Stem-Separation-Feature in einem buchstäblichen 12-Zeilen-Skript — Track einreichen, bis zur Bereitschaft pollen und die 4 Stems vor der nächsten Standup-Demo auf die Festplatte schreiben.
Installieren
Authentifizieren
Generieren Sie einen Key in Ihren Entwickler-Einstellungen, legen Sie ihn in Ihrer Umgebung als AISTEMSPLITTER_API_KEY ab und übergeben Sie ihn an den Client-Konstruktor. Das SDK loggt den Key nie, und die Seite rendert in Tooltips nie mehr als das öffentlich sichere ast_live_-Präfix.
import { AiStemSplitter } from "@aistemsplitter/sdk";
const client = new AiStemSplitter({
apiKey: process.env.AISTEMSPLITTER_API_KEY!,
});Hello World
Zwölf Zeilen, Ende-zu-Ende. Reichen Sie einen Track ein, warten Sie, bis das htdemucs_ft-Modell fertig ist, und schreiben Sie die vier Stems — vocals, drums, bass, other — auf die Festplatte. Fügen Sie das in eine einzelne .mjs-Datei ein, setzen Sie Ihren Key und führen Sie es vor der Standup-Demo aus.
import { AiStemSplitter } from "@aistemsplitter/sdk";
import { writeFile } from "node:fs/promises";
const client = new AiStemSplitter({
apiKey: process.env.AISTEMSPLITTER_API_KEY!,
});
// 1. Submit a split job
const job = await client.createSplit({
input: { type: "direct_url", url: "https://example.com/song.mp3" },
stemModel: "htdemucs_ft",
});
// 2. Wait until completion (polls under the hood)
const result = await client.waitForSplit(job.id);
// 3. Download all six stems
for (const [name, url] of Object.entries(result.stems)) {
const audio = await fetch(url).then((r) => r.arrayBuffer());
await writeFile(`./${name}.wav`, Buffer.from(audio));
}Methoden
Sechs typisierte Methoden decken den vollständigen Job-Lifecycle ab. Jede ist eine echte TypeScript-Signatur im veröffentlichten Paket — Autovervollständigung in Ihrem Editor, keine fetch-Wrapper zu schreiben, kein Schema auswendig zu lernen.
Reicht einen neuen Split-Job ein; gibt eine Job-ID und queued-Status zurück.
Ruft den aktuellen Status eines Split-Jobs ab.
Pollt, bis der Job erfolgreich ist, fehlschlägt oder das Timeout abläuft.
Paginierte Liste der letzten Split-Jobs für den API-Key.
Erstellt eine vorab signierte PUT-URL für direkte Browser-/Server-Uploads.
Verifiziert die HMAC-SHA256-Signatur eines eingehenden Webhook-Payloads.
Webhooks
Polling bringt Sie zur Demo. Webhooks bringen Sie in die Produktion. Legen Sie eine signierte Callback-URL in createSplit ab und verifizieren Sie anschließend die HMAC-SHA256-Signatur mit einem SDK-Aufruf in Ihrem bestehenden Express- oder Hono-Handler.
import { AiStemSplitter } from "@aistemsplitter/sdk";
import { Hono } from "hono";
const app = new Hono();
const client = new AiStemSplitter({
apiKey: process.env.AISTEMSPLITTER_API_KEY!,
});
app.post("/webhooks/aistemsplitter", async (c) => {
const raw = await c.req.text();
const event = client.verifyWebhook(c.req.header(), raw); // throws if invalid
switch (event.type) {
case "split.succeeded":
// event.data.stems → six URLs
break;
case "split.failed":
// event.data.error → { code, message }
break;
}
return c.text("ok");
});FAQ
Does @aistemsplitter/sdk work in Bun and Deno without polyfills?
Yes. The package is dual-published to npm and JSR, so Bun installs via `bun add jsr:@aistemsplitter/sdk` and Deno via `deno add jsr:@aistemsplitter/sdk`. There are no @types/node polyfills, no Buffer shimming required, and no node:fs imports in the client core — the typed surface uses the Web Fetch + Web Streams APIs, which Node 18+, Bun, and Deno all implement natively.
How do I verify webhook signatures in Express, Hono, or Next.js?
Call ast.verifyWebhook({ headers, body }) — it computes the HMAC-SHA256 over the raw body, constant-time-compares against the aistemsplitter-signature header, and throws on tamper. The Webhooks section above shows runnable Express and Hono handlers; for Next.js App Router, use the Hono pattern in a route.ts handler with `await request.text()` to read the raw body before verification.
Is the TypeScript surface real, or `any` everywhere?
Real. Every method on AistemsplitterClient has a typed input + Promise return: createSplit(input: CreateSplitInput) → Promise<Split>, getSplit(id: string) → Promise<Split>, waitForSplit, listSplits, presignUpload, verifyWebhook. The Split + Stem + WebhookEvent types are exported from the package root, so you can import them into your own handlers and storage layer without re-deriving the shape.
How do I handle errors and retries from the SDK?
All methods throw typed errors: AistemsplitterApiError (4xx/5xx with code + message + requestId), AistemsplitterRateLimitError (429 with retryAfter seconds), AistemsplitterNetworkError (transport-level). waitForSplit retries polls automatically with exponential backoff until the SDK timeout (default 5 min) — wrap createSplit / presignUpload in your own retry helper if you need at-least-once submission semantics.
Can I run this in the browser?
No — the SDK is a server-side client. Browser use would expose your API key (any code that reaches the user's machine can read it) and run into CORS on the upload endpoints. Mint a short-lived signed URL on your server with presignUpload and hand only that URL to the browser; do the actual createSplit + waitForSplit calls from a server route, n8n workflow, or background worker.
Funktioniert @aistemsplitter/sdk in Bun und Deno ohne Polyfills?
Ja. Das Paket wird parallel auf npm und JSR veröffentlicht, sodass Bun über `bun add jsr:@aistemsplitter/sdk` installiert und Deno über `deno add jsr:@aistemsplitter/sdk`. Es gibt keine @types/node-Polyfills, kein erforderliches Buffer-Shimming und keine node:fs-Imports im Client-Core — die typisierte Oberfläche nutzt die Web Fetch + Web Streams APIs, die Node 18+, Bun und Deno nativ implementieren.
Wie verifiziere ich Webhook-Signaturen in Express, Hono oder Next.js?
Rufen Sie ast.verifyWebhook({ headers, body }) auf — es berechnet HMAC-SHA256 über den Raw Body, vergleicht in konstanter Zeit gegen den aistemsplitter-signature-Header und wirft bei Manipulation. Der Webhooks-Abschnitt oben zeigt ausführbare Express- und Hono-Handler; für Next.js App Router nutzen Sie das Hono-Muster in einem route.ts-Handler mit `await request.text()`, um den Raw Body vor der Verifikation zu lesen.
Ist die TypeScript-Oberfläche echt, oder überall `any`?
Echt. Jede Methode auf AistemsplitterClient hat typisierte Eingaben und Promise-Rückgaben: createSplit(input: CreateSplitInput) → Promise<Split>, getSplit(id: string) → Promise<Split>, waitForSplit, listSplits, presignUpload, verifyWebhook. Die Typen Split + Stem + WebhookEvent werden aus dem Package-Root exportiert, sodass Sie sie in Ihre eigenen Handler und Storage-Layer importieren können, ohne die Struktur neu herzuleiten.
Wie gehe ich mit Fehlern und Retries aus dem SDK um?
Alle Methoden werfen typisierte Fehler: AistemsplitterApiError (4xx/5xx mit code + message + requestId), AistemsplitterRateLimitError (429 mit retryAfter-Sekunden), AistemsplitterNetworkError (Transportebene). waitForSplit wiederholt Polls automatisch mit exponentiellem Backoff bis zum SDK-Timeout (Standard 5 Min.) — wrappen Sie createSplit / presignUpload in Ihren eigenen Retry-Helper, wenn Sie At-least-once-Submission-Semantik benötigen.
Kann ich das im Browser ausführen?
Nein — das SDK ist ein serverseitiger Client. Browser-Nutzung würde Ihren API-Key offenlegen (jeder Code, der die Maschine des Nutzers erreicht, kann ihn lesen) und auf den Upload-Endpunkten in CORS laufen. Erstellen Sie auf Ihrem Server mit presignUpload eine kurzlebige signierte URL und geben Sie nur diese URL an den Browser; führen Sie die eigentlichen createSplit- + waitForSplit-Aufrufe aus einer Server-Route, einem n8n-Workflow oder einem Background Worker aus.
Nächste Schritte
Shippen Sie 4 Stems vor dem Standup.
Kostenlose Anmeldung, keine Kreditkarte. Credit-Pakete, die nie verfallen — $0.08–$0.14 pro Minute je nach Volumen.