Speech-to-Text (Realtime) - Gnani AI Documentation

Overview

Stream raw PCM audio frames and receive transcript segments as speech is detected. The server uses Voice Activity Detection (VAD) to identify speech boundaries and returns a transcript for each segment.

Use case	Recommended endpoint
Live microphone / phone call / real-time audio	This endpoint
Short pre-recorded clips ≤ 60 s	STT REST
Large files or bulk jobs	STT Batch

Endpoint

WSS wss://api.vachana.ai/stt/v3/stream

Connection Headers

All configuration is passed as WebSocket upgrade headers at connection time. Most headers are fixed for the life of the connection — reconnect with new headers to change them. The exceptions are x-enable-substitution, x-substitution-map, and the word-boosting headers (x-bias-list, x-bias-score), which can also be updated mid-session via update_settings control frames.

Header	Required	Default	Description
`x-api-key-id`	Yes	—	Your Gnani API key.
`lang_code`	Yes	`en-IN`	BCP-47 language code for transcription. See Supported Languages.
`x-sample-rate`	No	`16000`	Sample rate of the audio stream in Hz. Accepted values: `8000`, `16000`, `44100`, `48000`. Must match the actual sample rate of your audio source.
`x-format`	No	`verbatim`	`verbatim` — raw spoken-form output. `transcribe` — enables Inverse Text Normalization (ITN). See ITN.
`itn_native_numerals`	No	`false`	When `x-format=transcribe`, set `true` to render digits in the native script of the target language (e.g. `₹५,०००` instead of `₹5,000` for Hindi).
`x-enable-substitution`	No	`false`	Set to `true` to enable post-transcription find-and-replace. All patterns in `x-substitution-map` are applied to each transcript segment after ITN. Can be toggled mid-session via `update_settings`.
`x-substitution-map`	No	—	JSON-encoded list of substitution rules (same format as the REST `substitution_map` field). Only evaluated when `x-enable-substitution=true`. Maximum 10 rules. Can be replaced mid-session via `update_settings`. See Find-and-Replace below.
`x-bias-list`	No	—	Words to boost during recognition (word boosting). JSON array or comma-separated; up to 100 single words, letters only. Requires `x-bias-score`. Can be replaced mid-session via `update_settings`. See Word Boosting.
`x-bias-score`	No	—	Boost strength: `0.0`, `0.5`, `1.0`, `1.5` or `2.0`. `0.0` or omitted disables boosting.

Choosing the right sample rate:

Value	When to use
`48000`	Browser `getUserMedia` default; Mac microphone
`44100`	Mac microphone alternate; CD-quality audio
`16000`	Wideband telephony; sent as-is with no resampling
`8000`	Narrowband telephony (legacy PSTN / VoIP)

VAD tuning headers

These five optional headers control where speech starts and stops. Defaults are tuned for a clean wideband microphone — override them for telephony, noisy environments, or latency-sensitive flows. See VAD Tuning for guidance and ready-made presets.

Header	Required	Default	Range	Description
`x-vad-threshold`	No	`0.7`	`0.0`–`1.0`	Speech-probability threshold. Clean mic: `0.45`–`0.55`. Telephony: `0.65`–`0.75`.
`x-min-silence-ms`	No	`500`	`100`–`2000`	Silence required to close a segment. Telephony: `400`–`600`. Conversation: `600`–`900`.
`x-min-speech-ms`	No	`100` (`200` at 8 kHz)	`50`–`2000`	Speech required to open a segment. Raise in noisy environments.
`x-min-segment-ms`	No	`120`	`100`–`1000`	Floor on the speech needed to confirm a segment. Raise to `200`–`300` to suppress stray sounds.
`x-max-speech-s`	No	disabled	`5.0`–`120.0`	Hard cap on a single segment. Set (e.g. `30`) to force transcripts on monologues.

Voice Activity Detection (VAD) Tuning

VAD is what turns a continuous audio stream into discrete utterances. It listens for the moment speech starts, holds the segment open through natural pauses, and closes it when the speaker stops. Every closed segment becomes exactly one transcript message — so VAD settings directly control both how your transcripts are chunked and how quickly they arrive.

