Official TypeScript SDK for Cleanvoice AI audio processing
npm install @cleanvoice/cleanvoice-sdkOfficial TypeScript SDK for Cleanvoice AI - AI-powered audio processing and enhancement.


- 🎵 Audio Processing: Remove fillers, background noise, long silences, and more
- 📹 Video Support: Process audio tracks from video files
- 📝 Transcription: Convert speech to text with high accuracy
- 📊 Summarization: Generate summaries, chapters, and key learnings
- 🔧 Type Safe: Full TypeScript support with comprehensive type definitions
- ⚡ Developer Friendly: Simple, intuitive API design
- 🔄 Async/Await: Modern promise-based API
- 🎛️ Extensible: Comprehensive configuration options
``bash`
npm install @cleanvoice/cleanvoice-sdk
`typescript
import { Cleanvoice } from '@cleanvoice/cleanvoice-sdk';
const cv = new Cleanvoice({
apiKey: process.env.CLEANVOICE_API_KEY!
});
// Process audio with AI
const { audio, transcript } = await cv.process(
"https://example.com/podcast.mp3",
{
fillers: true,
normalize: true,
transcription: true,
summarize: true
}
);
console.log('Processed audio:', audio.url);
console.log('Summary:', transcript?.summary);
`
Get your API key from the Cleanvoice Dashboard.
`typescript`
const cv = new Cleanvoice({
apiKey: 'your-api-key-here',
// Optional: custom base URL
baseUrl: 'https://api.cleanvoice.ai/v2',
// Optional: request timeout in milliseconds
timeout: 60000
});
Process an audio or video file with AI enhancement.
Parameters:
- fileInput (string): URL to audio/video fileconfig
- (ProcessingConfig): Processing options
Returns: Promise
`typescript
import { Cleanvoice } from '@cleanvoice/cleanvoice-sdk';
const cv = new Cleanvoice({
apiKey: process.env.CLEANVOICE_API_KEY!
});
const result = await cv.process(
"https://example.com/audio.mp3",
{
// Audio Enhancement
fillers: true, // Remove filler sounds (um, uh, etc.)
stutters: true, // Remove stutters
long_silences: true, // Remove long silences
mouth_sounds: true, // Remove mouth sounds
breath: true, // Reduce breath sounds
remove_noise: true, // Remove background noise
normalize: true, // Normalize audio levels
// Advanced Options
mute_lufs: -80, // Mute threshold (negative number)
target_lufs: -16, // Target loudness level
export_format: 'mp3', // Output format: auto, mp3, wav, flac, m4a
// AI Features
transcription: true, // Generate transcript
summarize: true, // Generate summary (requires transcription)
social_content: true, // Optimize for social media
// Video
video: false, // Set to true for video files (auto-detected)
// Multi-track
merge: false, // Merge multi-track audio
}
);
// Access results
console.log(result.audio.url); // Download URL
console.log(result.audio.statistics); // Processing stats
console.log(result.transcript?.text); // Full transcript
console.log(result.transcript?.summary); // AI summary
`
Create an edit job without waiting for completion.
`typescript
import { Cleanvoice } from '@cleanvoice/cleanvoice-sdk';
const cv = new Cleanvoice({
apiKey: process.env.CLEANVOICE_API_KEY!
});
const editId = await cv.createEdit(
"https://example.com/audio.mp3",
{ fillers: true, normalize: true }
);
console.log('Edit ID:', editId);
`
Get the status and results of an edit job.
`typescript
import { Cleanvoice } from '@cleanvoice/cleanvoice-sdk';
const cv = new Cleanvoice({
apiKey: process.env.CLEANVOICE_API_KEY!
});
const edit = await cv.getEdit(editId);
if (edit.status === 'SUCCESS') {
console.log('Download URL:', edit.result?.download_url);
} else {
console.log('Status:', edit.status); // PENDING, STARTED, RETRY, FAILURE
}
`
Verify API authentication and get account information.
`typescript
import { Cleanvoice } from '@cleanvoice/cleanvoice-sdk';
const cv = new Cleanvoice({
apiKey: process.env.CLEANVOICE_API_KEY!
});
const account = await cv.checkAuth();
console.log('Account info:', account);
`
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| fillers | boolean | false | Remove filler sounds (um, uh, etc.) |stutters
| | boolean | false | Remove stutters |long_silences
| | boolean | false | Remove long silences |mouth_sounds
| | boolean | false | Remove mouth sounds |hesitations
| | boolean | false | Remove hesitations |breath
| | boolean \| string | false | Reduce breath sounds ("natural", "legacy", "muted") |remove_noise
| | boolean | true | Remove background noise |keep_music
| | boolean | false | Preserve music sections |normalize
| | boolean | false | Normalize audio levels |studio_sound
| | boolean \| string | false | Studio sound algorithm selection ("nightly") |
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| export_format | string | 'auto' | Output format: auto, mp3, wav, flac, m4a |mute_lufs
| | number | -80 | Mute threshold in LUFS (negative) |target_lufs
| | number | -16 | Target loudness in LUFS (negative) |export_timestamps
| | boolean | false | Export edit timestamps |
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| transcription | boolean | false | Generate speech-to-text |summarize
| | boolean | false | Generate AI summary (requires transcription) |social_content
| | boolean | false | Optimize for social media (requires summarize) |
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| video | boolean | auto-detected | Process video file |merge
| | boolean | false | Merge multi-track audio |send_email
| | boolean | false | Email results to account |
`typescript`
interface ProcessResult {
audio: {
url: string; // Download URL
filename: string; // Generated filename
statistics: { // Processing statistics
FILLER_SOUND?: number;
BREATH?: number;
DEADAIR?: number;
STUTTERING?: number;
MOUTH_SOUND?: number;
};
};
transcript?: {
text: string; // Full transcript text
paragraphs: Array<{ // Paragraph-level data
start: number;
end: number;
text: string;
}>;
detailed: { // Word-level data
words: Array<{
id: number;
start: number;
end: number;
text: string;
}>;
paragraphs: Array<{
id: number;
start: number;
end: number;
speaker: string;
}>;
};
summary?: string; // AI-generated summary
title?: string; // AI-generated title
chapters?: Array<{ // Chapter breakdowns
start: number;
title: string;
}>;
};
}
`typescript
import { Cleanvoice } from '@cleanvoice/cleanvoice-sdk';
const cv = new Cleanvoice({
apiKey: process.env.CLEANVOICE_API_KEY!
});
const { audio } = await cv.process(
"https://example.com/podcast.mp3",
{
fillers: true,
long_silences: true,
normalize: true,
remove_noise: true
}
);
console.log(Cleaned audio: ${audio.url});Removed ${audio.statistics.FILLER_SOUND} filler sounds
console.log();`
`typescript
import { Cleanvoice } from '@cleanvoice/cleanvoice-sdk';
const cv = new Cleanvoice({
apiKey: process.env.CLEANVOICE_API_KEY!
});
const { transcript } = await cv.process(
"https://example.com/interview.wav",
{
transcription: true,
summarize: true,
normalize: true
}
);
console.log('Title:', transcript?.title);
console.log('Summary:', transcript?.summary);
console.log('Chapters:', transcript?.chapters);
`
`typescript
import { Cleanvoice } from '@cleanvoice/cleanvoice-sdk';
const cv = new Cleanvoice({
apiKey: process.env.CLEANVOICE_API_KEY!
});
const result = await cv.process(
"https://example.com/video.mp4",
{
video: true, // Optional: auto-detected
fillers: true,
transcription: true,
export_format: 'mp3'
}
);
console.log('Processed audio:', result.audio.url);
`
`typescript
import { Cleanvoice } from '@cleanvoice/cleanvoice-sdk';
const cv = new Cleanvoice({
apiKey: process.env.CLEANVOICE_API_KEY!
});
const files = [
"https://example.com/episode1.mp3",
"https://example.com/episode2.mp3",
"https://example.com/episode3.mp3"
];
const editIds = await Promise.all(
files.map(file => cv.createEdit(file, { fillers: true, normalize: true }))
);
// Poll for completion
const results = await Promise.all(
editIds.map(async (id) => {
let edit;
do {
edit = await cv.getEdit(id);
if (edit.status === 'PENDING' || edit.status === 'STARTED') {
await new Promise(resolve => setTimeout(resolve, 5000));
}
} while (edit.status === 'PENDING' || edit.status === 'STARTED');
return edit;
})
);
console.log('All processing completed:', results.length, 'files');
`
For complete, runnable example applications, check out the examples/ directory:
- Next.js Application: A comprehensive web app demonstrating all SDK features including audio processing, transcription, video processing, and batch operations.
Each example includes:
- Complete setup instructions
- Environment configuration
- Real-world usage patterns
- Error handling
- UI components and styling
To get started with an example:
`bash`
cd examples/nextjs-app
npm install
cp .env.local.example .env.localAdd your API key to .env.local
npm run devError Handling
`typescript
import { Cleanvoice, ApiError } from '@cleanvoice/cleanvoice-sdk';
const cv = new Cleanvoice({
apiKey: process.env.CLEANVOICE_API_KEY!
});
try {
const result = await cv.process(
"https://example.com/audio.mp3",
{ fillers: true, normalize: true }
);
console.log('Success:', result.audio.url);
} catch (error) {
if (error instanceof Error) {
console.error('Error:', error.message);
// Check if it's an API error
const apiError = error as ApiError;
if (apiError.status) {
console.error('HTTP Status:', apiError.status);
console.error('Error Code:', apiError.code);
}
}
}
`
`bash`
npm run build
`bash`
npm test
npm run test:coverage
`bash``
npm run lint
npm run lint:fix
- Node.js 16+
- TypeScript 5+
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
MIT License - see LICENSE file for details.
- 📖 Documentation
- 📧 Email Support
- 🐛 Report Issues