cleanvoice-sdk 1.0.1

Official Python SDK for Cleanvoice AI audio processing

Cleanvoice Python SDK

Official Python SDK for Cleanvoice AI - AI-powered audio processing and enhancement.

Features

• 🎵 Audio Processing: Remove fillers, background noise, long silences, and more
• 📹 Video Support: Process audio tracks from video files without ffmpeg
• 📝 Transcription: Convert speech to text with high accuracy
• 📊 Summarization: Generate summaries, chapters, and key learnings
• 🔧 Type Safe: Full type hints with Pydantic models
• ⚡ Developer Friendly: Simple, intuitive API design
• 🔄 Async Support: Modern async/await patterns
• 🎛️ Extensible: Comprehensive configuration options
• 📦 No FFmpeg Required: Built-in audio/video handling with librosa, soundfile, and PyAV

Installation

pip install cleanvoice-sdk

Optional Dependencies

For development:

pip install cleanvoice-sdk[dev]

Quick Start

from cleanvoice import Cleanvoice

cv = Cleanvoice({'api_key': 'your-api-key-here'})

# Process audio with AI
result = cv.process(
    "https://example.com/podcast.mp3",
    {
        'fillers': True,
        'normalize': True,
        'transcription': True,
        'summarize': True
    }
)

print(f"Processed audio: {result.audio.url}")
print(f"Summary: {result.transcript.summary}")

# Download the processed file
downloaded_path = cv.download_file(result.audio.url, "enhanced_audio.mp3")
print(f"Downloaded to: {downloaded_path}")

Authentication

Get your API key from the Cleanvoice Dashboard.

from cleanvoice import Cleanvoice

cv = Cleanvoice({
    'api_key': 'your-api-key-here',
    # Optional: custom base URL
    'base_url': 'https://api.cleanvoice.ai/v2',
    # Optional: request timeout in seconds
    'timeout': 60
})

API Reference

process(file_input, config, progress_callback=None)

Process an audio or video file with AI enhancement.

Parameters:

• file_input (str): URL to audio/video file or local file path
• config (ProcessingConfig or dict): Processing options
• progress_callback (callable, optional): Callback function for progress updates

Returns: ProcessResult

from cleanvoice import Cleanvoice

cv = Cleanvoice({'api_key': 'your-api-key'})

def progress_callback(data):
    print(f"Status: {data['status']}, Progress: {data.get('result', {}).get('done', 0)}%")

result = 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
    },
    progress_callback=progress_callback
)

# Access results
print(result.audio.url)           # Download URL
print(result.audio.statistics)    # Processing stats
print(result.transcript.text)     # Full transcript
print(result.transcript.summary)  # AI summary

create_edit(file_input, config)

Create an edit job without waiting for completion.

from cleanvoice import Cleanvoice

cv = Cleanvoice({'api_key': 'your-api-key'})

edit_id = cv.create_edit(
    "https://example.com/audio.mp3",
    {'fillers': True, 'normalize': True}
)

print(f'Edit ID: {edit_id}')

File Upload and Download

Upload Local Files

Upload local audio/video files for processing:

# Upload a file and get its URL
uploaded_url = cv.upload_file("local_audio.mp3")
print(f"Uploaded to: {uploaded_url}")

# Upload with custom filename
uploaded_url = cv.upload_file("local_audio.mp3", "my_custom_name.mp3")

# Process local file directly (automatic upload)
result = cv.process("local_audio.mp3", {"fillers": True})

Download Processed Files

Download the enhanced audio files:

# Download with automatic filename
downloaded_path = cv.download_file(result.audio.url)
print(f"Downloaded to: {downloaded_path}")

# Download with custom path
downloaded_path = cv.download_file(result.audio.url, "enhanced_audio.mp3")

# Process and download in one step
result, downloaded_path = cv.process_and_download(
    "audio.mp3",
    "output.mp3", 
    {"fillers": True, "normalize": True}
)
print(f"Processed and saved to: {downloaded_path}")

Complete Workflow

from cleanvoice import Cleanvoice

cv = Cleanvoice({"api_key": "your-api-key"})

# Upload, process, and download in one line
result, output_file = cv.process_and_download(
    "input_audio.mp3",     # Local file (automatically uploaded)
    "enhanced_output.mp3", # Output filename  
    {
        "fillers": True,
        "normalize": True,
        "transcription": True,
        "summarize": True
    }
)

get_edit(edit_id)

Get the status and results of an edit job.

from cleanvoice import Cleanvoice

cv = Cleanvoice({'api_key': 'your-api-key'})

edit = cv.get_edit(edit_id)

if edit.status == 'SUCCESS':
    print(f'Download URL: {edit.result.download_url}')
else:
    print(f'Status: {edit.status}')  # PENDING, STARTED, RETRY, FAILURE

check_auth()

Verify API authentication and get account information.

from cleanvoice import Cleanvoice

cv = Cleanvoice({'api_key': 'your-api-key'})

account = cv.check_auth()
print('Account info:', account)

File Handling Without FFmpeg

The SDK includes built-in support for audio and video files using PyAV without requiring FFmpeg:

Audio File Information

from cleanvoice import get_audio_info

info = get_audio_info('path/to/audio.mp3')
print(f"Duration: {info.duration}s")
print(f"Sample Rate: {info.sample_rate}Hz")
print(f"Channels: {info.channels}")