VAD headers are fixed for the life of the connection. To change them, close the WebSocket and reconnect with the new values.

The two knobs that matter most

Most tuning comes down to two trade-offs:

Goal	Change	Trade-off
Faster transcripts	Lower `x-min-silence-ms`	A sentence may split at a natural pause
More complete sentences	Raise `x-min-silence-ms`	Every transcript arrives later
Fewer false triggers (noise, keyboard, hold music)	Raise `x-vad-threshold` and `x-min-speech-ms`	Soft or distant speech may be missed
Catch quiet speakers	Lower `x-vad-threshold`	Background noise may open segments

Header reference

`x-vad-threshold`

How confident the model must be that a frame contains speech. Type float, default 0.7, range 0.0–1.0.

Higher (0.75+) — stricter. Rejects background noise, hold music, and line hiss, but may miss soft or distant speech.
Lower (0.45–0.55) — more sensitive. Catches quiet speakers and whispers, but noise is more likely to open a segment.

Environment	Suggested value
Clean headset or studio mic	`0.45`–`0.55`
Open office / laptop mic	`0.6`–`0.7`
Telephony, call centre, noisy line	`0.65`–`0.75`

`x-min-silence-ms`

How much silence must follow speech before the segment is closed and transcribed. Type integer, default 500, range 100–2000. This is the single biggest lever on end-of-utterance latency — the transcript cannot arrive until this timer expires.

Lower (300–400) — snappier results. Best for IVR prompts and short commands, but a speaker who pauses mid-sentence (“my number is… 98765…”) will get two transcripts instead of one.
Higher (700–900) — more complete utterances. Best for natural conversation and dictation, at the cost of ~half a second of extra latency per turn.

Use case	Suggested value
IVR / short commands / yes-no answers	`300`–`400`
Telephony conversation	`400`–`600`
Natural conversation, dictation, meetings	`600`–`900`

`x-min-speech-ms`

How much consecutive speech is needed before a segment is opened. Type integer, default 100 (200 when x-sample-rate: 8000), range 50–2000. Acts as a noise gate at the start of speech. A door slam, a click, or a cough is shorter than this window, so it never opens a segment and never costs you a transcription.

Raise (200–300) in noisy environments or on noisy telephony lines.
Lower (50–80) only if you are losing very short interjections like “haan” or “yes”.

`x-min-segment-ms`

A floor on the amount of speech required to confirm a segment. Type integer, default 120, range 100–1000. This works together with x-min-speech-ms — whichever demands more speech wins. Because it applies at the start of a segment, audio below this threshold never opens a segment at all, so no transcript message is produced for it.

Raise to 200–300 to suppress residual coughs, breaths, and line pops that survive the x-min-speech-ms gate.
Leave at the default (or lower toward 100) if you expect genuine one-word answers like “yes”, “नहीं”, or “two”.

Raising x-min-segment-ms too far silently drops short answers — they produce no transcript message at all. If users report that “yes”/“no” responses never come back, this header is the first thing to check.

`x-max-speech-s`

Hard cap on how long a single segment can run. Type float, disabled by default, range 5.0–120.0. Normally a segment closes when the speaker pauses. If someone talks continuously — reading an address, giving a monologue — that pause may never come, and you get no transcript until they stop. Setting this header force-closes and transcribes the segment at the cap so results keep flowing.

Leave unset for normal turn-taking conversation.
Set to 20–30 for monologue-heavy audio (voicemail, dictation, long narration) to get steady intermediate results.

The overall session is always capped at 15 minutes regardless of this setting. x-max-speech-s bounds a single uninterrupted segment within that session.

Presets

Copy-paste starting points. Tune from here rather than from scratch.

x-api-key-id:      <your-api-key>
lang_code:         en-IN
x-sample-rate:     48000
x-vad-threshold:   0.5
x-min-silence-ms:  700

x-api-key-id:      <your-api-key>
lang_code:         hi-IN
x-sample-rate:     8000
x-vad-threshold:   0.7
x-min-speech-ms:   200
x-min-silence-ms:  500

