Metadata-Version: 2.4
Name: orpheus-tts
Version: 0.1.6
Summary: Python SDK for Orpheus TTS - stream high-quality speech
Project-URL: Homepage, https://canopylabs.ai
Project-URL: Documentation, https://docs.canopylabs.ai
Author: Canopy Labs
License-Expression: MIT
Keywords: audio,orpheus,speech,text-to-speech,tts
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# Orpheus TTS Python SDK

Stream high-quality speech from the Orpheus TTS model.

## Installation

```bash
pip install orpheus-tts
```

## Quick Start

```python
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

```python
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

```python
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

```python
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

```bash
export ORPHEUS_TTS_API_KEY="YOUR_API_KEY"
```

```python
from orpheus_tts import OrpheusClient

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

## License

MIT

