AudioLasso

TypeScript SDK, CLI, and MCP server for the AudioLasso audio separation API.

AudioLasso separates specific sounds from audio or video with plain-language prompts. Use it from backend apps, local scripts, CI jobs, and coding agents.

The API follows a queue model: submit work, poll status, fetch the result. The SDK's waitForResult helper polls for you. Streaming status and webhooks are optional surfaces for clients that need them.

Install

npm install audiolasso

To test the packaged artifact from this repository before a release:

pnpm package:pack
npm install ./packages/audiolasso/audiolasso-0.2.0.tgz

The package requires Node.js 20 or newer.

Quickstart

Create an API key in the AudioLasso dashboard and set:

export AUDIOLASSO_API_KEY="al_live_..."

import { createAudioLasso } from "audiolasso";

const client = createAudioLasso({
  apiKey: process.env.AUDIOLASSO_API_KEY,
});

const job = await client.separate({
  audioUrl: "https://example.com/audio.wav",
  prompt: "isolate the lead vocal",
  idempotencyKey: "workflow-job-123",
});

const result = await client.waitForResult(job.request_id, { logs: true });

console.log(result.data.target.url);
console.log(result.data.residual.url);

The SDK generates an idempotency key when one is not supplied. Use a stable key when a logical workflow may be restarted from another process.

Configure transport reliability when needed:

const client = createAudioLasso({
  requestTimeoutMs: 30_000,
  maxRetries: 2,
});

Upload a local file

import { createAudioLasso } from "audiolasso";

const client = createAudioLasso();

const upload = await client.uploadFile("./song.wav");

const job = await client.separate({
  fileId: upload.file_id,
  prompt: "isolate the vocals",
});

const result = await client.waitForResult(job.request_id, { logs: true });

console.log(result.data.target.url);

SDK methods

The simplest methods are:

• client.separate(...)
• client.getStatus(...)
• client.getResult(...)
• client.cancel(...)
• client.waitForResult(...)
• client.createUpload(...)
• client.uploadFile(...)
• client.getFile(...)
• client.listModels()

Grouped methods are also available if you prefer them:

• client.audio.separate(...)
• client.queue.status(...)
• client.queue.result(...)
• client.queue.cancel(...)
• client.queue.waitForResult(...)
• client.queue.streamStatus(...)
• client.files.createUpload(...)
• client.files.upload(...)
• client.files.get(...)
• client.models.list()

Error handling

API failures throw AudioLassoApiError.

import { AudioLassoApiError, createAudioLasso } from "audiolasso";

try {
  await createAudioLasso().separate({
    audioUrl: "https://example.com/audio.wav",
    prompt: "isolate the lead vocal",
  });
} catch (error) {
  if (error instanceof AudioLassoApiError) {
    console.error(error.status, error.code, error.message);
  }
}

CLI

npx audiolasso --help

Log in from the browser:

npx audiolasso login

Separate a local file and download outputs:

audiolasso separate ./song.wav \
  --prompt "isolate the vocals" \
  --idempotency-key workflow-job-123 \
  --output-dir ./stems

Separate a public URL and print JSON:

audiolasso separate https://example.com/audio.wav \
  --prompt "remove crowd noise" \
  --json

Check status:

pnpm audiolasso status req_abc123 --logs

Fetch a completed result:

audiolasso result req_abc123 --download --output-dir ./stems

Cancel queued or running work:

audiolasso cancel req_abc123 --json

MCP server

Use the stdio MCP server when you want an agent to call AudioLasso tools directly.

{
  "mcpServers": {
    "audiolasso": {
      "command": "npx",
      "args": ["-y", "audiolasso", "mcp"],
      "env": {
        "AUDIOLASSO_API_KEY": "al_live_..."
      }
    }
  }
}

The MCP server exposes tools for uploading local files, submitting and canceling separation jobs, checking status, waiting for results, fetching completed outputs, and listing models. Tool successes and errors include machine-readable structuredContent.

Webhooks

await client.separate({
  audioUrl: "https://example.com/audio.wav",
  prompt: "separate the piano",
  webhookUrl: "https://example.com/webhooks/audiolasso",
  webhookSecret: process.env.AUDIOLASSO_WEBHOOK_SECRET,
  metadata: {
    userId: "user_123",
  },
});

Webhook events are signed with AudioLasso-Signature as HMAC SHA-256 over:

{AudioLasso-Timestamp}.{raw_body}

Use the exported verifyWebhookSignature(...) helper with the raw body to verify the HMAC and reject stale delivery attempts.

Links

• API docs: https://audiolasso.dev/docs
• OpenAPI spec: https://audiolasso.dev/v1/openapi.json