x-api-key-id:      <your-api-key>
lang_code:         en-IN
x-sample-rate:     8000
x-min-silence-ms:  300
x-min-speech-ms:   100
x-min-segment-ms:  100

x-api-key-id:      <your-api-key>
lang_code:         en-IN
x-sample-rate:     16000
x-min-silence-ms:  800
x-max-speech-s:    30

Setting VAD headers in code

VAD headers are sent at connection time, alongside your API key.

import websockets

headers = {
    "x-api-key-id":     "your-api-key",
    "lang_code":        "hi-IN",
    "x-sample-rate":    "8000",
    "x-vad-threshold":  "0.7",
    "x-min-speech-ms":  "200",
    "x-min-silence-ms": "500",
}

async with websockets.connect(
    "wss://api.vachana.ai/stt/v3/stream",
    additional_headers=headers,   # `extra_headers` on websockets < 13
) as ws:
    ...

import WebSocket from "ws";

const ws = new WebSocket("wss://api.vachana.ai/stt/v3/stream", {
  headers: {
    "x-api-key-id": "your-api-key",
    "lang_code": "hi-IN",
    "x-sample-rate": "8000",
    "x-vad-threshold": "0.7",
    "x-min-speech-ms": "200",
    "x-min-silence-ms": "500",
  },
});

Browser WebSocket cannot set custom headers. From a browser, proxy the connection through your own backend and attach the headers there — this also keeps your API key off the client.

The Python SDK (gnani-vachana) does not currently expose VAD tuning. Use a raw WebSocket client, as above, if you need these headers.

Connection Flow

A WebSocket session follows a strict sequence:

Client connects — opens a WebSocket to /stt/v3/stream with all required headers.
Server confirms — immediately sends a connected message echoing the active configuration.
Client streams audio — continuously sends binary frames of raw PCM audio at a steady real-time cadence.
Server detects speech — VAD identifies end-of-speech boundaries and emits a processing message to acknowledge that a segment was captured.
Server returns transcript — sends a transcript message with the transcribed text, segment metadata, and latency.
Either side closes — client or server may close the connection at any time.

The processing message is a low-latency signal that audio was captured and transcription has begun. Expect a transcript message shortly after.

Audio Format & Sending Audio

All audio must be sent as raw PCM binary frames over the WebSocket. No container format (WAV, MP3, etc.) is accepted mid-stream.

PCM Specification

Property	16 kHz	8 kHz
Encoding	PCM signed 16-bit little-endian	PCM signed 16-bit little-endian
Sample Rate	16,000 Hz	8,000 Hz
Channels	1 (mono)	1 (mono)
Samples per chunk	512	512
Bytes per frame	1,024 bytes (512 samples × 2 bytes)	1,024 bytes (512 samples × 2 bytes)
Frame duration	32 ms	64 ms

Sending Rules

Each binary frame must be exactly 1,024 bytes.
Frames must be sent at real-time cadence — one frame every 32 ms (16 kHz) or 64 ms (8 kHz). Do not buffer and burst; this degrades VAD accuracy.
For 44100 and 48000 Hz sources, the server resamples internally — still send 1,024-byte frames at the appropriate cadence.

Server Messages

The server sends JSON text frames. All messages share a type discriminator field and an ISO-8601 timestamp.

`connected`

Sent once immediately after the WebSocket handshake succeeds.

{
  "type": "connected",
  "message": "STT service ready — VAD service connected",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "config": {
    "sample_rate": 16000,
    "chunk_size": 512
  }
}

Field	Type	Description
`type`	`string`	Always `"connected"`.
`message`	`string`	Human-readable status string.
`timestamp`	`string`	ISO-8601 server timestamp.
`config.sample_rate`	`integer`	Active sample rate in Hz, echoed from `x-sample-rate`.
`config.chunk_size`	`integer`	Expected chunk size in samples (always 512).

`processing`

Emitted when VAD detects the end of a speech segment and transcription has begun. Use this as a low-latency acknowledgment that audio was captured.

{
  "type": "processing",
  "timestamp": "2024-01-15T10:30:05.123Z"
}

