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
  long_silences?: boolean;  // Trim long silences
  mouth_sounds?: boolean;   // Remove mouth noises
  breath?: boolean;         // Remove audible breathing
  stutters?: boolean;       // Remove stutters
  remove_noise?: boolean;   // Reduce background noise
  studio_sound?: boolean;   // Apply studio sound enhancement
  normalize?: boolean;      // Normalize loudness
  target_lufs?: number;     // Target LUFS level (e.g. -16)
  transcription?: boolean;  // Return transcript
  summarize?: boolean;      // Generate summary and chapters
  social_content?: boolean; // Generate social media copy
  export_format?: 'auto' | 'mp3' | 'wav' | 'flac' | 'm4a';
}

Return value

interface ProcessResult {
  audio: {
    url: string;
    filename: string;
    localPath?: string;
  };
  media: {
    url: string;
    filename: string;
  };
  video: boolean;
  isVideo: boolean;
  transcript?: {
    text: string;
    paragraphs: Array<{ start: number; end: number; text: string }>;
    detailed: {
      words: Array<{ id: number; start: number; end: number; text: string }>;
      paragraphs: Array<{ id: number; start: number; end: number; speaker: string }>;
    };
    summary?: string;
    title?: string;
    chapters?: Array<{ start: number; title: string }>;
    summarization?: {
      title: string;
      summary: string;
      chapters: Array<{ start: number; title: string }>;
      summaries: string[];
      key_learnings: string;
      summary_of_summary: string;
      episode_description: string;
    };
  };
  summarization?: {
    title: string;
    summary: string;
    chapters: Array<{ start: number; title: string }>;
    summaries: string[];
    key_learnings: string;
    summary_of_summary: string;
    episode_description: string;
  };
  socialContent:
    | []
    | {
        newsletter?: string;
        twitter_thread?: string;
        linkedin?: 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,
    long_silences: true,
    mouth_sounds: true,
    remove_noise: true,
    normalize: true,
  }
);

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

Text outputs

const result = await client.process('https://example.com/episode.mp3', {
  transcription: true,
  summarize: true,
  social_content: true,
});

if (result.transcript) {
  console.log(result.transcript.text);
  console.log(result.transcript.paragraphs[0]?.text);
  console.log(result.transcript.detailed.words[0]?.text);
  console.log(result.transcript.summary);
  console.log(result.transcript.title);
  console.log(result.transcript.chapters);
}

if (result.summarization) {
  console.log(result.summarization.title);
  console.log(result.summarization.summary);
  console.log(result.summarization.chapters);
  console.log(result.summarization.key_learnings);
}

if (!Array.isArray(result.socialContent)) {
  console.log(result.socialContent.newsletter);
  console.log(result.socialContent.twitter_thread);
  console.log(result.socialContent.linkedin);
}

`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,
    long_silences: 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' | 'PREPROCESSING' | 'CLASSIFICATION' | 'EDITING' | 'POSTPROCESSING' | 'EXPORT' | 'SUCCESS' | 'FAILURE' | 'RETRY'

if (edit.status === 'SUCCESS' && edit.result && 'download_url' in edit.result) {
  console.log('Download URL:', edit.result.download_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,
  export_format: '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,
    long_silences: true,
  });

  return NextResponse.json({ editId });
}

On this page