API Reference

Speech To Text · WebSocket · Streaming

WSSwss://stream.shabd.tech/v1/streaming-speech-to-text

Connection headers

x-api-keystringrequired
API key for authentication.

Message flow

Outgoing Message (↑): The client sends metadata first then continuously sends audio data in bytes.
Incoming Message (↓): The server responds json with requestId, status, transcript, chunk, completed, mode, stage.

Send Metadata (↑):

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "language": "tamil",  "sampleRate": 16000}

Send Audio Data (↑):

  Raw PCM 16-bit Audio Data (in Bytes)

Initial messageapplication/json

requestIdstringrequired
Unique identifier for the request
languagestringrequired
Language of the speech
sampleRatenumber or nulloptional
Sample Rate of the speech
Default:
8000
sendPartialbooleanoptional
Whether to send partial transcripts or not
Default:
true

Server messages

101The server streams transcribed text along with status and progress updates.

Receive Transcription (↓):

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "வணக்கம்",  "chunk": 1,  "stage": "partial",  "completed": false,  "mode": "stt"}

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "வணக்கம் இனிய",  "chunk": 1,  "stage": "partial",  "completed": false,  "mode": "stt"}

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "வணக்கம் இனிய நாள்!",  "chunk": 1,  "stage": "final",  "completed": false,  "mode": "stt"}

When the transcription is complete:

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "",  "chunk": 2,  "stage": "final",  "completed": true,  "mode": "stt"}

Messages

Message Type	Example	Description
Send (↑)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "language": "tamil", "sampleRate": 16000 }`	The client sends parameters for getting transcription from Audio.
Send (↑)	`Raw PCM 16-bit Audio Data (in Bytes)`	The client sends audio data after sending metadata.
Receive (↓)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": true, "transcript": "வணக்கம்", "chunk": 1, "stage": "partial", "completed": false, "mode": "stt" }`	The server returns intermediate transcription updates.
Receive (↓)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": true, "transcript": "வணக்கம் இனிய", "chunk": 1, "stage": "partial", "completed": false, "mode": "stt" }`	Continued partial result with updated transcription.
Receive (↓)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": true, "transcript": "வணக்கம் இனிய நாள்!", "chunk": 1, "stage": "final", "completed": false, "mode": "stt" }`	Final transcription for the current audio segment.
Receive (↓)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": true, "transcript": "", "chunk": 2, "stage": "final", "completed": true, "mode": "stt" }`	Indicates completion of transcription for the entire stream.

Example response

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "வணக்கம்",  "chunk": 1,  "stage": "partial",  "completed": false,  "mode": "stt"} {  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "வணக்கம் இனிய",  "chunk": 1,  "stage": "partial",  "completed": false,  "mode": "stt"} {  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "வணக்கம் இனிய நாள்!",  "chunk": 1,  "stage": "final",  "completed": false,  "mode": "stt"} {  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "",  "chunk": 2,  "stage": "final",  "completed": true,  "mode": "stt"}

Request

1# Requirements: 2# sudo apt install portaudio19-dev3# pip install pyaudio websockets4 5import asyncio6import websockets7import pyaudio8import json9import threading10import signal11import sys12 13# Configuration14api_key = "your_api_key"15 16url = f'wss://stream.shabd.tech/v1/streaming-speech-to-text'17headers = {"x-api-key": api_key}18requestId = "your_uuid_here"19 20LANGUAGE = "english"21SAMPLE_RATE = 1600022CHUNK_DURATION = 0.08  # 80ms23CHUNK_SIZE = int(SAMPLE_RATE * CHUNK_DURATION)  # 1280 samples24FORMAT = pyaudio.paInt1625CHANNELS = 126 27# Global variables28websocket = None29audio = None30stream = None31is_recording = False32audio_thread = None33loop = None34 35def signal_handler(signum, frame):36    global is_recording37    print("\nReceived interrupt signal. Stopping...")38    is_recording = False39 40signal.signal(signal.SIGINT, signal_handler)41 42def audio_worker():43    # Read audio from microphone and send to WebSocket44    global websocket, stream, is_recording, loop45    print("Recording started. Press Ctrl+C to exit at any time.")46    try:47        while is_recording and websocket:48            audio_data = stream.read(CHUNK_SIZE, exception_on_overflow=False)49            if websocket and not websocket.closed:50                asyncio.run_coroutine_threadsafe(websocket.send(audio_data), loop)51    except Exception as e:52        if is_recording:53            print(f"Audio error: {e}")54    finally:55        print("Recording stopped. Sending final empty buffer...")56        try:57            if websocket and not websocket.closed:58                # Send empty buffer to signal end of audio59                asyncio.run_coroutine_threadsafe(websocket.send(b""), loop)60        except Exception as e:61            print(f"Error sending final empty message: {e}")62 63async def handle_messages():64    # Handle incoming WebSocket messages65    global websocket, is_recording66    try:67        async for message in websocket:68            try:69                msg = json.loads(message)70                request_id = msg['requestId']71                chunk_id = msg['chunk']72                transcript = msg['transcript']73                stage = msg['stage']74                completed = msg['completed']75        76                if completed:77                    print("\n--- Transcription Completed ---")78                    is_recording = False79                    break80 81                if transcript:82                    if stage == 'partial':83                        print(84                            f"\r[Partial] Chunk: {chunk_id} | Transcript: {transcript}",85                            end='',86                            flush=True87                        )88                    elif stage == 'final':89                        print(f"\n[Final] Chunk: {chunk_id} | Transcript: {transcript}")90 91            except json.JSONDecodeError:92                print("\n[Warning] Received non-JSON message.")93    except websockets.exceptions.ConnectionClosed:94        print("\nWebSocket connection closed.")95    except Exception as e:96        print(f"Message handler error: {e}")97 98def setup_audio():99    global audio, stream100    audio = pyaudio.PyAudio()101    stream = audio.open(102        format=FORMAT,103        channels=CHANNELS,104        rate=SAMPLE_RATE,105        input=True,106        frames_per_buffer=CHUNK_SIZE107    )108 109async def cleanup():110    global audio, stream, websocket, audio_thread111    print("\nCleaning up resources...")112 113    if audio_thread and audio_thread.is_alive():114        audio_thread.join(timeout=2.0)115    if stream:116        stream.stop_stream()117        stream.close()118    if audio:119        audio.terminate()120    if websocket:121        try:122            if not websocket.closed:123                await websocket.close()124                print("WebSocket closed.")125        except Exception as e:126            print(f"Error closing WebSocket: {e}")127 128async def main():129    global websocket, is_recording, audio_thread, loop130 131    try:132        # Setup133        setup_audio()134        loop = asyncio.get_event_loop()135 136        # Connect WebSocket with headers137        websocket = await websockets.connect(url, extra_headers=headers)138        print("Connected to WebSocket.", url)139 140        # Send metadata141        metadata = { "requestId": requestId, "language": LANGUAGE, "sampleRate": SAMPLE_RATE}142        await websocket.send(json.dumps(metadata))143 144        # Start audio thread145        is_recording = True146        audio_thread = threading.Thread(target=audio_worker, daemon=True)147        audio_thread.start()148 149        # Receive messages150        await handle_messages()151 152    except Exception as e:153        print(f"Fatal error: {e}")154    finally:155        await cleanup()156 157if __name__ == "__main__":158    try:159        asyncio.run(main())160    except KeyboardInterrupt:161        print("\nGoodbye!")162        sys.exit(0)163    except Exception as e:164        print(f"Startup error: {e}")165        sys.exit(1)