Field	Type	Description
`type`	`string`	Always `"processing"`.
`timestamp`	`string`	ISO-8601 timestamp when speech-end was detected.

`transcript`

Contains the transcribed text for a completed speech segment.

{
  "type": "transcript",
  "timestamp": "2024-01-15T10:30:05.987Z",
  "text": "Hello, how are you today?",
  "audio_duration_ms": 2340,
  "segment_id": "<segment_id>",
  "segment_index": 0,
  "latency": 320
}

Field	Type	Description
`type`	`string`	Always `"transcript"`.
`timestamp`	`string`	ISO-8601 timestamp when the transcript was emitted.
`text`	`string`	Transcribed text. Format depends on the `x-format` header.
`audio_duration_ms`	`integer`	Duration of the captured speech segment in milliseconds.
`segment_id`	`string`	Unique identifier for this speech segment. Use for deduplication or support correlation.
`segment_index`	`integer`	Sequential index of this segment within the session, starting at `0`.
`latency`	`integer`	Time in milliseconds from end-of-speech detection to transcript delivery.

`error`

Sent when the server encounters a recoverable or fatal error. The connection may remain open after a recoverable error.

Field	Type	Description
`type`	`string`	Always `"error"`.
`timestamp`	`string`	ISO-8601 timestamp of the error.
`message`	`string`	Human-readable description of the error.

{
  "type": "error",
  "timestamp": "2024-01-15T10:30:10.000Z",
  "message": "STT engine failed to initialize"
}

`settings_updated`

Sent in response to a successful update_settings control frame. Echoes the full active configuration after the update.

{
  "type": "settings_updated",
  "timestamp": "2024-01-15T10:31:00.000Z",
  "config": {
    "language_code": "en-IN",
    "format": "verbatim",
    "itn_native_numerals": false,
    "substitution_enabled": true,
    "bias_word_count": 2,
    "bias_score": 1.5
  }
}

Field	Type	Description
`type`	`string`	Always `"settings_updated"`.
`timestamp`	`string`	ISO-8601 timestamp of the update.
`config.language_code`	`string`	Active language code.
`config.format`	`string`	Active format (`verbatim` or `transcribe`).
`config.itn_native_numerals`	`boolean`	Whether native numeral rendering is on.
`config.substitution_enabled`	`boolean`	Whether find-and-replace is currently active.
`config.bias_word_count`	`integer`	Number of words currently boosted (`0` when word boosting is off).
`config.bias_score`	`number`	Active boost strength.

Client Control Frames

Alongside binary PCM audio frames, the client can send JSON text frames to update settings mid-session. No reconnect needed.

`update_settings`

Send a JSON text frame with "type": "update_settings" and the settings you want to change. Unspecified fields keep their current values.

{"type": "update_settings", "substitution": {"enabled": true, "map": [{"patterns": ["ok", "okay"], "replacement": "acknowledged"}]}}

Substitution key

Key	Type	Description
`substitution.enabled`	`boolean`	Toggle find-and-replace on or off for subsequent segments.
`substitution.map`	`array`	Replace the full rule set. Uses the same format as `x-substitution-map`. Ignored when `enabled` is `false`.

You can send enabled and map together or separately:

// Turn on with a new rule set
{"type": "update_settings", "substitution": {"enabled": true, "map": [{"patterns": ["hello", "hi"], "replacement": "greetings"}]}}

// Turn off without changing the stored rule set
{"type": "update_settings", "substitution": {"enabled": false}}

// Swap the rule set while already on
{"type": "update_settings", "substitution": {"map": [{"patterns": ["bye", "goodbye"], "replacement": "farewell"}]}}

Bias key

Key	Type	Description
`bias.list`	`array` \| `string`	Replace the boosted words (JSON array or comma-separated string). `[]` or `null` turns word boosting off.
`bias.score`	`number`	New boost strength: `0.0`, `0.5`, `1.0`, `1.5` or `2.0`.

Omit a key to keep its current value — for example {"bias": {"score": 2.0}} changes only the strength.

