Разделение стемов в Node.js.
Типизированный клиент Node и TypeScript для AI Stem Splitter. Установите из npm или JSR, запустите в Node, Bun или Deno и выпустите рабочую функцию разделения стемов буквально в 12 строках кода — отправьте трек, опрашивайте до готовности и сохраните 4 стема на диск ещё до следующего стендапа.
Установка
Аутентификация
Создайте ключ в настройках разработчика, добавьте его в окружение как AISTEMSPLITTER_API_KEY и передайте в конструктор клиента. SDK никогда не логирует ключ, а на странице во всплывающих подсказках отображается только безопасный публичный префикс ast_live_.
import { AiStemSplitter } from "@aistemsplitter/sdk";
const client = new AiStemSplitter({
apiKey: process.env.AISTEMSPLITTER_API_KEY!,
});Hello world
Двенадцать строк, от начала до конца. Отправьте трек, дождитесь завершения работы модели htdemucs_ft и сохраните четыре стема — vocals, drums, bass, other — на диск. Вставьте это в один файл .mjs, задайте свой ключ и запустите перед демо на стендапе.
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));
}Методы
Шесть типизированных методов покрывают весь жизненный цикл задачи. Каждый из них — реальная сигнатура TypeScript в опубликованном пакете: автодополнение в редакторе, никаких оболочек над fetch и никаких схем для запоминания.
Отправить новую задачу разделения; возвращает id задачи и статус queued.
Получить текущий статус задачи разделения.
Опрашивать до успеха, ошибки или истечения тайм-аута.
Постраничный список недавних задач разделения для API-ключа.
Получить предварительно подписанный PUT URL для прямой загрузки из браузера или сервера.
Проверить подпись HMAC-SHA256 во входящем payload вебхука.
Вебхуки
Опрос годится для демо. Вебхуки — для продакшна. Передайте подписанный callback URL в createSplit, затем проверьте подпись HMAC-SHA256 одним вызовом SDK в существующем обработчике Express или Hono.
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.
Работает ли @aistemsplitter/sdk в Bun и Deno без полифилов?
Да. Пакет публикуется одновременно в npm и JSR, поэтому Bun устанавливает его через `bun add jsr:@aistemsplitter/sdk`, а Deno — через `deno add jsr:@aistemsplitter/sdk`. Не нужны полифилы @types/node, не требуется shim для Buffer и нет импортов node:fs в ядре клиента — типизированный API использует Web Fetch и Web Streams, которые нативно поддерживаются в Node 18+, Bun и Deno.
Как проверять подписи вебхуков в Express, Hono или Next.js?
Вызовите ast.verifyWebhook({ headers, body }) — метод вычисляет HMAC-SHA256 по сырому телу, сравнивает за постоянное время с заголовком aistemsplitter-signature и выбрасывает исключение при подделке. В разделе «Вебхуки» выше приведены рабочие обработчики для Express и Hono; для Next.js App Router используйте паттерн Hono в обработчике route.ts с `await request.text()`, чтобы прочитать сырое тело перед проверкой.
TypeScript-API действительно типизирован или повсюду `any`?
Действительно типизирован. У каждого метода AistemsplitterClient есть типизированный вход и Promise на выходе: createSplit(input: CreateSplitInput) → Promise<Split>, getSplit(id: string) → Promise<Split>, waitForSplit, listSplits, presignUpload, verifyWebhook. Типы Split, Stem и WebhookEvent экспортируются из корня пакета, поэтому вы можете импортировать их в свои обработчики и слой хранения без повторного описания структуры.
Как организовать обработку ошибок и повторные попытки в SDK?
Все методы выбрасывают типизированные ошибки: AistemsplitterApiError (4xx/5xx с code + message + requestId), AistemsplitterRateLimitError (429 с retryAfter в секундах), AistemsplitterNetworkError (уровень транспорта). waitForSplit автоматически повторяет опросы с экспоненциальной задержкой до тайм-аута SDK (по умолчанию 5 мин) — оберните createSplit и presignUpload в собственный helper повторных попыток, если нужна семантика at-least-once для отправки.
Можно ли запускать это в браузере?
Нет — SDK предназначен для серверной стороны. Использование в браузере раскроет ваш API-ключ (любой код, попадающий на машину пользователя, может его прочитать) и упрётся в CORS на эндпоинтах загрузки. Сформируйте короткоживущий подписанный URL на сервере через presignUpload и передайте в браузер только его; сами вызовы createSplit и waitForSplit делайте из серверного маршрута, рабочего процесса n8n или фонового воркера.
Дальнейшие шаги
Выпустите 4 стема ещё до стендапа.
Бесплатная регистрация, без банковской карты. Пакеты кредитов без срока действия — $0.08–$0.14 за минуту в зависимости от объёма.