Metadata-Version: 2.4
Name: botnoi-voice-py
Version: 0.1.0
Summary: Python client for Botnoi Voice TTS API
License: MIT
Project-URL: Homepage, https://github.com/yourusername/botnoi-tts
Project-URL: Bug Tracker, https://github.com/yourusername/botnoi-tts/issues
Keywords: tts,text-to-speech,botnoi,thai,voice,audio
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# botnoi-tts

Python client for the [Botnoi Voice](https://voice.botnoi.ai/) Text-to-Speech API.

- ✅ Zero dependencies (stdlib only)
- ✅ Python 3.8+
- ✅ Type hints throughout
- ✅ Simple `.save()` helper to download audio

---

## Installation

```bash
pip install botnoi-tts
```

---

## Quick Start

```python
from botnoi_tts import BotnoiTTS

client = BotnoiTTS(token="YOUR_BOTNOI_TOKEN")

# Generate audio
response = client.generate(
    text="สวัสดีครับ",
    speaker="1",
    language="th",
)

print(response.audio_url)   # URL to the audio file
response.save("hello.mp3")  # download & save locally
```

---

## API Reference

### `BotnoiTTS(token, timeout=30)`

| Parameter | Type | Description |
|-----------|------|-------------|
| `token`   | `str` | Your Botnoi API token |
| `timeout` | `int` | Request timeout in seconds (default 30) |

---

### `client.generate(text, *, speaker, volume, speed, media_type, language, save_file)`

| Parameter    | Type    | Default | Description |
|--------------|---------|---------|-------------|
| `text`       | `str`   | —       | Text to synthesise |
| `speaker`    | `str`   | `"1"`   | Speaker ID |
| `volume`     | `float` | `1.0`   | 0.0 – 2.0 |
| `speed`      | `float` | `1.0`   | 0.5 – 2.0 |
| `media_type` | `str`   | `"mp3"` | `"mp3"`, `"wav"`, `"ogg"` |
| `language`   | `str`   | `"th"`  | `"th"` or `"en"` |
| `save_file`  | `bool`  | `True`  | Persist file on Botnoi servers |

Returns an **`AudioResponse`** object.

---

### `AudioResponse`

| Attribute    | Type   | Description |
|--------------|--------|-------------|
| `audio_url`  | `str`  | Direct URL to the generated audio |
| `media_type` | `str`  | Format of the audio file |
| `text`       | `str`  | Input text that was synthesised |
| `speaker`    | `str`  | Speaker ID used |
| `raw`        | `dict` | Full raw API response |

#### `.save(path) -> str`

Downloads the audio and saves it to `path`. Returns the absolute file path.

```python
response.save("output")        # saves as output.mp3
response.save("output.wav")    # saves as output.wav
```

---

## Aliases

```python
client.synthesize("สวัสดี")  # same as generate()
client.tts("สวัสดี")         # short alias
```

---

## Error Handling

```python
from botnoi_tts import BotnoiTTS, BotnoiAuthError, BotnoiAPIError

client = BotnoiTTS(token="...")

try:
    response = client.generate("สวัสดีครับ")
except BotnoiAuthError:
    print("Invalid token")
except BotnoiAPIError as e:
    print(f"API error {e.status_code}: {e}")
```

| Exception         | When raised |
|-------------------|-------------|
| `BotnoiAuthError` | Token is invalid or missing |
| `BotnoiAPIError`  | Non-200 HTTP response or connection error |

---

## License

MIT
