Metadata-Version: 2.4
Name: novaxvoice
Version: 0.1.0
Summary: Official NovaxVoice Text-to-Speech V2 SDK for Python (sync + async).
Project-URL: Homepage, https://novaxvoice.com
Project-URL: Documentation, https://docs.novaxvoice.com
Author: NovaxVoice
License: MIT
Keywords: ai,novaxvoice,speech-synthesis,text-to-speech,tts,voice
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.9
Requires-Dist: httpx<1.0,>=0.24
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# novaxvoice (Python)

Official **NovaxVoice Text-to-Speech V2** SDK for Python. Sync **and** async clients,
streaming, and save-to-file. Built on [httpx](https://www.python-httpx.org/).

Synthesizes **Krio** text and returns a WAV blob (16-bit mono PCM, 24 kHz).

## Install

```bash
pip install novaxvoice
```

Requires Python 3.9+.

## Quick start

```python
from novaxvoice import NovaxVoiceClient

client = NovaxVoiceClient()  # no API key required

wav = client.synthesize("Kushɛ, aw di bodi?")   # -> bytes (WAV)
with open("hello.wav", "wb") as f:
    f.write(wav)
```

## Synchronous client

```python
from novaxvoice import NovaxVoiceClient

with NovaxVoiceClient() as client:
    # One-shot
    wav = client.synthesize("Tɛnki ya.")

    # Streaming download
    for chunk in client.synthesize_stream("A de go na os."):
        ...

    # Straight to disk
    client.synthesize_to_file("out.wav", "A sev am na fail.")
```

## Asynchronous client

```python
import asyncio
from novaxvoice import AsyncNovaxVoiceClient

async def main():
    async with AsyncNovaxVoiceClient() as client:
        wav = await client.synthesize("Kushɛ from async.")
        async for chunk in client.synthesize_stream("streaming"):
            ...

asyncio.run(main())
```

## Forward-compatible parameters

The backend currently reads only `text`. Pass new fields as the backend gains support
(e.g. a voice or speed) via `extra_body` — no SDK upgrade needed:

```python
client.synthesize("...", extra_body={"speed": 1.2})
```

## Configuration

| Argument      | Default                                                       | Description                                  |
| ------------- | ------------------------------------------------------------ | -------------------------------------------- |
| `endpoint`    | `https://joshuamcoker--krio-tts-kriotts-generate.modal.run`  | Full TTS endpoint URL (POSTed to directly).  |
| `api_key`     | `NOVAXVOICE_API_KEY` env var                                 | Optional; sent as `Bearer` if set.           |
| `timeout`     | `120.0`                                                       | Per-request timeout, seconds (cold ~20s).    |
| `headers`     | `None`                                                       | Extra headers on every request.              |
| `http_client` | `None`                                                       | Bring your own `httpx.Client`.               |

## Error handling

All errors subclass `NovaxVoiceError`:

- `NovaxVoiceAPIError` — non-2xx (has `.status`, `.code`, `.body`). A missing `text` returns
  HTTP 400 with the plain-text message `missing 'text'`.
- `NovaxVoiceAuthError` — 401/403
- `NovaxVoiceRateLimitError` — 429 (has `.retry_after`)
- `NovaxVoiceTimeoutError` / `NovaxVoiceConnectionError` — network failures

## Development

```bash
pip install -e ".[dev]"
pytest          # httpx mocked, no network
mypy src
```

## License

MIT