1// Requirements: npm install ws mic2const WebSocket = require('ws');3const mic = require('mic');4 5// Configuration6const api_key = "your_api_key";7const url = `wss://stream.shabd.tech/v1/streaming-speech-to-text`; 8const headers = {9  "x-api-key": api_key10};11 12const requestId = "your_uuid_here";13const LANGUAGE = 'english';14const SAMPLE_RATE = 16000;15const CHUNK_DURATION = 0.08; // 80ms16const CHUNK_SIZE = SAMPLE_RATE * CHUNK_DURATION * 2; // 2 bytes per sample for 16-bit PCM17 18let isRecording = false;19let ws = null;20 21// Setup mic22const micInstance = mic({23  rate: SAMPLE_RATE.toString(),24  channels: '1',25  bitwidth: '16',26  encoding: 'signed-integer',27  endian: 'little',28  device: 'default',29  fileType: 'raw',30});31 32const micInputStream = micInstance.getAudioStream();33let buffer = Buffer.alloc(0);34let cleanupDone = false;35 36function cleanupAndExit() {37  if (cleanupDone) return;38  cleanupDone = true;39 40  console.log('\nCleaning up resources...');41  if (micInstance) micInstance.stop();42  if (ws && ws.readyState === WebSocket.OPEN) ws.close();43 44  process.exit(0);45}46 47process.on('SIGINT', () => {48  console.log('\nReceived interrupt signal. Stopping...');49  if (isRecording) {50    isRecording = false;51    micInstance.stop();52    console.log('Recording stopped. Sending final empty buffer...');53    if (ws && ws.readyState === WebSocket.OPEN) {54      ws.send(Buffer.alloc(0));55    }56  } else {57    cleanupAndExit();58  }59});60 61async function main() {62  ws = new WebSocket(url, {63    headers: headers,64  });65 66  ws.on('open', () => {67    console.log('Connected to WebSocket:', url);68    const metadata = { requestId: requestId, language: LANGUAGE, sampleRate: SAMPLE_RATE };69    ws.send(JSON.stringify(metadata));70 71    isRecording = true;72    micInstance.start();73    console.log('Recording started. Press Ctrl+C to stop.');74  });75 76  micInputStream.on('data', (data) => {77    if (!isRecording || !ws || ws.readyState !== WebSocket.OPEN) return;78 79    buffer = Buffer.concat([buffer, data]);80 81    while (buffer.length >= CHUNK_SIZE) {82      const chunk = buffer.slice(0, CHUNK_SIZE);83      buffer = buffer.slice(CHUNK_SIZE);84      ws.send(chunk);85    }86  });87 88  ws.on('message', (message) => {89    try {90      const msg = JSON.parse(message);91      const { requestId, chunk: chunkId, transcript, stage, completed } = msg;92 93      if (completed) {94        console.log('\n--- Transcription Completed ---');95        cleanupAndExit();96        return;97      }98 99      if (transcript) {100        if (stage === 'partial') {101          process.stdout.write(`\r[Partial] Chunk: ${chunkId} | Transcript: ${transcript}`);102        } else if (stage === 'final') {103          console.log(`\n[Final] Chunk: ${chunkId} | Transcript: ${transcript}`);104        }105      }106    } catch (err) {107      console.warn('[Warning] Received invalid JSON message.');108    }109  });110 111  ws.on('close', () => {112    console.log('WebSocket connection closed.');113    cleanupAndExit();114  });115 116  ws.on('error', (err) => {117    console.error('WebSocket error:', err);118    cleanupAndExit();119  });120}121 122main().catch((err) => {123  console.error('Startup error:', err);124  cleanupAndExit();125});