Orpheus TTS Python SDK

Stream high-quality speech from the Orpheus TTS model.

Installation

pip install orpheus-tts

Quick Start

from orpheus_tts import OrpheusClient

client = OrpheusClient(api_key="YOUR_API_KEY", provider="PROVIDER_NAME")

# Stream audio chunks
for chunk in client.stream("Hello world!", voice="josh"):
    # chunk is raw PCM bytes (int16, 48kHz, mono)
    print("Received chunk of length:", len(chunk))

Usage

Pre-connect and Save WAV

import time
import wave

from orpheus_tts import OrpheusClient

API_KEY = "YOUR_API_KEY"
PROVIDER = "PROVIDER_NAME"
VOICE = "josh"
TEXT = "Hello from Orpheus."
OUTPUT = "output.wav"

client = OrpheusClient(api_key=API_KEY, provider=PROVIDER)
client.connect(voice=VOICE, websocket_count=1)
time.sleep(1) # Brief pause to ensure connection is stable

chunks = []
start = time.perf_counter()

for i, chunk in enumerate(client.stream(TEXT, voice=VOICE)):
    if i == 0:
        print(f"TTFA: {(time.perf_counter() - start) * 1000:.1f}ms")
    chunks.append(chunk)

client.close()
audio = b"".join(chunks)

with wave.open(OUTPUT, "wb") as wav:
    wav.setnchannels(1)
    wav.setsampwidth(2)
    wav.setframerate(48000)
    wav.writeframes(audio)

Configuration

client = OrpheusClient(
    api_key="YOUR_API_KEY",
    provider="PROVIDER_NAME",
    max_tokens=3000,        # Maximum tokens to generate
    temperature=1.0,        # Sampling temperature
    repetition_penalty=1.1, # Repetition penalty
)

# Or override per-request
for chunk in client.stream(
    "Custom settings for this request.",
    voice="josh",
    max_tokens=2000,
    temperature=0.9,
):
    process(chunk)

Audio Format

All audio is returned as raw PCM with the following format:

• Sample Rate: 48,000 Hz
• Bit Depth: 16-bit signed integer (int16)
• Channels: Mono (1 channel)

Error Handling

from orpheus_tts import OrpheusClient, OrpheusError, AuthenticationError

client = OrpheusClient(api_key="YOUR_API_KEY", provider="PROVIDER_NAME")

try:
    for chunk in client.stream("Hello!", voice="josh"):
        process(chunk)
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except OrpheusError as e:
    print(f"TTS error: {e}")

Connect with environment variables

export ORPHEUS_TTS_API_KEY="YOUR_API_KEY"

from orpheus_tts import OrpheusClient

client = OrpheusClient(provider="PROVIDER_NAME")  # Reads ORPHEUS_TTS_API_KEY if set
client.connect(websocket_count=1)

License

MIT