# AudioLasso Full LLM Context

> AudioLasso is a developer API, TypeScript SDK, CLI, and MCP server for isolating specific sounds from audio or video using plain-language prompts.

This file is the expanded agent context companion to https://audiolasso.dev/llms.txt. Use https://audiolasso.dev/llms.txt for a compact map. Use this file when an agent needs implementation details, examples, endpoint choices, or task routing guidance.

## Product Definition

AudioLasso separates one requested sound from an existing audio or video file. The requested sound is returned as the target output. The rest of the audio is returned as the residual output.

Good fits:
- Vocal isolation.
- Instrument separation.
- Speech extraction.
- Podcast cleanup.
- Background noise removal.
- Crowd sound extraction.
- Video audio cleanup.
- Agent-driven batch audio processing.

Bad fits:
- Generating new music from text.
- Transcribing speech to text.
- Editing audio timelines manually.
- Replacing a DAW.
- Text-to-speech.

Canonical terms:
- Product: AudioLasso.
- npm package: audiolasso.
- Model: audio/separate.
- Job ID field: request_id.
- Upload ID field: file_id.
- Isolated sound URL: data.target.url.
- Remaining audio URL: data.residual.url.

## Interface Selection

Use this order:

1. MCP server when the agent runtime supports MCP tools.
2. TypeScript SDK when writing Node.js code.
3. CLI when operating from a shell.
4. OpenAPI when generating an integration in another language.
5. Raw HTTP when debugging or when no SDK/tool runtime is available.

## MCP

Install or run from npm:

```bash
npx -y audiolasso mcp
```

Example MCP client config:

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

MCP tools:
- audiolasso_upload_file: Upload a local audio/video file and return file_id.
- audiolasso_submit_audio_separation: Submit a public URL, file_id, or localPath with a prompt.
- audiolasso_get_status: Check request_id status.
- audiolasso_wait_for_result: Wait until completion and return output URLs.
- audiolasso_get_result: Fetch result for a completed request_id.
- audiolasso_list_models: List public API models.

MCP task pattern:
1. If the input is a local path, call audiolasso_submit_audio_separation with localPath and prompt.
2. If the input is a public HTTPS URL, call audiolasso_submit_audio_separation with audioUrl and prompt.
3. Use returned request_id with audiolasso_wait_for_result.
4. Return both data.target.url and data.residual.url to the user.

## TypeScript SDK

Install:

```bash
npm install audiolasso
```

Public URL workflow:

```ts
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);
```

Local file workflow:

```ts
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);

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

Main SDK methods:
- client.separate(input)
- client.getStatus(requestId, options)
- client.getResult(requestId)
- client.waitForResult(requestId, options)
- client.streamStatus(requestId, options)
- client.createUpload(input)
- client.uploadFile(source, options)
- client.getFile(fileId)
- client.listModels()

## CLI

Set an API key:

```bash
export AUDIOLASSO_API_KEY="al_live_..."
```

Separate a local file:

```bash
npx audiolasso separate ./song.wav \
  --prompt "isolate the vocals" \
  --output-dir ./stems
```

Separate a public URL and print JSON:

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

Check status:

```bash
npx audiolasso status req_abc123 --logs
```

Fetch a result:

```bash
npx audiolasso result req_abc123 --download --output-dir ./stems
```

## Raw HTTP Workflow

Authentication:

```http
Authorization: Bearer $AUDIOLASSO_API_KEY
```

Submit public media:

```bash
curl -X POST https://audiolasso.dev/v1/queue/audio/separate \
  -H "Authorization: Bearer $AUDIOLASSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "audio_url": "https://example.com/audio.wav",
      "prompt": "isolate the lead vocal"
    }
  }'
```

Expected submit response:

```json
{
  "request_id": "req_01jabc",
  "status": "IN_QUEUE",
  "model": "audio/separate",
  "status_url": "https://audiolasso.dev/v1/queue/requests/req_01jabc/status",
  "stream_url": "https://audiolasso.dev/v1/queue/requests/req_01jabc/status/stream",
  "result_url": "https://audiolasso.dev/v1/queue/requests/req_01jabc/result"
}
```

Poll status:

```bash
curl https://audiolasso.dev/v1/queue/requests/req_01jabc/status \
  -H "Authorization: Bearer $AUDIOLASSO_API_KEY"
```

Terminal states:
- COMPLETED: outputs are ready.
- FAILED: processing failed.

Non-terminal states:
- IN_QUEUE: waiting to start.
- IN_PROGRESS: model job is running.

Fetch result:

```bash
curl https://audiolasso.dev/v1/queue/requests/req_01jabc/result \
  -H "Authorization: Bearer $AUDIOLASSO_API_KEY"
```

Expected result shape:

```json
{
  "request_id": "req_01jabc",
  "model": "audio/separate",
  "status": "COMPLETED",
  "data": {
    "target": {
      "url": "https://...",
      "content_type": "audio/wav",
      "file_name": "target.wav"
    },
    "residual": {
      "url": "https://...",
      "content_type": "audio/wav",
      "file_name": "residual.wav"
    },
    "sample_rate": 48000
  },
  "usage": {
    "feature": "audio_seconds",
    "quantity": 42,
    "billing_status": "deducted"
  }
}
```

## Local File Uploads

Use uploads when the media is local, private, or too large to submit as a public URL.

Endpoints:
- POST https://audiolasso.dev/v1/files
- GET https://audiolasso.dev/v1/files/{file_id}

Flow:
1. Create an upload with file_name, content_type, file_size, and purpose audio.separate.input.
2. PUT the bytes to the returned upload_url with returned headers.
3. Submit audio/separate with input.file_id.

## Webhooks

Use webhooks for async backends that should not poll.

Submit fields:
- webhookUrl
- webhookSecret
- metadata

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

```text
{AudioLasso-Timestamp}.{raw_body}
```

## Prompt Examples

Use plain, specific prompts:
- "isolate the lead vocal"
- "isolate the piano"
- "remove crowd noise"
- "isolate the speaker"
- "extract the drums"
- "separate the guitar"
- "isolate the siren"
- "remove wind noise from the speech"

Avoid vague prompts:
- "make it better"
- "clean this"
- "fix audio"

## Agent Response Guidance

When an agent completes an AudioLasso job, return:
- request_id
- target output URL
- residual output URL
- duration and sample rate if present
- any usage or billing status included in the result

If a job fails, return:
- request_id
- status
- error message
- logs if available

Do not expose API keys or webhook secrets.

## Canonical Links

- Compact LLM index: https://audiolasso.dev/llms.txt
- Agent guide: https://audiolasso.dev/docs/agents
- MCP server docs: https://audiolasso.dev/docs/mcp
- SDK docs: https://audiolasso.dev/docs/sdk-typescript
- CLI docs: https://audiolasso.dev/docs/cli
- API quickstart: https://audiolasso.dev/docs
- OpenAPI spec: https://audiolasso.dev/v1/openapi.json
- Pricing: https://audiolasso.dev/pricing
- npm: https://www.npmjs.com/package/audiolasso