Speech Enhancement

client.enhance sends speech to Clarity (clarity-1) and returns it cleaned: background noise removed, or, when you pass speaker=, only that person’s voice kept. What the two tasks do, the free month, the paid plan and the limits are in the Speech enhancement guide; the wire protocol is in the API reference. generate and stream are async; generate_sync and stream_sync are their blocking twins and take the same arguments.

Enhance a recording

import asyncio

from kugelaudio import KugelAudio, load_audio

client = KugelAudio(api_key="YOUR_API_KEY")

async def main():
    result = await client.enhance.generate(load_audio("call.wav"), model="clarity-1")
    print(result.duration, "seconds")
    result.save("call-clean.wav")

asyncio.run(main())

Without asyncio:

result = client.enhance.generate_sync(load_audio("call.wav"), model="clarity-1")
result.save("call-clean.wav")

Keep one voice

Pass a 2–8 second sample of the person to keep as speaker=. The SDK then switches to target_speaker_extraction; see A good speaker sample.

result = client.enhance.generate_sync(
    load_audio("meeting.wav"),
    model="clarity-1",
    speaker=load_audio("speaker.wav"),
)
result.save("one-voice.wav")

`generate` / `generate_sync`

async def generate(audio: Audio, *, model: str, speaker: Audio | None = None) -> EnhancedAudio
def generate_sync(audio: Audio, *, model: str, speaker: Audio | None = None) -> EnhancedAudio

Argument	Type	Description
`audio`	`Audio`	The recording, from `load_audio`. Any WAV the API accepts: 16-, 24- or 32-bit integer or 32-bit float PCM, mono or stereo, 8–48 kHz, at most 300 seconds.
`model`	`str`	Required. `"clarity-1"`.
`speaker`	`Audio \| None`	A 2–8 second sample of one voice, from `load_audio`. Given: only that voice is kept. Omitted: noise is removed and every voice is kept.

Returns an EnhancedAudio with the same duration as the input. The request is bounded by the client’s timeout (default 60 seconds). Every generate call on one client reuses the same kept-alive connection, so only the first request pays for connecting.

`prewarm` / `prewarm_sync`

async def prewarm() -> None
def prewarm_sync() -> None

Readies enhancement ahead of time. Enhancement capacity scales down when nobody uses it, so the first request after a quiet period can wait several seconds; prewarm sends the warm-up request, which starts enhancement in the background and returns at once, and it opens the connection the next request reuses. Call it as soon as you know audio is coming, for example when the user opens the recording screen: a connection that sits idle for 50 seconds is closed. prewarm warms the connection generate uses and prewarm_sync the one generate_sync uses.

await client.enhance.prewarm()
result = await client.enhance.generate(load_audio("call.wav"), model="clarity-1")

The warm-up is not billed and does not count against your rate limits. It never raises: a network error, or a refused warm-up such as 401 for a bad API key, is logged as a warning and the first request connects as usual and raises its own error. The LiveKit and Pipecat enhancement filters call it for you when they start.

Enhance live audio

stream opens a WebSocket, sends your audio while you iterate, and yields enhanced mono 16-bit PCM at 24 kHz as it is produced. Iteration ends once the last input chunk has been enhanced; the total output matches the input’s duration.

import asyncio

from kugelaudio import KugelAudio, load_audio_stream

client = KugelAudio(api_key="YOUR_API_KEY")

async def main():
    enhanced = bytearray()
    audio = load_audio_stream("call.wav")
    async for chunk in client.enhance.stream(audio, model="clarity-1"):
        enhanced += chunk  # mono PCM16 at 24 kHz, as it arrives

asyncio.run(main())

Add speaker=load_audio("speaker.wav") to keep one voice. stream_sync is the blocking form; it sends from a background thread:

for chunk in client.enhance.stream_sync(load_audio_stream("call.wav"), model="clarity-1"):
    print(len(chunk), "bytes")

Raw PCM input

Audio that is not a WAV file, such as a live capture, goes in as any iterable (or, for stream, async iterable) of mono 16-bit little-endian PCM bytes chunks, with its sample_rate:

def pcm_chunks(path, chunk_bytes=3200):  # 0.1 s of mono PCM16 at 16 kHz
    with open(path, "rb") as f:
        while chunk := f.read(chunk_bytes):
            yield chunk

for chunk in client.enhance.stream_sync(
    pcm_chunks("call.pcm"), model="clarity-1", sample_rate=16000
):
    print(len(chunk), "bytes")

Chunks of at most one second work best; longer ones are split before sending.

`stream` / `stream_sync`

def stream(
    audio: AudioStream | Iterable[bytes] | AsyncIterable[bytes],
    *,
    model: str,
    sample_rate: int | None = None,
    speaker: Audio | None = None,
) -> AsyncIterator[bytes]

def stream_sync(
    audio: AudioStream | Iterable[bytes],
    *,
    model: str,
    sample_rate: int | None = None,
    speaker: Audio | None = None,
) -> Iterator[bytes]

Argument	Type	Description
`audio`	`AudioStream`, or an iterable of `bytes`	An `AudioStream` from `load_audio_stream`, or raw mono PCM16 chunks. `stream_sync` does not take async iterables.
`model`	`str`	Required. `"clarity-1"`.
`sample_rate`	`int \| None`	Sample rate of raw chunks, 8000–48000. Required for raw chunks; taken from an `AudioStream`, and must match it if you pass both.
`speaker`	`Audio \| None`	A 2–8 second sample of one voice, from `load_audio`.