{"type": "update_settings", "bias": {"list": ["Vachana", "EMI"], "score": 1.5}}

The change applies from the next speech segment. An invalid update is ignored as a whole and the previous settings stay in effect. The server replies with a settings_updated frame confirming the new state.

Python SDK

The official Python SDK wraps the WebSocket connection, audio pacing, and event parsing into a clean async interface.

Installation

pip install gnani-vachana

Requires Python 3.10+.

Authentication

The streaming client requires your API key and language code.

from gnani.stt import GnaniSTTStreamClient

stream = GnaniSTTStreamClient(
    api_key="your-api-key",
    language_code="hi-IN",
)

export GNANI_API_KEY="your-api-key"

from gnani.stt import GnaniSTTStreamClient

# Picks up GNANI_API_KEY from environment automatically
stream = GnaniSTTStreamClient(language_code="hi-IN")

Stream Audio from a File

Use the async context manager and the stream_audio helper. It handles real-time pacing automatically so frames are sent at the correct cadence for VAD.

import asyncio
from gnani.stt import GnaniSTTStreamClient

async def main():
    async with GnaniSTTStreamClient(
        api_key="your-api-key",
        language_code="hi-IN",
        sample_rate=16000,
    ) as stream:
        with open("audio.pcm", "rb") as f:
            transcripts = await stream.stream_audio(
                f,
                on_transcript=lambda t: print(f"Transcript: {t.text}"),
                on_processing=lambda p: print("Processing..."),
                realtime_pace=True,  # sends frames at real-time cadence
            )

    print(f"Total segments: {len(transcripts)}")

asyncio.run(main())

Iterate Over Events Manually

For lower-level control — handling each event type differently or interleaving sending and receiving — iterate over the stream directly.

import asyncio
from gnani.stt import GnaniSTTStreamClient, StreamTranscriptEvent, StreamProcessingEvent

async def main():
    async with GnaniSTTStreamClient(
        api_key="your-api-key",
        language_code="hi-IN",
    ) as stream:
        with open("audio.pcm", "rb") as f:
            while chunk := f.read(1024):
                await stream.send_audio(chunk)
                await asyncio.sleep(0.032)  # 32 ms per frame at 16 kHz

        async for event in stream:
            if isinstance(event, StreamTranscriptEvent):
                print(f"[Segment {event.segment_index}] {event.text}")
                print(f"  Duration: {event.audio_duration_ms} ms  Latency: {event.latency} ms")
            elif isinstance(event, StreamProcessingEvent):
                print("Processing speech...")

asyncio.run(main())

Using 8 kHz Audio (Telephony)

stream = GnaniSTTStreamClient(
    api_key="your-api-key",
    language_code="en-IN",
    sample_rate=8000,
)

SDK Event Types

All events are typed dataclasses with a raw field containing the full server JSON.

Event class	Key fields	Description
`StreamConnectedEvent`	`message`, `sample_rate`, `chunk_size`	Sent once after the WebSocket handshake. Confirms the active config.
`StreamProcessingEvent`	`timestamp`	VAD detected end-of-speech; transcription has started.
`StreamTranscriptEvent`	`text`, `segment_index`, `audio_duration_ms`, `latency`	Completed transcript for a speech segment.
`StreamErrorEvent`	`message`, `timestamp`	Server-side error, recoverable or fatal.

Error Handling

from gnani.stt import (
    StreamConnectionError,  # Could not establish the WebSocket connection
    StreamClosedError,      # Attempted to send on an already-closed stream
    StreamError,            # Server returned an error message mid-session
)

try:
    async with GnaniSTTStreamClient(api_key="your-api-key") as stream:
        await stream.send_audio(chunk)
except StreamConnectionError as e:
    print(f"Could not connect: {e}")
except StreamClosedError as e:
    print(f"Stream was already closed: {e}")
except StreamError as e:
    print(f"Server error: {e.message} (at {e.timestamp})")

Supported Languages

