Cleanvoice SDK

Official TypeScript SDK for Cleanvoice AI. Upload local files or use remote URLs, process audio or video, and download cleaned results from Node.js.

Table of Contents

• Installation
• Quick Start
• Authentication
• Common Patterns
• Examples
• File Upload and Download
• API Reference
• Configuration Options
• Error Handling
• Supported Formats
• Development

Installation

npm install @cleanvoice/cleanvoice-sdk

Quick Start

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

const client = Cleanvoice.fromEnv();

const result = await client.process(
  'https://example.com/podcast.mp3',
  {
    fillers: true,
    normalize: true,
    studio_sound: true,
    summarize: true,
  },
  {
    outputPath: 'podcast-clean.mp3',
  }
);

console.log(result.media.url);
console.log(result.audio.localPath);
console.log(result.transcript?.summary);

Authentication

Get your API key from the Cleanvoice Dashboard.

Recommended:

export CLEANVOICE_API_KEY="your-api-key-here"

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

const client = Cleanvoice.fromEnv();

Explicit constructor:

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

const client = new Cleanvoice({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://api.cleanvoice.ai/v2',
  timeout: 60000,
});

Common Patterns

Choose the pattern that fits your workflow:

Pattern	When to use
process()	One-call processing for scripts, jobs, and backend routes
createEdit() + getEdit()	Submit now, poll later
process(..., { outputPath })	Process and save in one call
processAndDownload()	Get both the result object and local saved path

Notes:

• Local file upload is supported for Node.js and other server-side runtimes.
• Browser clients should keep API keys server-side and use backend routes.
• social_content: true automatically enables summarize.
• summarize: true automatically enables transcription.

Examples

Basic Audio Cleaning

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

const client = Cleanvoice.fromEnv();

const result = await client.process('https://example.com/podcast.mp3', {
  fillers: true,
  long_silences: true,
  normalize: true,
  remove_noise: true,
});

console.log(result.audio.url);
console.log(result.audio.statistics.FILLER_SOUND);

Local File Upload

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

const client = Cleanvoice.fromEnv();

const result = await client.process(
  '/absolute/path/to/recording.mp3',
  {
    normalize: true,
    studio_sound: true,
  },
  {
    outputPath: 'recording-clean.mp3',
  }
);

console.log(result.audio.localPath);

Progress Updates

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

const client = Cleanvoice.fromEnv();

const result = await client.process(
  'https://example.com/audio.mp3',
  { summarize: true },
  {
    polling: {
      onProgress: ({ status, progress, attempt }) => {
        console.log(`Attempt ${attempt}: ${status}`, progress?.done ?? 0);
      },
    },
  }
);

console.log(result.transcript?.summary);

Submit First, Poll Later

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

const client = Cleanvoice.fromEnv();

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

const edit = await client.getEdit(editId);
console.log(edit.status);

More Examples

• Node example
• Next.js example app

File Upload and Download

Upload Only

const url = await client.uploadFile('/absolute/path/to/audio.mp3');
console.log(url);

Download Only

const localPath = await client.downloadFile(
  'https://cdn.cleanvoice.ai/output/audio.mp3',
  'audio.mp3'
);

Download from a Result

const result = await client.process('https://example.com/audio.mp3', {
  normalize: true,
});

const savedPath = await result.audio.download('enhanced.mp3');
console.log(savedPath);

One-Call Process and Download

const [result, savedPath] = await client.processAndDownload(
  'https://example.com/audio.mp3',
  'enhanced.mp3',
  {
    fillers: true,
    normalize: true,
  }
);

console.log(savedPath);
console.log(result.audio.localPath);

API Reference

Cleanvoice.fromEnv(options?)

Creates a client from environment variables.

Default variables:

• CLEANVOICE_API_KEY
• CLEANVOICE_BASE_URL
• CLEANVOICE_TIMEOUT

process(fileInput, config?, options?)

Processes a remote URL or local file path and waits for completion.

options supports:

• outputPath
• download
• templateId
• uploadType
• polling

createEdit(fileInput, config?, options?)

Creates an edit job and returns an edit ID without waiting for completion.

getEdit(editId)

Fetches the latest edit status and result payload.

uploadFile(filePath, filename?)

Uploads a local file and returns the public uploaded URL.

downloadFile(url, outputPath?)

Downloads a remote file to disk.

processAndDownload(fileInput, outputPath?, config?, options?)

Processes a file and returns both the ProcessResult and the saved output path.

checkAuth()

Verifies the API key and returns the current credit balances.

const account = await client.checkAuth();

console.log(account.credit.total);
console.log(account.credit.subscription);
console.log(account.credit.payg);

The JavaScript SDK returns the public credit balances only.

Configuration Options

Core Processing

Option	Type	Description
fillers	boolean	Remove filler sounds
stutters	boolean	Remove stutters
long_silences	boolean	Remove long silences
mouth_sounds	boolean	Remove mouth sounds
hesitations	boolean	Remove hesitations
muted	boolean	Mute edits instead of cutting
remove_noise	boolean	Remove background noise
keep_music	boolean	Preserve music sections
breath	boolean | string	Breath reduction mode
normalize	boolean	Normalize loudness
autoeq	boolean	Legacy automatic EQ
studio_sound	boolean | string	Studio sound mode
sound_studio	boolean | string	Legacy alias for studio_sound

Output and Routing

Option	Type	Description
export_format	'auto' | 'mp3' | 'wav' | 'flac' | 'm4a'	Output format
mute_lufs	number	Mute threshold in LUFS
target_lufs	number	Target loudness in LUFS
export_timestamps	boolean	Export timestamp markers
signed_url	string	Upload results to your own signed URL
send_email	boolean	Email the result to the account

AI Features

Option	Type	Description
transcription	boolean	Generate transcription
summarize	boolean	Generate summarization
social_content	boolean	Generate social-ready content

Media and Advanced

Option	Type	Description
video	boolean	Force video mode
merge	boolean	Merge multi-track audio
audio_for_edl	boolean	Backend-specific audio-for-EDL flag
automix	boolean	Backend automix flag
trim	boolean	Backend trim flag
waveform_preview	boolean	Request waveform preview data

Error Handling

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

const client = Cleanvoice.fromEnv();

try {
  const result = await client.process('https://example.com/audio.mp3', {
    fillers: true,
    normalize: true,
  });
  console.log(result.audio.url);
} catch (error) {
  if (error instanceof ApiError) {
    console.error(error.message);
    console.error(error.status);
    console.error(error.code);
  } else {
    console.error(error);
  }
}

The client retries brief transient transport and HTTP failures during requests and polling.

Supported Formats

Remote media URLs:

• http://
• https://

Local uploads (audio):

• .wav
• .mp3
• .flac
• .m4a

Video:

• .mp4
• .mov
• .webm
• .avi
• .mkv

Development

npm run build
npm test
npm run test:coverage
npm run lint

Requirements

• Node.js 16+
• TypeScript 5+

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes with tests.
4. Submit a pull request.

Support

Documentation	docs.cleanvoice.ai
Email	support@cleanvoice.ai
Issues	GitHub Issues

License

MIT - see LICENSE.