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. It works in Node.js and in the browser. Only reading and writing files by path needs Node.js; in the browser pass a Blob, File, ArrayBuffer or Uint8Array.

Enhance a recording

import { KugelAudio, loadAudio } from 'kugelaudio';

const client = new KugelAudio({ apiKey: 'YOUR_API_KEY' });

const result = await client.enhance.generate(await loadAudio('call.wav'), {
  model: 'clarity-1',
});
console.log(result.duration, 'seconds');
await result.save('call-clean.wav'); // Node.js only

In the browser, pass the file straight from an <input type="file"> and play the result:

const file = input.files![0];
const result = await client.enhance.generate(file, { model: 'clarity-1' });
audioElement.src = URL.createObjectURL(result.toBlob());

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.

const result = await client.enhance.generate(await loadAudio('meeting.wav'), {
  model: 'clarity-1',
  speaker: await loadAudio('speaker.wav'),
});
await result.save('one-voice.wav');

`generate`

generate(audio: AudioInput, options: EnhanceGenerateOptions): Promise<EnhancedAudio>

Argument	Type	Description
`audio`	`AudioInput`	The recording: `await loadAudio(...)`, or the WAV file itself as a `Blob`, `File`, `ArrayBuffer` or `Uint8Array`. 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. File paths are not accepted here; load them with `loadAudio`.
`options.model`	`string`	Required. `'clarity-1'`.
`options.speaker`	`AudioInput`	Optional. A 2–8 second sample of one voice. 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. Every generate call on one client reuses the kept-alive connections of fetch, so only the first request pays for connecting.

`prewarm`

prewarm(): Promise<void>

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: fetch closes connections that sit idle for a few seconds.

await client.enhance.prewarm();
const result = await client.enhance.generate(await loadAudio('call.wav'), { model: 'clarity-1' });

The warm-up is not billed and does not count against your rate limits. It never rejects: a network error, a timeout, or a refused warm-up such as 401 for a bad API key, is logged with console.warn and the first request connects as usual and throws its own error.

Enhance live audio

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

import { KugelAudio, loadAudio, loadAudioStream } from 'kugelaudio';

const client = new KugelAudio({ apiKey: 'YOUR_API_KEY' });

const input = await loadAudioStream('call.wav');
for await (const chunk of client.enhance.stream(input, { model: 'clarity-1' })) {
  console.log(chunk.length, 'bytes'); // mono PCM16 at 24 kHz, as it arrives
}

Add speaker: await loadAudio('speaker.wav') to keep one voice.

Raw PCM input

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

async function* capture(): AsyncGenerator<Uint8Array> {
  // yield mono PCM16 chunks at 16 kHz as your source produces them
}

for await (const chunk of client.enhance.stream(capture(), {
  model: 'clarity-1',
  sampleRate: 16000,
})) {
  play(chunk);
}

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

`stream`

stream(
  audio: AudioStream | Iterable<PcmChunk> | AsyncIterable<PcmChunk>,
  options: EnhanceStreamOptions,
): AsyncGenerator<Uint8Array, void, undefined>

Argument	Type	Description
`audio`	`AudioStream`, or an iterable of `PcmChunk`	An `AudioStream` from `loadAudioStream`, or raw mono PCM16 chunks.
`options.model`	`string`	Required. `'clarity-1'`.
`options.sampleRate`	`number`	Sample rate of raw chunks, 8000–48000. Required for raw chunks; taken from an `AudioStream`, and must match it if you pass both.
`options.speaker`	`AudioInput`	Optional. A 2–8 second sample of one voice.

Breaking out of the loop closes the connection and stops sending. 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.

const session = client.enhance.session();
await session.connect();
try {
  for (const path of ['first.wav', 'second.wav']) {
    const input = await loadAudioStream(path);
    for await (const chunk of session.stream(input, { model: 'clarity-1' })) {
      play(chunk);
    }
  }
} finally {
  await session.close();
}

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

`loadAudio`

loadAudio(source: AudioSource): Promise<LoadedAudio>

Loads a WAV file for generate and for speaker. source is a path (Node.js only) or the WAV file as a Blob, File, ArrayBuffer or Uint8Array. The file is sent as-is and decoded by the server, so every supported WAV format works. The returned LoadedAudio has:

