Metadata-Version: 2.4
Name: orpheus-tts
Version: 0.1.1
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()

# Stream audio chunks
for chunk in client.stream("Hello world!", voice="antoine"):
    # chunk is raw PCM bytes (int16, 48kHz, mono)
    process_audio(chunk)
```

## Usage

### Basic Streaming

```python
from orpheus_tts import OrpheusClient

client = OrpheusClient()

# Stream and save to file
with open("output.pcm", "wb") as f:
    for chunk in client.stream("Welcome to Orpheus TTS!", voice="antoine"):
        f.write(chunk)
```

### Save as WAV

```python
import wave
from orpheus_tts import OrpheusClient

client = OrpheusClient()

# Get complete audio
audio_data = client.stream_to_bytes("Hello, this is a test.", voice="antoine")

# Save as WAV file
with wave.open("output.wav", "wb") as wav:
    wav.setnchannels(1)        # mono
    wav.setsampwidth(2)        # 16-bit
    wav.setframerate(48000)    # 48kHz
    wav.writeframes(audio_data)
```

### Async Streaming

```python
import asyncio
from orpheus_tts import OrpheusClient

async def main():
    client = OrpheusClient()
    
    async for chunk in client.stream_async("Async streaming!", voice="antoine"):
        await process_audio_async(chunk)

asyncio.run(main())
```

### Real-time Playback with PyAudio

```python
import pyaudio
from orpheus_tts import OrpheusClient

client = OrpheusClient()

# Initialize PyAudio
p = pyaudio.PyAudio()
stream = p.open(
    format=pyaudio.paInt16,
    channels=1,
    rate=48000,
    output=True
)

# Stream and play
for chunk in client.stream("This plays in real-time!", voice="antoine"):
    stream.write(chunk)

stream.stop_stream()
stream.close()
p.terminate()
```

## Available Voices

```python
from orpheus_tts import VOICES

print(VOICES)
```

## Configuration

```python
client = OrpheusClient(
    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="antoine",
    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()

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

## License

MIT

