JavaScript SDK

The official Cleanvoice JavaScript SDK works in Node.js and is fully typed with TypeScript. It handles authentication, polling, and provides a clean async/await interface.

GitHub
npm

Installation

npm install @cleanvoice/cleanvoice-sdk

pnpm add @cleanvoice/cleanvoice-sdk

yarn add @cleanvoice/cleanvoice-sdk

bun add @cleanvoice/cleanvoice-sdk

Initialization

import Cleanvoice from '@cleanvoice/cleanvoice-sdk';

const client = new Cleanvoice({
  apiKey: process.env.CLEANVOICE_API_KEY,
});

`client.process()`

Submit a file and wait for the result. This is the recommended method for most use cases.

const result = await client.process(fileInput, config);

Parameters

Parameter	Type	Description
`fileInput`	`string`	URL to the audio or video file
`config`	`ProcessingConfig`	Processing options (see below)

`ProcessingConfig`

interface ProcessingConfig {
  fillers?: boolean;        // Remove filler words
  longSilences?: boolean;   // Trim long silences
  mouthSounds?: boolean;    // Remove mouth noises
  breath?: boolean;         // Remove audible breathing
  stutters?: boolean;       // Remove stutters
  removeNoise?: boolean;    // Reduce background noise
  studioSound?: boolean;    // Apply studio sound enhancement
  normalize?: boolean;      // Normalize loudness
  targetLufs?: number;      // Target LUFS level (e.g. -16)
  transcription?: boolean;  // Return transcript
  summarize?: boolean;      // Generate summary and chapters
  socialContent?: boolean;  // Generate social media copy
  exportFormat?: 'mp3' | 'wav' | 'flac' | 'm4a';
}

Return value

interface ProcessResult {
  editId: string;
  status: 'SUCCESS';
  url: string;          // Download URL for cleaned audio
  transcript?: string;  // If transcription was enabled
  summary?: {
    chapters: Chapter[];
    keyLearnings: string[];
    socialContent?: string;
  };
}

Example

import Cleanvoice from '@cleanvoice/cleanvoice-sdk';

const client = new Cleanvoice({ apiKey: process.env.CLEANVOICE_API_KEY });

const result = await client.process(
  'https://example.com/episode.mp3',
  {
    fillers: true,
    longSilences: true,
    mouthSounds: true,
    removeNoise: true,
    normalize: true,
  }
);

console.log('Cleaned audio:', result.url);

`client.createEdit()`

Submit a job without waiting for completion. Returns the editId for later polling.

const editId = await client.createEdit(
  'https://example.com/episode.mp3',
  {
    fillers: true,
    longSilences: true,
  }
);

console.log('Edit ID:', editId);

`client.getEdit()`

Retrieve the current status and result of a previously created edit.

const edit = await client.getEdit('edit_abc123');

console.log(edit.status); // 'PENDING' | 'STARTED' | 'SUCCESS' | 'FAILURE' | 'RETRY'

if (edit.status === 'SUCCESS') {
  console.log('Download URL:', edit.result.url);
}

Polling manually

async function waitForEdit(editId: string) {
  while (true) {
    const edit = await client.getEdit(editId);

    if (edit.status === 'SUCCESS') return edit;
    if (edit.status === 'FAILURE') throw new Error('Edit failed');

    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

`client.checkAuth()`

Verify your API key and retrieve account information.

const account = await client.checkAuth();
console.log(account);

TypeScript support

The SDK ships with full TypeScript definitions. All config options and response types are typed:

import Cleanvoice, { ProcessingConfig, ProcessResult } from '@cleanvoice/cleanvoice-sdk';

const config: ProcessingConfig = {
  fillers: true,
  normalize: true,
  exportFormat: 'wav',
};

const result: ProcessResult = await client.process(url, config);

Usage in Next.js

// app/api/clean/route.ts
import { NextResponse } from 'next/server';
import Cleanvoice from '@cleanvoice/cleanvoice-sdk';

const client = new Cleanvoice({ apiKey: process.env.CLEANVOICE_API_KEY });

export async function POST(req: Request) {
  const { url } = await req.json();

  const editId = await client.createEdit(url, {
    fillers: true,
    longSilences: true,
  });

  return NextResponse.json({ editId });
}

On this page