Language	Code	Native Script	Example
Bengali	`bn-IN`	Bengali (বাংলা)	“আমি ভাত খাই”
English	`en-IN`		“I am going to the market”
Gujarati	`gu-IN`	Gujarati (ગુજરાતી)	“હું બજાર જાઉં છું”
Hindi	`hi-IN`	Devanagari (हिन्दी)	“मैं बाज़ार जा रहा हूँ”
Kannada	`kn-IN`	Kannada (ಕನ್ನಡ)	“ನಾನು ಮಾರುಕಟ್ಟೆಗೆ ಹೋಗುತ್ತೇನೆ”
Malayalam	`ml-IN`	Malayalam (മലയാളം)	“ഞാൻ ചന്തയിലേക്ക് പോകുന്നു”
Marathi	`mr-IN`	Devanagari (मराठी)	“मी बाजारात जातोय”
Punjabi	`pa-IN`	Gurmukhi (ਪੰਜਾਬੀ)	“ਮੈਂ ਬਾਜ਼ਾਰ ਜਾ ਰਿਹਾ ਹਾਂ”
Tamil	`ta-IN`	Tamil (தமிழ்)	“நான் சந்தைக்கு செல்கிறேன்”
Telugu	`te-IN`	Telugu (తెలుగు)	“నేను మార్కెట్‌కి వెళ్తున్నాను”

Inverse Text Normalization (ITN)

When x-format: transcribe is set, ITN runs on every transcript segment immediately after recognition — converting spoken-form numbers, currency, dates, times, and phone numbers into the compact written form a reader expects.

What ITN Normalizes

1 — Cardinal & Ordinal Numbers

Spoken input (ASR)	Written output (ITN)	Rule
दो हज़ार	2,000	Indian comma grouping
पाँच लाख बीस हज़ार	5,20,000	Lakh-scale grouping
five lakh	5,00,000	English lakh convention
पहला / twenty first	1st / 21st	Ordinal suffix

2 — Currency & Money

Spoken input (ASR)	Written output (ITN)	Rule
पाँच सौ रुपये	₹500	₹ + amount
तीन रुपये पचास पैसे	₹3.50	₹ + rupees.paise
I need five thousand rupees	₹5,000	English India pipeline
pay do lakh rupees	₹2,00,000	Code-mixed en/hi

3 — Dates

Spoken input (ASR)	Written output (ITN)	Rule
बीस जनवरी दो हज़ार पच्चीस	20 जनवरी 2025	DD Month YYYY (hi)
fifteenth january twenty twenty five	15th January 2025	Ordinal Month YYYY (en)

4 — Times

Indian time-of-day words (सुबह, दोपहर, शाम, रात) automatically map to 24-hour HH:MM output.

Spoken input (ASR)	Written output (ITN)	Rule
सुबह पाँच बजे	सुबह 05:00	सुबह = AM
शाम पाँच बजे	शाम 17:00	शाम = evening (16–20 h)
रात के दस बजे	रात 22:00	रात = night (20–24 h)
meeting at five fifteen in the evening	meeting 17:15 in the evening	en — 24-hour

5 — Phone Numbers & PIN Codes

Spoken input (ASR)	Written output (ITN)	Rule
नौ आठ सात छह पाँच चार तीन दो एक शून्य	9876543210	10 digits → phone
एक एक शून्य शून्य शून्य एक	110001	6 digits → PIN
one two three four five six	123456	English digit words

6 — Mixed & Code-Mixed Utterances

Spoken input (ASR)	Written output (ITN)
कल थ्री फिफ्टी पीएम को पाँच सौ रुपये transfer करना है	कल 15:50 को ₹500 transfer करना है
pay do lakh rupees by fifteenth march	pay ₹2,00,000 by 15th March

Native Script Digits — `itn_native_numerals`

By default, ITN outputs Western Arabic digits (0–9). Set itn_native_numerals: true in the connection headers to render digits in the native script of the target language.

Language	Spoken input	`false` (default)	`true` — native script
Hindi `hi-IN`	पाँच हज़ार रुपये	₹5,000	₹५,०००
English `en-IN`	five thousand rupees	₹5,000	₹5,000 (Latin — no change)

What ITN Does Not Change

ITN intentionally preserves idiomatic and ambiguous phrases to avoid incorrect normalization.

