rumik 0.3.0

The official Python SDK for the Rumik Silk text-to-speech API.

Rumik Python SDK

The official Python SDK for the Rumik Silk text-to-speech API.

Turn text into natural, expressive speech with a few lines of code.

Installation

pip install rumik

Real-time WebSocket streaming needs an extra dependency:

pip install "rumik[ws]"

Quickstart

from rumik import Rumik

client = Rumik(api_key="rk_live_...")  # or set the RUMIK_API_KEY env var

audio = client.speech.create(
    text="[happy] Namaste! Kaise hain aap?",
    model="muga",
)
audio.save("hello.wav")

Controlling the voice (mulberry model)

audio = client.speech.create(
    text="Hi there, how can I help you today?",
    model="mulberry",
    description="a warm 30s female voice, smooth timbre, conversational pacing",
    speaker="speaker_2",
)
audio.save("greeting.wav")

Async

For servers and high-concurrency workloads, use AsyncRumik with async/await:

import asyncio
from rumik import AsyncRumik

async def main():
    async with AsyncRumik() as client:  # reads RUMIK_API_KEY
        audio = await client.speech.create(text="Hello!", model="mulberry")
        audio.save("hello.wav")

asyncio.run(main())

Fire many requests concurrently with asyncio.gather:

async with AsyncRumik() as client:
    clips = await asyncio.gather(
        client.speech.create(text="One"),
        client.speech.create(text="Two"),
        client.speech.create(text="Three"),
    )

Real-time streaming

For voice agents and low-latency playback, stream PCM audio over a WebSocket as it is generated. Requires the websockets extra (pip install "rumik[ws]").

from rumik import Rumik

client = Rumik()
with client.speech.stream(text="Streaming in real time.", model="mulberry") as stream:
    for chunk in stream:        # raw PCM (24 kHz mono 16-bit) as it arrives
        play(chunk)             # feed your audio device

# After the stream ends:
print(stream.request_id, stream.credits_used)

Save a stream straight to a playable WAV file:

with client.speech.stream(text="Hello!", model="mulberry") as stream:
    stream.save("out.wav")

Async streaming mirrors this with async with / async for:

async with AsyncRumik() as client:
    async with client.speech.stream(text="Hello!") as stream:
        async for chunk in stream:
            await play(chunk)

The SDK handles the two-step handshake (minting a session token, then opening the WebSocket) for you — you just iterate audio.

Voice-agent sessions (multi-utterance + barge-in)

For voice agents, open a persistent session: keep one WebSocket open for the whole conversation, send() an utterance for each thing the agent says, and interrupt() (or just send new text) to barge in.

from rumik import Rumik, AudioChunk, UtteranceDone

client = Rumik()
with client.speech.session(model="mulberry", speaker="speaker_1") as session:
    session.send("Hello! How can I help you today?")
    for event in session:
        if isinstance(event, AudioChunk):
            play(event.data)
            if user_started_talking():
                session.interrupt()                 # barge-in
                session.send("Sorry, go ahead.")
        elif isinstance(event, UtteranceDone):
            break

Sending a new utterance while one is generating interrupts it — the older one comes back as an UtteranceCancelled event with reason="interrupt". The async client mirrors this with async with / async for, and you can await session.interrupt() / await session.send(...) from another task.

Models

Model	Steering
muga	Expressive. Prefix text with a tone tag, e.g. [happy].
mulberry	Faster. Use a natural-language description + speaker.

Tone tags for muga: neutral, happy, sad, excited, angry, whisper.

Configuration

client = Rumik(
    api_key="rk_live_...",   # falls back to RUMIK_API_KEY
    timeout=60.0,            # per-request timeout (seconds)
    max_retries=2,           # automatic retries on 429 / 5xx / network errors
)

Error handling

from rumik import Rumik, RateLimitError, AuthenticationError, APIStatusError

client = Rumik()
try:
    audio = client.speech.create(text="Hello")
except AuthenticationError:
    print("Check your API key.")
except RateLimitError as e:
    print(f"Slow down. Retry after {e.retry_after}s.")
except APIStatusError as e:
    print(f"API error {e.status_code}: {e}")

Audio format

Rumik Silk returns 24 kHz, mono, signed 16-bit PCM. The HTTP API wraps it in a WAV container, so audio.save("out.wav") produces a ready-to-play file.

License

MIT