Node.jsでステム分離。
AI Stem Splitter向けの型付きNode / TypeScriptクライアントです。npmまたはJSRからインストールし、Node、Bun、Denoで実行できます。トラックを送信し、完了までポーリングし、次のスタンドアップデモ前に4つのステムをディスクへ書き出す、文字どおり12行のスクリプトで動くステム分離機能を出荷できます。
インストール
認証
開発者設定でキーを生成し、環境変数AISTEMSPLITTER_API_KEYに入れて、クライアントコンストラクタへ渡します。SDKはキーをログに出さず、このページもツールチップ内でpublic-safeなast_live_プレフィックス以上を表示しません。
import { AiStemSplitter } from "@aistemsplitter/sdk";
const client = new AiStemSplitter({
apiKey: process.env.AISTEMSPLITTER_API_KEY!,
});Hello world
エンドツーエンドで12行です。トラックを送信し、htdemucs_ftモデルの完了を待ち、4つのステム（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));
}メソッド
6つの型付きメソッドでジョブライフサイクル全体をカバーします。公開パッケージ上の実際のTypeScriptシグネチャなので、エディタで補完でき、fetchラッパーを書く必要もスキーマを覚える必要もありません。
新しい分離ジョブを送信し、job idとqueuedステータスを返します。
分離ジョブの現在のステータスを取得します。
ジョブが成功、失敗、またはタイムアウトするまでポーリングします。
APIキーに紐づく最近の分離ジョブをページネーション付きで一覧表示します。
ブラウザ/サーバーから直接アップロードするためのpre-signed PUT URLを取得します。
受信webhook payloadのHMAC-SHA256署名を検証します。
Webhooks
ポーリングはデモまで連れて行ってくれます。Webhooksは本番まで連れて行ってくれます。署名付きcallback URLをcreateSplitに渡し、既存のExpressまたはHonoハンドラーで、SDKの1回の呼び出しによりHMAC-SHA256署名を検証します。
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でpolyfillなしに動きますか？
はい。パッケージはnpmとJSRの両方に公開されているため、Bunは`bun add jsr:@aistemsplitter/sdk`、Denoは`deno add jsr:@aistemsplitter/sdk`でインストールできます。@types/nodeのpolyfill、Bufferのshim、クライアントコア内のnode:fs importは不要です。型付きsurfaceはWeb Fetch + Web Streams APIsを使っており、Node 18+、Bun、Denoはいずれもネイティブに実装しています。
Express、Hono、Next.jsでwebhook署名を検証するには？
ast.verifyWebhook({ headers, body })を呼び出してください。raw bodyに対してHMAC-SHA256を計算し、aistemsplitter-signatureヘッダーとconstant-timeで比較し、改ざんがあればthrowします。上のWebhooksセクションには実行可能なExpressとHonoハンドラーがあります。Next.js App Routerでは、route.tsハンドラー内でHonoパターンを使い、検証前に`await request.text()`でraw bodyを読み取ります。
TypeScript surfaceは本物ですか？それとも`any`だらけですか？
本物です。AistemsplitterClient上のすべてのメソッドは、型付きinput + Promise returnを持ちます。createSplit(input: CreateSplitInput) → Promise<Split>、getSplit(id: string) → Promise<Split>、waitForSplit、listSplits、presignUpload、verifyWebhookです。Split + Stem + WebhookEvent型はパッケージルートからexportされるため、形を再定義せずに自分のハンドラーやストレージ層へimportできます。
SDKからのエラーやリトライはどう扱いますか？
すべてのメソッドは型付きエラーをthrowします。AistemsplitterApiError（4xx/5xx、code + message + requestId付き）、AistemsplitterRateLimitError（429、retryAfter秒付き）、AistemsplitterNetworkError（transport-level）です。waitForSplitはSDKのtimeout（デフォルト5分）まで指数バックオフで自動的にポーリングをリトライします。少なくとも1回の送信セマンティクスが必要な場合は、createSplit / presignUploadを独自のretry helperでラップしてください。
ブラウザで実行できますか？
いいえ。SDKはサーバーサイドクライアントです。ブラウザ利用ではAPIキーが露出し（ユーザーのマシンに届くコードは読めます）、アップロードエンドポイントでCORSにも当たります。サーバー側でpresignUploadにより短命の署名付きURLを発行し、ブラウザにはそのURLだけを渡してください。実際のcreateSplit + waitForSplit呼び出しは、server route、n8n workflow、background workerから実行します。