docs/live_s2s_runtime.md

# Live Urdu S2S Runtime

Use this once you want to run the real Urdu S2S service:

ASR audio -> Urdu reply -> Devanagari bridge -> Praxy/Chatterbox WAV

## Preflight

```bash
PYTHONPATH=src:scripts python3 scripts/s2s_live_preflight.py
```

The command checks:

- sample input WAV exists
- Praxy voice anchor exists
- `OPENAI_API_KEY` is present
- `faster-whisper`, `chatterbox-tts`, and `soundfile` are importable
- Python version is likely compatible

## Recommended Runtime

Use Python 3.10, 3.11, or 3.12 for the live ML audio environment. The current local `.venv` may be Python 3.14, which is likely to be brittle for these dependencies.

```bash
python3.11 -m venv .venv-live-s2s
source .venv-live-s2s/bin/activate
pip install -r requirements-live-s2s.txt
```

Then set the OpenAI key in the shell:

```bash
export OPENAI_API_KEY="..."
export OPENAI_MODEL="gpt-4o-mini"
```

## Full Local Smoke Command

```bash
PYTHONPATH=src:scripts python3 scripts/run_s2s_live.py \
  --audio-path data/raw/benchmarks/gemini_urdu_s2s_v1/audio/bench_001.wav \
  --asr-provider faster_whisper \
  --whisper-model large-v3 \
  --whisper-device cpu \
  --whisper-compute-type int8 \
  --tts-provider chatterbox_praxy \
  --tts-audio-path reports/evals/s2s_live_bench_001_praxy.wav \
  --output-json reports/evals/s2s_live_bench_001.json
```

For a CUDA GPU box, use:

```bash
  --whisper-device cuda \
  --whisper-compute-type float16 \
  --chatterbox-device cuda
```

## API Live TTS Mode

Start the API:

```bash
PYTHONPATH=src:scripts python3 scripts/serve_s2s_api.py --host 0.0.0.0 --port 8017
```

Generate a live Praxy/Chatterbox response WAV:

```bash
curl -X POST "http://127.0.0.1:8017/s2s?mode=live_tts&request_id=live_bench_001&prompt_roman_urdu=Assalam%20o%20alaikum&whisper_device=cuda&whisper_compute_type=float16&chatterbox_device=cuda" \
  -F "audio=@data/processed/benchmarks/gemini_urdu_s2s_v1/audio_canonical/bench_001.wav"
```

The generated WAV is saved under `artifacts/api_tts_outputs/{request_id}.wav` and is served from `/s2s/{request_id}/audio`.

## Current Local Blockers

If preflight reports missing dependencies or Python 3.14, use a Python 3.11/3.12 runtime or run the same command on the GPU box.