docs/API.md

# Python API

## Load once

```python
from inference import InflectTTS

tts = InflectTTS(model_dir=".", device="cpu")
```

`model_dir` must contain `model.pth`, `config.json`, the public frontend, and
`runtime/`. `device` accepts a PyTorch device string such as `cpu`, `cuda`, or
`cuda:0`. Loading validates the release architecture and raises
`FileNotFoundError` for missing artifacts or `RuntimeError` for an incompatible
checkpoint.

Keep one engine alive for repeated requests. Constructing an engine reloads the
checkpoint and should not happen per utterance.

## `synthesize`

```python
sample_rate, waveform = tts.synthesize(
    "A compact model can still speak clearly.",
    speed=1.0,
    variation=0.667,
    seed=7,
)
```

Signature:

```python
synthesize(text, *, speed=1.0, variation=0.667, seed=0)
```

Returns `(sample_rate, waveform)`:

- `sample_rate`: integer `24000`, in samples per second.
- `waveform`: one-dimensional, mono `numpy.ndarray` with `float32` samples
  clipped to `[-1.0, 1.0]`.

Validation:

- empty or whitespace-only text raises `ValueError`;
- `speed` must be in `0.5–2.0`;
- `variation` must be in `0.0–1.0`;
- `seed` is converted to an integer.

`seed` repeats the same stochastic sample on the same model/runtime stack.
Cross-version or cross-device bit identity is not guaranteed.

## `save`

```python
output = tts.save(
    "This is written directly to disk.",
    "outputs/out.wav",
    seed=7,
)
```

`save(text, output, **synthesis_options)` creates parent directories, writes a
mono 24 kHz PCM WAV, and returns the output `Path`.

## Long text

Long input is normalized, split first at sentence punctuation and then at safe
intra-sentence boundaries. Each chunk is generated independently with
`seed + chunk_index`, edge-faded, and joined with punctuation-dependent silence.
This bounds memory, but it is not one globally planned long-form prosody pass.

## Concurrency

One `InflectTTS` instance mutates random-number state during synthesis. Serialize
requests to one instance. For concurrent serving, use a worker pool with one
engine per worker/device and enforce an application-level queue.

## CLI

```bash
python inference.py \
  --model-dir . \
  --device cpu \
  --text "Inflect is running locally." \
  --output out.wav \
  --speed 1.0 \
  --variation 0.667 \
  --seed 7
```

Run `python inference.py --help` for the authoritative flag list.

## Deliberate omissions

The v2 API does not expose speaker cloning, streaming state, SSML, native pitch
control, or language switching. Pitch-shifting generated audio is
post-processing and is not part of the model contract.