Field	Type	Description
`data`	`Uint8Array`	The WAV file bytes.
`filename`	`string`	File name sent with the upload (`'audio.wav'` when there is none).
`duration`	`number \| undefined`	Duration in seconds when the header can be read locally.

`loadAudioStream`

loadAudioStream(source: AudioSource, options?: LoadAudioStreamOptions): Promise<AudioStream>

Loads a 16-bit integer PCM WAV for stream. Stereo and multi-channel audio is mixed down to mono, and the sample rate is read from the file. options.chunkSeconds (greater than 0, at most 1, default 0.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 sampleRate (Hz) and duration (seconds), and iterating it (with for or for await) yields Uint8Array 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`	`Uint8Array`	Raw mono PCM16 samples, little-endian.
`sampleRate`	`number`	`24000`.
`duration`	`number`	Duration in seconds.
`wav`	`Uint8Array`	The audio as WAV file bytes.
`toBlob()`	`Blob`	The audio as an `audio/wav` Blob, for example for an `<audio>` element.
`save(path)`	`Promise<void>`	Writes the audio to `path` as a WAV file. Node.js only.

The package also exports ENHANCED_SAMPLE_RATE (24000), TASK_NOISE_REMOVAL, TASK_TARGET_SPEAKER_EXTRACTION and the types AudioInput, PcmChunk, AudioSource, EnhanceGenerateOptions, EnhanceStreamOptions and LoadAudioStreamOptions.

Errors

Thrown by the SDK itself, not the server:

Error	When
`TypeError`	`audio` (for `generate`) or `speaker` is not audio, for example a path string. Wrap it in `await loadAudio(...)`.
`ValidationError`	`model` is empty; `stream` got a WAV file or `LoadedAudio` (use `loadAudioStream`); raw chunks without `sampleRate`, or a `sampleRate` that does not match the `AudioStream`; a chunk that is not binary; `loadAudioStream` got a WAV that is not 16-bit integer PCM, or a `chunkSeconds` outside (0, 1]; an unreadable or empty file.
`KugelAudioError`	A file path was used outside Node.js.

Thrown from the server’s answer, all subclasses of KugelAudioError with statusCode, errorCode, requestId and retryAfter: ValidationError (the server rejected the input), RateLimitError, InsufficientCreditsError, AuthenticationError and ConnectionError. What each means and what to do is in Limits and errors.

import { InsufficientCreditsError, RateLimitError } from 'kugelaudio';

try {
  await client.enhance.generate(await loadAudio('call.wav'), { model: 'clarity-1' });
} catch (e) {
  if (e instanceof RateLimitError) {
    console.log('retry in', e.retryAfter, 'seconds'); // undefined for the concurrency limit
  } else if (e instanceof InsufficientCreditsError) {
    console.log(e.errorCode, e.message); // INSUFFICIENT_CREDITS or FREE_PERIOD_ENDED
  } else {
    throw e;
  }
}

In Node.js, a stream refused while connecting reports both 402s with errorCode INSUFFICIENT_CREDITS; on the free month it means the month is over. A browser’s WebSocket does not reveal why an upgrade was refused, so in the browser every refusal while connecting (a bad key, a limit, the free month, capacity) arrives as ConnectionError. Call generate once to see the reason.

Next steps

Speech enhancement guide: tasks, free month, paid plan and limits
Speech enhancement API: REST and WebSocket wire protocol

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`

`prewarm`

Enhance live audio

Raw PCM input

`stream`

Several audios on one connection

Loading audio

`loadAudio`

`loadAudioStream`

`EnhancedAudio`

Errors

Next steps

​Enhance a recording

​Keep one voice

​generate

​prewarm

​Enhance live audio

​Raw PCM input

​stream

​Several audios on one connection

​Loading audio

​loadAudio

​loadAudioStream

​EnhancedAudio

​Errors

​Next steps

Enhance a recording

Keep one voice

`generate`

`prewarm`

Enhance live audio

Raw PCM input

`stream`

Several audios on one connection

Loading audio

`loadAudio`

`loadAudioStream`

`EnhancedAudio`

Errors

Next steps