Quickstart

pip install kugelaudio

uv add kugelaudio

import os

from kugelaudio import KugelAudio

# Initialize the client
client = KugelAudio(api_key=os.environ["KUGELAUDIO_API_KEY"])

# Generate speech
audio = client.tts.generate(
    text="Hello, world!",
    model_id="kugel-3",
    voice_id=1071,
)

# Save to file
audio.save("output.wav")

import asyncio
import os

from kugelaudio import AudioChunk, KugelAudio

async def main():
    # Create a pre-connected client (handshake happens here)
    client = await KugelAudio.create(api_key=os.environ["KUGELAUDIO_API_KEY"])

    # First request is now fast: no handshake on the hot path
    async for item in client.tts.stream_async("Hello, world!", voice_id=1071):
        if isinstance(item, AudioChunk):
            play_audio(item.audio)

    await client.aclose()

asyncio.run(main())

import os

from kugelaudio import KugelAudio

client = KugelAudio(api_key=os.environ["KUGELAUDIO_API_KEY"])
with client.tts.streaming_session_sync(voice_id=1071) as session:
    for chunk in session.send("Hello, world!"):
        play_audio(chunk.audio)
    for chunk in session.flush():
        play_audio(chunk.audio)

import os

from kugelaudio import KugelAudio

# Initialize client
client = KugelAudio(api_key=os.environ["KUGELAUDIO_API_KEY"])

# List available models
print("Available Models:")
for model in client.models.list():
    print(f"  - {model.id}: {model.name}")

# List available voices
print("\nAvailable Voices:")
result = client.voices.list(limit=5)
for voice in result.voices:
    print(f"  - {voice.id}: {voice.name}")

# Generate audio
print("\nGenerating audio...")
audio = client.tts.generate(
    text="Welcome to KugelAudio. This is an example of high-quality text-to-speech synthesis.",
    model_id="kugel-3",
    voice_id=1071,
)

print(f"Generated {audio.duration_seconds:.2f}s of audio in {audio.generation_ms:.0f}ms")
print(f"Real-time factor: {audio.rtf:.2f}x")

# Save to file
audio.save("example.wav")
print("Saved to example.wav")

# Close client
client.close()

pip install "kugelaudio[turn-detection]"
hf auth login  # the model bundle is downloaded from Hugging Face

from kugelaudio.turn import TurnDetector, TurnMessage

detector = TurnDetector.from_pretrained()
turn = detector.create_session("en")

# Optional: prior dialogue, separate from the current user transcript
turn.update_history([
    TurnMessage("user", "I'd like to book a trip."),
    TurnMessage("assistant", "Where would you like to go?"),
])

# Feed the current user's audio and interim transcript continuously
turn.push_pcm16(pcm_chunk, sample_rate=16_000)
turn.update_transcript("To Berlin, and then")

# Call with the current silence duration whenever your VAD reports silence
decision = turn.observe_silence(duration_ms=200)
if decision.end_turn:
    turn.reset_turn()  # start the assistant response, then reset