API Reference

Speech To Speech · WebSocket

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

Connection headers

x-api-keystringrequired
API key for authentication.

Message flow

WebSocket endpoint for real-time speech-to-speech conversion.

Message Flow:

Outgoing Message (↑): The client sends metadata including a requestId, sourceLanguage, targetLanguage, and optional settings like gender, inputSampleRate, sampleRate and speed. After sending metadata, the client sends audio data in bytes.
Incoming Message (↓): The server responds with processed text and audio data.

Send MetaData (↑):

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "sourceLanguage": "english",  "targetLanguage": "hindi",  "gender": "female",  "inputSampleRate": 16000,  "sampleRate": 8000,  "speed": "normal",  "projectId": "<your-project-id-here>"}

Send Audio Data (↑):

  Raw PCM 16-bit Audio Data (in Bytes)

Initial messageapplication/json

requestIdstringrequired
Unique identifier for the request
sourceLanguagestringrequired
Source language of the speech
targetLanguagestringrequired
Target language to translate to
genderstringoptional
Allowed:
male
female
Default:
male
inputSampleRatenumber or nulloptional
Sample rate of the input speech
Default:
16000
sampleRatenumber or nulloptional
Audio sample rate for synthesis (e.g., 22050)
speedstringoptional
Allowed:
slow
normal
fast
Default:
normal
projectIdstring or nulloptional
An optional ID representing the project.

Server messages

101The server sends back synthesized audio as continuous streams of raw PCM-16 bit audio data.The response consists of 48-byte header containing metadata.Raw PCM-16 bit audio data following the header.

Receive Message (↓):

Streaming PCM-16 bit audio data in chunks...

Field Breakdown

Field	Description	Size	Byte Offset
requestId	Unique ID for the request	36	0 - 35
status	0 (error) or 1 (success)	1	36
completed	0 (in progress) or 1 (finished)	1	37
sampleRate	Sampling rate of the audio (e.g., 8, 16, 22, 48)	1	38
gender	0 (female) or 1 (male)	1	39
contentLength	Length of the audio content (in bytes)	4	40 - 43
chunkId	ID for each audio chunk	1	44
Audio content begins from byte 48

Messages

Message Type	Example	Description
Send (↑)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "sourceLanguage": "english", "targetLanguage": "hindi", "gender": "female", "inputSampleRate": 16000, "sampleRate": 8000, "speed": "normal", "projectId": "<your-project-id-here>" }`	The client sends parameters for speech synthesis.
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": "Welcome to Shabd", "chunk": 1, "completed": false, "mode": "stt" }`	The server sends transcription along with status.
Receive (↓)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": true, "translation": "शब्द में आपका स्वागत है", "chunk": 1, "completed": false, "mode": "ttt" }`	The server sends translation along with status.
Receive (↓)	`Continuous stream of raw PCM-16 bit audio data in chunks until byte header completed true`	The server sends back the synthesized audio as PCM-16 bit.
Receive (↓)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": true, "transcript": "", "chunk": 2, "completed": true, "mode": "stt" }`	The server sends completed message for transcription.
Receive (↓)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": true, "translation": "", "chunk": 2, "completed": true, "mode": "ttt" }`	The server sends completed message for translation.

Request

1from websockets.sync.client import connect2from scipy.io import wavfile3import json4import wave5 6api_key = "your_api_key"7 8url = f'wss://stream.shabd.tech/v1/speech-to-speech'9headers = {"x-api-key": api_key}10 11sampleRate = 8000  12inputSampleRate, audio_data = wavfile.read("path_to_your_audio_file.wav")13audio_data_bytes = audio_data.tobytes() # Ensure your audio is Raw PCM 16 bit Format14 15metadata = {16    "requestId": "your_uuid_here",17    "sourceLanguage": "english",18    "targetLanguage": "hindi",19    "gender": "female",20    "inputSampleRate": inputSampleRate, # Input Sample Rate of the Audio21    "sampleRate": sampleRate,  # Sample Rate for Audio Synthesis22    "speed": "normal",23    "projectId": "your_project_id_here"24}25 26with connect(url, additional_headers=headers) as ws:27    ws.send(json.dumps(metadata))28    ws.send(audio_data_bytes)29    30    i=131    for data in ws:32        # Handle string data (transcriptions and translations)33        if isinstance(data, str):34            response = json.loads(data)35            36            status = response.get("status", False)37            transcript = response.get("transcript", "")38            translation = response.get("translation", "")39            chunk = response.get("chunk") 40            completed = response.get("completed", False)41            mode = response.get("mode")42            43            if not status:44                print("Request Failed: ",response.get('message', 'Unknown Error'))45            if transcript:46                print(f"Transcript {chunk}: {transcript}") # chunk id and transcript47            if completed and mode == "stt":48                print("Transcription completed")49            if translation:50                print(f"Translation {chunk}: {translation}") # chunk id and translation51            if completed and mode == "ttt":52                print("Translation completed")53        54        # Handle binary data (audio chunks)55        if isinstance(data, bytes):56            header = data[:48]57            content = data[48:]  # Audio content starts from 4858            59            status = header[36] # status 0 or 160            completed = header[37] # completed 0 or 161            62            if not status:63                print("Request Failed: ", str(content))64                break  65            if completed: 66                print("Audio Synthesis Completed")67                break68            print(f"Received audio chunk of size {len(content)} bytes")69            with wave.open(f'SynthesizedAudio_Chunk{i}.wav', 'wb') as wf:70                wf.setnchannels(1)71                wf.setsampwidth(2)72                wf.setframerate(sampleRate)73                wf.writeframes(content)74                i+=1