Video File Information

from cleanvoice import get_video_info

info = get_video_info('path/to/video.mp4')
print(f"Duration: {info.duration}s")
print(f"Resolution: {info.width}x{info.height}")
print(f"FPS: {info.fps}")
print(f"Has Audio: {info.has_audio}")

Extract Audio from Video

from cleanvoice import extract_audio_from_video

audio_path = extract_audio_from_video(
    'path/to/video.mp4',
    'extracted_audio.wav'  # Optional output path
)
print(f"Extracted audio: {audio_path}")

Configuration Options

Audio Processing

Option	Type	Default	Description
fillers	bool	False	Remove filler sounds (um, uh, etc.)
stutters	bool	False	Remove stutters
long_silences	bool	False	Remove long silences
mouth_sounds	bool	False	Remove mouth sounds
hesitations	bool	False	Remove hesitations
breath	bool	False	Reduce breath sounds
remove_noise	bool	True	Remove background noise
keep_music	bool	False	Preserve music sections
normalize	bool	False	Normalize audio levels
sound_studio	bool	False	AI-powered enhancement

Output Options

Option	Type	Default	Description
export_format	str	'auto'	Output format: auto, mp3, wav, flac, m4a
mute_lufs	float	-80	Mute threshold in LUFS (negative)
target_lufs	float	-16	Target loudness in LUFS (negative)
export_timestamps	bool	False	Export edit timestamps

AI Features

Option	Type	Default	Description
transcription	bool	False	Generate speech-to-text
summarize	bool	False	Generate AI summary (requires transcription)
social_content	bool	False	Optimize for social media (requires summarize)

Other Options

Option	Type	Default	Description
video	bool	auto-detected	Process video file
merge	bool	False	Merge multi-track audio
send_email	bool	False	Email results to account

Examples

Basic Audio Cleaning

from cleanvoice import Cleanvoice

cv = Cleanvoice({'api_key': 'your-api-key'})

result = cv.process(
    "https://example.com/podcast.mp3",
    {
        'fillers': True,
        'long_silences': True,
        'normalize': True,
        'remove_noise': True
    }
)

print(f"Cleaned audio: {result.audio.url}")
print(f"Removed {result.audio.statistics.FILLER_SOUND} filler sounds")

Transcription and Summary

from cleanvoice import Cleanvoice

cv = Cleanvoice({'api_key': 'your-api-key'})

result = cv.process(
    "https://example.com/interview.wav",
    {
        'transcription': True,
        'summarize': True,
        'normalize': True
    }
)

print('Title:', result.transcript.title)
print('Summary:', result.transcript.summary)
print('Chapters:', result.transcript.chapters)

Video Processing

from cleanvoice import Cleanvoice

cv = Cleanvoice({'api_key': 'your-api-key'})

result = cv.process(
    "https://example.com/video.mp4",
    {
        'video': True,  # Optional: auto-detected
        'fillers': True,
        'transcription': True,
        'export_format': 'mp3'
    }
)

print('Processed audio:', result.audio.url)

Batch Processing

from cleanvoice import Cleanvoice
import time

cv = Cleanvoice({'api_key': 'your-api-key'})

files = [
    "https://example.com/episode1.mp3",
    "https://example.com/episode2.mp3",
    "https://example.com/episode3.mp3"
]

edit_ids = []
for file in files:
    edit_id = cv.create_edit(file, {'fillers': True, 'normalize': True})
    edit_ids.append(edit_id)

# Poll for completion
results = []
for edit_id in edit_ids:
    while True:
        edit = cv.get_edit(edit_id)
        if edit.status == 'SUCCESS':
            results.append(edit)
            break
        elif edit.status == 'FAILURE':
            print(f"Failed: {edit_id}")
            break
        else:
            time.sleep(5)  # Wait 5 seconds before polling again

print(f'All processing completed: {len(results)} files')

Error Handling

from cleanvoice import Cleanvoice, ApiError, FileValidationError

cv = Cleanvoice({'api_key': 'your-api-key'})

try:
    result = cv.process(
        "https://example.com/audio.mp3",
        {'fillers': True, 'normalize': True}
    )
    print('Success:', result.audio.url)
except ApiError as e:
    print(f'API Error: {e.message}')
    if e.status_code:
        print(f'HTTP Status: {e.status_code}')
        print(f'Error Code: {e.error_code}')
except FileValidationError as e:
    print(f'File Error: {e}')
except Exception as e:
    print(f'Unexpected Error: {e}')

Supported File Formats

Audio Formats

• WAV (.wav)
• MP3 (.mp3)
• OGG (.ogg)
• FLAC (.flac)
• M4A (.m4a)
• AIFF (.aiff)
• AAC (.aac)

Video Formats

• MP4 (.mp4)
• MOV (.mov)
• WebM (.webm)
• AVI (.avi)
• MKV (.mkv)

Requirements

• Python 3.8+
• No FFmpeg required for basic audio/video processing

Development

Installing for Development

git clone https://github.com/cleanvoice/cleanvoice-python-sdk
cd cleanvoice-python-sdk
pip install -e .[dev]

Running Tests

pytest

Code Formatting

black src/
isort src/

Type Checking

mypy src/

Contributing

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

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 📧 Email Support
• 🐛 Report Issues