| # OpenThai2.0 ASR Streaming service: reference |
|
|
| Install, start and example calls: see the main [README](../README.md). |
|
|
| ## Endpoints |
|
|
| | endpoint | what it does | |
| |---|---| |
| | `POST /v1/transcribe` | multipart `file` + the fields below → JSON | |
| | `WS /v1/live` | a live stream of any length: JSON config → PCM16 LE 16 kHz mono frames → text `end`. Replies `partial` (the sentence so far) and one `final` each time the speaker pauses, then `done` | |
| | `WS /v1/stream` | one utterance: JSON config → frames → `end`; replies `partial`… then one `final` | |
| | `GET /v1/health` | loaded model and settings | |
|
|
| | field | values | default | |
| |---|---|---| |
| | `mode` | `standard` · `conversation` · `meeting` | `standard` | |
| | `lang` | `th-TH` · `th-mix` | `th-TH` | |
| | `latency_ms` | 80 · 320 · 560 · 1120 | 560 | |
| | `diarize` | `true` · `false` | on for `meeting` | |
| | `split` (files) | `auto` · `on` · `off` | `auto`: cut files longer than 30 s at pauses | |
| | `end_silence_ms` (`/v1/live`) | 300–3000 | 700 | |
|
|
| **Response fields:** |
| - `text` (raw, as scored) and `display_text` (for display). |
| - `duration_s`, `lang`, `latency_ms`, `mode`, `policy`, `delta`, `model`, `processing_s`. |
| - A file cut at pauses also has `segments` `[{start, end, text}]`, one per piece. |
| - With speaker labels, also `segments` `[{speaker, start, end, text}]` and `speakers`. |
|
|
| **Errors:** 400 empty file · 415 unreadable audio · 422 bad option. |
|
|
| ## What each mode does |
|
|
| The blank bias δ controls how readily the model writes something: the more negative it is, the fewer words get dropped. |
|
|
| | mode | decode | |
| |---|---| |
| | `standard` | δ −1.0; clips under 2 s re-decoded at −2.5; empty output re-decoded at −4.0 | |
| | `conversation` | δ −2.0; empty output re-decoded at −4.0 | |
| | `meeting` | δ −1.0 + speaker labels from `nvidia/Nemotron-3-Diarization` (downloaded on first use) | |
|
|
| ## Environment variables |
|
|
| | var | default | meaning | |
| |---|---|---| |
| | `CHINDA_DEVICE` | `cpu` | `cuda` for GPU | |
| | `CHINDA_MODEL` | `../openthai2.0-asr-streaming_raw.nemo` | must be the raw file; `*_bias-*` files are refused (the bias would apply twice) | |
| | `CHINDA_PRELOAD` | unset | `1` = load at start-up; otherwise the first request waits about 20 s | |
| | `CHINDA_REPLICAS` | `1` | model copies, about 2.6 GB each; each copy runs one decode step at a time | |
| | `CHINDA_NUM_THREADS` | min(16, CPUs); 1 on macOS | CPU threads. On Apple silicon each extra thread makes decoding slower, so macOS uses 1 | |
| | `CHINDA_DIAR_MODEL` | download | path to a local `Nemotron-3-Diarization.nemo` | |
| | `CHINDA_CUDA_GRAPHS` | `0` | leave at 0: `1` crashes on the request after speaker labels | |
| | `CHINDA_SPLIT_FROM_S` | `30` | `split=auto` cuts files longer than this many seconds | |
|
|
| ## Long audio |
|
|
| Do not decode a long recording as one stream. After a pause of near-silence this model drops some of the speech that follows: TVSpeech's videos, rebuilt by joining their clips with one second of silence, score 23.5% character errors as one stream and 12.7% cut at pauses (12.4% clip by clip). So: |
|
|
| - `POST /v1/transcribe` cuts any file longer than 30 s where nobody speaks for 0.7 s, and decodes the pieces on their own (`split=auto`). Speaker labels (`mode=meeting`) still decode one stream. |
| - `WS /v1/live` ends an utterance at each pause and starts the next one fresh, like iApp's hosted OpenThai ASR Realtime. |
| - `WS /v1/stream` decodes everything you send as one utterance; keep it for short commands and single sentences. |
| - In Python: `chinda_realtime.transcribe_long(asr, audio)` for recordings, `chinda_realtime.RealtimeSession` for live audio. |
|
|
| The pause detector is an energy rule (`chinda_realtime.Endpointer`): a 20 ms frame is speech when it is louder than both the loudest recent level − 30 dB and the quietest recent level + 8 dB. Stretches with no speech are skipped. |
|
|
| ## Good to know |
|
|
| - No authentication or rate limiting. |
| - With `diarize` on `/v1/stream`, speaker labels arrive with the `final` message only; `/v1/live` has no speaker labels. Speakers are anonymous (`speaker_0`, …). |
| - Live text equals decoding the finished utterance on its own. Batch decoding (the benchmark) can differ by the last word on clips under 2 s. |
| - With `ffmpeg` on the PATH, the API also accepts mp3, m4a and ogg. |
| - The decode loop is adapted from NVIDIA NeMo's `speech_to_text_cache_aware_streaming_infer.py` (Apache-2.0). |
|
|