Breaking out of the loop closes the connection and stops sending. With stream, wrap the iterator in contextlib.aclosing to make that cleanup immediate. The client’s timeout bounds the wait for the stream to become ready.

Several audios on one connection

Each stream call opens its own WebSocket. To enhance one audio after another, for example one utterance at a time in a voice agent, open a session instead: it keeps one connection warm and sends each audio over it, so only the first pays for connecting. connect() opens it ahead of the first audio.

async with client.enhance.session() as session:  # connects here
    for path in ("first.wav", "second.wav"):
        async for chunk in session.stream(load_audio_stream(path), model="clarity-1"):
            play(chunk)

session.stream takes the same arguments as stream, and each call may use a different speaker or sample rate. Streams on one session run one after another; each is a request of its own for rate limits and billing. If the server closed the connection in the meantime (60 seconds without audio, one hour after it opened, or a restart), the next stream reconnects without an error. Breaking out of a stream closes the connection; the next stream opens a new one. The WebSocket reference lists the session limits.

Loading audio

`load_audio`

def load_audio(source: str | os.PathLike | bytes) -> Audio

Loads a WAV file, from a path or its bytes, for generate and for speaker=. The file is sent as-is and decoded by the server, so every supported WAV format works. The returned Audio has:

Field	Type	Description
`data`	`bytes`	The WAV file bytes.
`filename`	`str`	File name sent with the upload (`"audio.wav"` for bytes).
`duration`	`float \| None`	Duration in seconds when the header can be read locally, else `None` (for example float WAVs).

`load_audio_stream`

def load_audio_stream(source: str | os.PathLike | bytes, *, chunk_seconds: float = 0.1) -> AudioStream

Loads a 16-bit PCM WAV for stream. Stereo and multi-channel audio is mixed down to mono, and the sample rate is read from the file. chunk_seconds (greater than 0, at most 1) sets the length of each chunk; chunks are sent as fast as the connection allows, and small ones let enhanced audio start coming back sooner. The returned AudioStream has sample_rate (Hz) and duration (seconds), and iterating it yields the bytes chunks; iterating again starts from the beginning. For 24-bit or float WAVs, use generate instead or convert to 16-bit.

`EnhancedAudio`

What generate returns: mono 16-bit PCM at 24 kHz.

Member	Type	Description
`audio`	`bytes`	Raw mono PCM16 samples, little-endian.
`sample_rate`	`int`	`24000`.
`duration`	`float`	Duration in seconds.
`wav`	`bytes`	The audio as WAV file bytes.
`save(path)`	method	Writes the audio to `path` as a WAV file.

Errors

Raised by the SDK itself, not the server:

Exception	When
`TypeError`	`audio` (for `generate`) or `speaker` is not an `Audio`, for example a path string. Wrap it in `load_audio(...)`.
`ValidationError`	`model` is empty; `stream` got a path or WAV bytes (use `load_audio_stream`); raw chunks without `sample_rate`, or a `sample_rate` that does not match the `AudioStream`; a chunk that is not `bytes`; `load_audio_stream` got a WAV that is not 16-bit, or a `chunk_seconds` outside (0, 1]; an unreadable or empty file.

Raised from the server’s answer, all subclasses of KugelAudioError with status_code, error_code, request_id and retry_after: ValidationError (the server rejected the input), RateLimitError, InsufficientCreditsError, AuthenticationError and KugelAudioConnectionError. What each means and what to do is in Limits and errors.

from kugelaudio import InsufficientCreditsError, RateLimitError

try:
    result = client.enhance.generate_sync(load_audio("call.wav"), model="clarity-1")
except RateLimitError as e:
    print("retry in", e.retry_after, "seconds")  # None for the concurrency limit
except InsufficientCreditsError as e:
    print(e.error_code, e.message)  # INSUFFICIENT_CREDITS or FREE_PERIOD_ENDED

A stream refused while connecting reports both 402s with error_code INSUFFICIENT_CREDITS; on the free month it means the month is over.

Next steps

Speech enhancement guide: tasks, free month, paid plan and limits
Speech enhancement API: REST and WebSocket wire protocol
LiveKit and Pipecat: enhancement as a voice-agent input filter

Get started

Build a voice agent

Generate audio

Voices

Enhance audio

Hosting and deployment

SDK Reference

API Reference

Enhance a recording

Keep one voice

`generate` / `generate_sync`

`prewarm` / `prewarm_sync`

Enhance live audio

Raw PCM input

`stream` / `stream_sync`

Several audios on one connection

Loading audio

`load_audio`

`load_audio_stream`

`EnhancedAudio`

Errors

Next steps

​Enhance a recording

​Keep one voice

​generate / generate_sync

​prewarm / prewarm_sync

​Enhance live audio

​Raw PCM input

​stream / stream_sync

​Several audios on one connection

​Loading audio

​load_audio

​load_audio_stream

​EnhancedAudio

​Errors

​Next steps

Enhance a recording

Keep one voice

`generate` / `generate_sync`

`prewarm` / `prewarm_sync`

Enhance live audio

Raw PCM input

`stream` / `stream_sync`

Several audios on one connection

Loading audio

`load_audio`

`load_audio_stream`

`EnhancedAudio`

Errors

Next steps