> ## Documentation Index
> Fetch the complete documentation index at: https://docs.audiopod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> Official Node.js SDK for AudioPod AI - Professional Audio Processing powered by AI

[![npm version](https://badge.fury.io/js/audiopod.svg)](https://www.npmjs.com/package/audiopod)
[![Node 16+](https://img.shields.io/badge/node-16+-green.svg)](https://nodejs.org/)

## Installation

```bash theme={null}
npm install audiopod
# or
yarn add audiopod
```

## Quick Start

```typescript theme={null}
import AudioPod from 'audiopod';

// Initialize client
const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Separate audio into 6 stems
const result = await client.stems.separate({
  url: 'https://youtube.com/watch?v=VIDEO_ID',
  mode: 'six'
});

// Download stems
for (const [stem, url] of Object.entries(result.download_urls)) {
  console.log(`${stem}: ${url}`);
}
```

## Authentication

```typescript theme={null}
import AudioPod from 'audiopod';

// Method 1: Pass API key directly
const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Method 2: Use environment variable (recommended)
// Set AUDIOPOD_API_KEY environment variable, then:
const client = new AudioPod();
```

***

## Stem Separation

Extract individual audio components from mixed recordings.

### Available Modes

| Mode        | Stems | Output                                                          |
| ----------- | ----- | --------------------------------------------------------------- |
| `single`    | 1     | Specified stem only (vocals, drums, bass, guitar, piano, other) |
| `two`       | 2     | Vocals + Instrumental                                           |
| `four`      | 4     | Vocals, Drums, Bass, Other                                      |
| `six`       | 6     | Vocals, Drums, Bass, Guitar, Piano, Other                       |
| `producer`  | 8     | + Kick, Snare, Hihat                                            |
| `studio`    | 12    | Full production toolkit                                         |
| `mastering` | 16    | Maximum detail                                                  |

### Examples

```typescript theme={null}
import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Six-stem separation from YouTube
const result = await client.stems.separate({
  url: 'https://youtube.com/watch?v=VIDEO_ID',
  mode: 'six'
});
console.log(result.download_urls);

// From local file
const result = await client.stems.separate({
  file: './song.mp3',
  mode: 'four'
});

// Extract only vocals
const result = await client.stems.separate({
  url: 'https://youtube.com/watch?v=VIDEO_ID',
  mode: 'single',
  stem: 'vocals'
});

// Async job handling (for more control)
const job = await client.stems.extract({
  url: 'https://youtube.com/watch?v=VIDEO_ID',
  mode: 'six'
});
console.log(`Job ID: ${job.id}`);

// Wait for completion
const result = await client.stems.waitForCompletion(job.id);

// Get available modes
const modes = await client.stems.modes();
modes.modes.forEach(m => {
  console.log(`${m.mode}: ${m.description}`);
});
```

***

## Transcription

Convert audio to text with speaker diarization.

```typescript theme={null}
import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// From URL
const job = await client.transcription.create({ url: 'https://...' });
const result = await client.transcription.waitForCompletion(job.id);
console.log(result.transcript);

// From file
const job = await client.transcription.create({ file: './audio.mp3' });
const result = await client.transcription.waitForCompletion(job.id);
```

***

## Voice Cloning & TTS

Create custom voices and generate speech.

```typescript theme={null}
import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Clone a voice from audio sample
const voice = await client.voice.clone({
  file: './sample.wav',
  name: 'My Voice'
});
console.log(`Voice ID: ${voice.id}`);

// Generate speech with cloned voice
const audio = await client.voice.generate({
  voiceId: voice.id,
  text: 'Hello, this is my cloned voice speaking!'
});
```

***

## Music Generation (AudioMusic V2)

Generate AI music with AudioMusic V2 — text-to-music, covers, style transfer, audio analysis, and more.

```typescript theme={null}
import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Simple mode — just describe what you want
const job = await client.music.simple({
  query: 'a soft Bengali love song for a quiet evening',
});
const song = await client.music.waitForCompletion(job.id);
console.log(`Music URL: ${song.output_url}`);

// Full control with text2music
const advanced = await client.music.create({
  prompt: 'upbeat pop, female vocals, catchy melody',
  task: 'text2music',
  lyrics: '[verse]\nSun is shining bright\n[chorus]\nDance the night away',
  duration: 120,
  inferenceSteps: 64,
  guidanceScale: 7.0,
  format: 'flac',
});

// Instrumental
const instrumental = await client.music.instrumental(
  'chill jazz piano with saxophone', 90
);

// Cover / style transfer
const cover = await client.music.cover({
  srcAudioUrl: 'https://example.com/song.mp3',
  caption: 'jazz piano version with upright bass',
  audioCoverStrength: 0.7,
});

// Analyze existing audio
const analysis = await client.music.analyze({
  audioUrl: 'https://example.com/song.mp3',
});
console.log(`BPM: ${analysis.bpm}, Key: ${analysis.keyscale}`);

// Extract stems
const vocals = await client.music.extractStem({
  srcAudioUrl: 'https://example.com/song.mp3',
  trackName: 'vocals',
});
const completed = await client.music.waitForCompletion(vocals.id);
console.log(`Vocals URL: ${completed.output_url}`);

// Reference audio for style guidance
const ref = await client.music.reference({
  referenceAudioUrl: 'https://example.com/reference.mp3',
  caption: 'upbeat pop with similar warmth',
  lyrics: '[verse]\nHello world',
});
```

***

## Audiobook

Turn a manuscript into a finished, ACX-compliant audiobook. Use `produce()` for the whole pipeline in one call, or drive each step. See the [Audiobook API reference](/api-reference/audiobook) for the full surface.

```typescript theme={null}
// One call: manuscript in, ACX package out
const result = await client.audiobook.produce({
  title: 'The Lighthouse Keeper',
  author: 'A. P. Tester',
  file: 'book.epub',          // PDF / EPUB / DOCX / TXT  (or text: '...')
  voiceId: 387,
});
console.log(result.download_url);              // presigned ACX package ZIP
console.log(result.compliance_check.is_compliant);

// Or drive each step
const project = await client.audiobook.createProject({ title: 'My Book', author: 'Me' });
const up = await client.audiobook.uploadManuscript(project.id, 'book.epub');
await client.audiobook.parseManuscript(project.id, up.file_key, 'book.epub');

const voices = await client.audiobook.listVoices();      // available / recommended / custom
const estimate = await client.audiobook.costEstimate(project.id);

await client.audiobook.narrate(project.id, { voiceId: 387 });   // waits for all chapters
const exp = await client.audiobook.exportAndWait(project.id);   // waits; runs ACX compliance check
const manifest = await client.audiobook.download(project.id, exp.job_id);
console.log(manifest.download_url);
```

Generate an original book from a prompt instead of uploading:

```typescript theme={null}
const project = await client.audiobook.createProject({ title: 'Bedtime Tales' });
await client.audiobook.generateBook(project.id, {
  prompt: 'Three calm bedtime stories about the sea', chapterCount: 3, wordsPerChapter: 500,
});
await client.audiobook.narrate(project.id, { voiceId: 387 });
```

***

## Noise Reduction

Clean up audio by removing background noise.

```typescript theme={null}
import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Denoise audio file
const clean = await client.denoiser.denoise({ file: './noisy.wav' });
console.log(`Clean audio: ${clean.outputUrl}`);
```

***

## Speaker Separation

Identify and separate multiple speakers.

```typescript theme={null}
import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Diarize speakers
const speakers = await client.speaker.diarize({ url: 'https://...' });
console.log(`Found ${speakers.segments.length} speaker segments`);
```

***

## API Wallet

Check balance and manage billing.

```typescript theme={null}
import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Check balance
const balance = await client.wallet.balance();
console.log(`Balance: ${balance.balance_usd}`);

// Estimate cost before processing
const estimate = await client.wallet.estimate('stem_extraction', 180);
console.log(`Estimated cost: ${estimate.cost_usd}`);

// Get usage history
const usage = await client.wallet.usage();
usage.logs.forEach(log => {
  console.log(`${log.service_type}: ${log.amount_usd}`);
});
```

***

## Error Handling

```typescript theme={null}
import AudioPod, { AuthenticationError, InsufficientBalanceError } from 'audiopod';

try {
  const client = new AudioPod({ apiKey: 'ap_...' });
  const result = await client.stems.separate({ url: '...', mode: 'six' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof InsufficientBalanceError) {
    console.log(`Need more credits. Required: ${error.requiredCents} cents`);
  } else {
    console.log(`Error: ${error.message}`);
  }
}
```

***

## TypeScript Support

Full TypeScript support with exported types:

```typescript theme={null}
import AudioPod, { StemExtractionJob, StemMode, WalletBalance } from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

// Fully typed responses
const job: StemExtractionJob = await client.stems.extract({
  url: 'https://...',
  mode: 'six' as StemMode
});

const balance: WalletBalance = await client.wallet.balance();
```

***

## Environment Variables

```bash theme={null}
export AUDIOPOD_API_KEY="ap_your_api_key"
```

```typescript theme={null}
// Client reads from env automatically
import AudioPod from 'audiopod';
const client = new AudioPod();
```

***

## Resources

<Columns cols={2}>
  <Card title="npm Package" icon="npm" href="https://www.npmjs.com/package/audiopod">
    View on npm
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/audiopod-ai/audiopod-node">
    Source code
  </Card>

  <Card title="Get API Key" icon="key" href="https://www.audiopod.ai/dashboard/account/api-keys">
    Generate your API key
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/stem-splitter">
    Raw API documentation
  </Card>
</Columns>