दो तीन (meaning a few) stays as text, not 2 or 3
कर दो / ले दो (imperative verbs) are kept as words, not treated as cardinal 2

Find-and-Replace (Substitution)

After transcription (and after ITN, if enabled), the server can apply a custom set of find-and-replace rules to every transcript segment before delivering it to your client. Use this to:

Normalise domain-specific terms (“rs” → “INR”, “ok” → “acknowledged”)
Replace competitor names, internal codes, or product shortforms
Standardise phrases the model transcribes differently from your expected output

Enable at connection time

Pass x-enable-substitution: true and your rules in x-substitution-map as part of the WebSocket upgrade headers.

x-api-key-id:          <your-api-key>
lang_code:             en-IN
x-enable-substitution: true
x-substitution-map:    [{"patterns":["okay","ok"],"replacement":"acknowledged"},{"patterns":["rupees","rs"],"replacement":"INR"}]

import websockets, json

rules = json.dumps([
    {"patterns": ["okay", "ok", "alright"], "replacement": "acknowledged"},
    {"patterns": ["rupees", "rs"],           "replacement": "INR"},
])

headers = {
    "x-api-key-id":          "your-api-key",
    "lang_code":             "en-IN",
    "x-enable-substitution": "true",
    "x-substitution-map":    rules,
}

async with websockets.connect(
    "wss://api.vachana.ai/stt/v3/stream",
    additional_headers=headers,
) as ws:
    ...

import WebSocket from "ws";

const rules = JSON.stringify([
  { patterns: ["okay", "ok"], replacement: "acknowledged" },
  { patterns: ["rupees", "rs"], replacement: "INR" },
]);

const ws = new WebSocket("wss://api.vachana.ai/stt/v3/stream", {
  headers: {
    "x-api-key-id":          "your-api-key",
    "lang_code":             "en-IN",
    "x-enable-substitution": "true",
    "x-substitution-map":    rules,
  },
});

Toggle mid-session

Send an update_settings control frame at any time to turn substitution on/off or swap the rule set — no reconnect needed.

{"type": "update_settings", "substitution": {"enabled": true, "map": [{"patterns": ["hello", "hi"], "replacement": "greetings"}]}}

See Client Control Frames for the full reference.

Rule format

[
  {"patterns": ["find1", "find2"], "replacement": "replacement1"},
  {"patterns": ["find3"],          "replacement": "replacement2"}
]

Maximum 10 rules per session.
Matching is case-insensitive and respects Unicode word boundaries — "ok" matches "OK" but not "okay".
Longer phrases take priority — "New Delhi" is tried before "Delhi".
Rules are applied in a single pass with no cascading.

Substitution runs on the final client-visible transcript only. Billing records always carry the original raw transcript.

Word Boosting

Word boosting nudges the recognizer toward specific words — brand names, product names, domain terms — so they are more likely to be transcribed correctly. It affects recognition itself and is separate from find-and-replace.

Enable at connection time

Send x-bias-list and x-bias-score in the WebSocket upgrade headers. Both are needed for boosting to take effect.

x-api-key-id:  <your-api-key>
lang_code:     hi-IN
x-format:      verbatim
x-bias-list:   ["Prisma","EMI"]
x-bias-score:  1.0

import websockets, json

headers = {
    "x-api-key-id": "your-api-key",
    "lang_code":    "hi-IN",
    "x-format":     "verbatim",
    "x-bias-list":  json.dumps(["Prisma", "EMI"]),
    "x-bias-score": "1.0",
}

async with websockets.connect(
    "wss://api.vachana.ai/stt/v3/stream",
    additional_headers=headers,
) as ws:
    ...

import WebSocket from "ws";

const ws = new WebSocket("wss://api.vachana.ai/stt/v3/stream", {
  headers: {
    "x-api-key-id": "your-api-key",
    "lang_code": "hi-IN",
    "x-format": "verbatim",
    "x-bias-list": JSON.stringify(["Prisma", "EMI"]),
    "x-bias-score": "1.0",
  },
});

