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.

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

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

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

Support


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

License

MIT - see LICENSE.

FilesExpand file tree

README.md

Latest commit

History