1const WebSocket = require('ws');2const fs = require('fs');3const wav = require('wav');4 5const api_key = "your_api_key";6const url = `wss://stream.shabd.tech/v1/speech-to-speech`; 7const headers = {8  "x-api-key": api_key9};10 11const sampleRate = 8000; // Sample Rate for Audio Synthesis12const audioFilePath = 'path_to_your_audio_file.wav';13const audioData = fs.readFileSync(audioFilePath);14const inputSampleRate = audioData.readUInt32LE(24);  // Extract sample rate from audio file15const pcmData = audioData.slice(44); // Sending raw PCM Audio16 17const metadata = {18  requestId: "your_uuid_here",19  sourceLanguage: "english",20  targetLanguage: "hindi",21  gender: "female",22  inputSampleRate: inputSampleRate,23  sampleRate: sampleRate,24  speed: "normal",25  projectId: "your_project_id_here"26};27 28// Initialize WebSocket connection29const ws = new WebSocket(url, {30  headers: headers31});32 33ws.on('open', () => {34  ws.send(JSON.stringify(metadata));  35  ws.send(pcmData);               36});37 38let i = 1;39ws.on('message', (data) => {40  if (Buffer.isBuffer(data)) {41    try {42      const stringData = data.toString('utf8');43      if (stringData && stringData.startsWith("{") && stringData.endsWith("}")) {44        const response = JSON.parse(stringData);45        46        status = response.status;47        transcript = response.transcript;48        translation = response.translation;49        chunk = response.chunk;50        completed = response.completed;51        mode = response.mode;52        53        if (!status) 54          console.log("Request Failed: ", response.message || 'Unknown Error');55  56        if (transcript) 57          console.log(`Transcript ${chunk}: ${transcript}`);58        59        if (completed && mode === "stt") 60          console.log("Transcription completed");61        62        if (translation) 63          console.log(`Translation ${chunk}: ${translation}`);64        65        if (completed && mode === "ttt")66          console.log("Translation completed");67      68      } else {69        const header = data.slice(0, 48);  // first 48 bytes are header70        const content = data.slice(48);    // The rest is audio content71        const status = header[36]; // status 0 or 172        const completed = header[37]; // completed 0 or 173 74        if (!status) { 75          console.log("Request Failed: ", content.toString());76          ws.close(); 77        }78 79        if (completed) {  80          console.log("Audio Synthesis Completed");81          ws.close(); 82          return;83        }84 85        console.log(`Received audio chunk of size ${content.length} bytes`);86 87        const writer = new wav.Writer({88            sampleRate: sampleRate,  // Set the sample rate89            channels: 1,             // Mono (1 channel)90            bitDepth: 16             // 16-bit depth (common for audio)91          });92  93        const fileName = `SynthesizedAudio_Chunk${i}.wav`;94        const writeStream = fs.createWriteStream(fileName);95 96        writer.pipe(writeStream);97        writer.write(content);98        writer.end();99  100        console.log(`Saved audio chunk to ${fileName}`);101        i++; 102      }103    } catch (err) {104      console.log("Error processing buffer: ", err);105    }106  } else {107    console.log("Unexpected data type received");108  }109});110 111ws.on('error', (err) => {112  console.error("WebSocket Error: ", err);113});114 115ws.on('close', () => {116  console.log("WebSocket connection closed");117});