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.

Install

npm install audiolasso

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

pnpm package:pack
npm install ./packages/audiolasso/audiolasso-0.1.1.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",
});

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

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

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.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.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" \
  --stream \
  --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

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 separation jobs, checking status, waiting for results, fetching completed outputs, and listing models.

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}

Links

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