The list and score apply to every transcript segment in the session. If x-partials is on, they also apply to partial_transcript results.

Change it mid-session

Send an update_settings frame to replace the words or strength without reconnecting — see Client Control Frames.

{"type": "update_settings", "bias": {"list": ["Vachana", "EMI"], "score": 1.5}}

Rules


Words	Up to 100; each a single word of letters only (English or supported Indian scripts). No spaces, digits, punctuation, or symbols. Casing doesn’t matter.
Score	`0.0`, `0.5`, `1.0`, `1.5`, `2.0`. Start at `1.0`. `0.0` or omitted = off.
Format	Use `x-format: verbatim`; boost words are spoken-form tokens.
Languages	Works with a specific `lang_code` (e.g. `hi-IN`, `en-IN`) on the default model.

Invalid word-boosting input never rejects the connection or returns an error. If any entry breaks the rules, or the score is not an allowed value, boosting is skipped and audio is transcribed normally. Mid-session, an invalid update_settings is ignored and the previous list stays active.

Indic words in a header

HTTP headers are bytes, and many WebSocket clients refuse or garble non-ASCII values. The portable way is a JSON array with \u escapes, which is plain ASCII:

x-bias-list: ["\u0928\u092e\u0938\u094d\u0924\u0947","Vachana"]

Raw UTF-8 header bytes are also accepted if your client can send them.

Word boosting is also supported on /stt/v4/stream via the same headers, but that route has no update_settings channel for changing it mid-session.

​Overview

​Endpoint

​Connection Headers

​VAD tuning headers

​Voice Activity Detection (VAD) Tuning

​The two knobs that matter most

​Header reference

​x-vad-threshold

​x-min-silence-ms

​x-min-speech-ms

​x-min-segment-ms

​x-max-speech-s

​Presets

​Setting VAD headers in code

​Connection Flow

​Audio Format & Sending Audio

​PCM Specification

​Sending Rules

​Server Messages

​connected

​processing

​transcript

​error

​settings_updated

​Client Control Frames

​update_settings

​Substitution key

​Bias key

​Python SDK

​Installation

​Authentication

​Stream Audio from a File

​Iterate Over Events Manually

​Using 8 kHz Audio (Telephony)

​SDK Event Types

​Error Handling

​Supported Languages

​Inverse Text Normalization (ITN)

​What ITN Normalizes

​1 — Cardinal & Ordinal Numbers

​2 — Currency & Money

​3 — Dates

​4 — Times

​5 — Phone Numbers & PIN Codes

​6 — Mixed & Code-Mixed Utterances

​Native Script Digits — itn_native_numerals

​What ITN Does Not Change

​Find-and-Replace (Substitution)

​Enable at connection time

​Toggle mid-session

​Rule format

​Word Boosting

​Enable at connection time

​Change it mid-session

​Rules

​Indic words in a header

Overview

Endpoint

Connection Headers

VAD tuning headers

Voice Activity Detection (VAD) Tuning

The two knobs that matter most

Header reference

`x-vad-threshold`

`x-min-silence-ms`

`x-min-speech-ms`

`x-min-segment-ms`

`x-max-speech-s`

Presets

Setting VAD headers in code

Connection Flow

Audio Format & Sending Audio

PCM Specification

Sending Rules

Server Messages

`connected`

`processing`

`transcript`

`error`

`settings_updated`

Client Control Frames

`update_settings`

Substitution key

Bias key

Python SDK

Installation

Authentication

Stream Audio from a File

Iterate Over Events Manually

Using 8 kHz Audio (Telephony)

SDK Event Types

Error Handling

Supported Languages

Inverse Text Normalization (ITN)

What ITN Normalizes

1 — Cardinal & Ordinal Numbers

2 — Currency & Money

3 — Dates

4 — Times

5 — Phone Numbers & PIN Codes

6 — Mixed & Code-Mixed Utterances

Native Script Digits — `itn_native_numerals`

What ITN Does Not Change

Find-and-Replace (Substitution)

Enable at connection time

Toggle mid-session

Rule format

Word Boosting

Enable at connection time

Change it mid-session

Rules

Indic words in a header