API Reference

Text Translate To Speech · WebSocket

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

Connection headers

x-api-keystringrequired
API key for authentication.

Message flow

Outgoing Message (↑): The client sends a JSON object with the necessary parameters for translation and speech synthesis.
Incoming Message (↓): The server responds with a stream of translation and raw PCM-16 bit audio data in chunks.

Send Message (↑):

Sending Text Message

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "text": "नमस्ते, आपका दिन शुभ हो!",  "sourceLanguage": "hindi",  "targetLanguage": "tamil",  "gender": "female",  "sampleRate": 8000,  "speed": "normal"}

Initial messageapplication/json

requestIdstringrequired
Unique identifier for the request
textstringrequired
Text content to be converted to speech
sourceLanguagestringrequired
Source language of the text
targetLanguagestringrequired
Target language to translate to
genderstringoptional
Allowed:
male
female
Default:
male
sampleRatenumber or nulloptional
Audio sample rate for synthesis (e.g., 22050)
speedstringoptional
Allowed:
slow
normal
fast
Default:
normal

Server messages

101The server sends back translation and 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", "text": "नमस्ते, आपका दिन शुभ हो!", "sourceLanguage": "hindi", "targetLanguage": "tamil", "gender": "female", "sampleRate": 8000, "speed": "normal" }`	The client sends parameters for translation and speech synthesis.
Receive (↓)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": true, "translation": "வணக்கம் இனிய நாள்!", "chunk": 1, "completed": true, "mode": "ttt" }`	The server sends translation along with status and progress updates.
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 for the translated text.

Request

1from websockets.sync.client import connect2import json3import wave4 5api_key = "your_api_key"6 7url = f'wss://stream.shabd.tech/v1/text-translate-to-speech'8headers = {"x-api-key": api_key}9 10sampleRate = 8000  # SampleRate for Audio Synthesis11metadata = {12    "requestId": "your_uuid_here",13    "text": "नमस्ते, आपका दिन शुभ हो!",14    "sourceLanguage": "hindi",15    "targetLanguage": "tamil",16    "gender": "female",17    "sampleRate": sampleRate,18    "speed": "normal"19}20 21with connect(url, additional_headers=headers) as ws:22    ws.send(json.dumps(metadata))23    24    i=125    for data in ws:26        # Handle string data (translations)27        if isinstance(data, str):28            response = json.loads(data)29            30            status = response.get("status", False)31            translation = response.get("translation", "")32            chunk = response.get("chunk") 33            completed = response.get("completed", False)34      35            if not status:36                print("Request Failed: ",response.get('message', 'Unknown Error'))37            if translation:38                print(f"Translation {chunk}: {translation}") # chunk id and translation39            if completed:40                print("Translation completed")41        42        # Handle binary data (audio chunks)43        if isinstance(data, bytes):44            header = data[:48]45            content = data[48:]  # Audio content starts from 4846            47            status = header[36] # status 0 or 148            completed = header[37] # completed 0 or 149            50            if not status:51                print("Request Failed: ", str(content))52                break  53            if completed:54                print("Audio Synthesis Completed")55                break56            print(f"Received audio chunk of size {len(content)} bytes")57            with wave.open(f'SynthesizedAudio_Chunk{i}.wav', 'wb') as wf:58                wf.setnchannels(1)59                wf.setsampwidth(2)60                wf.setframerate(sampleRate)61                wf.writeframes(content)62                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/text-translate-to-speech`; 7const headers = {8  "x-api-key": api_key9};10 11const sampleRate = 8000; // Sample Rate for Audio Synthesis12 13const metadata = {14  requestId: "your_uuid_here",15  text: "नमस्ते, आपका दिन शुभ हो!",16  sourceLanguage: "hindi",17  targetLanguage: "tamil",18  gender: "female",19  sampleRate: sampleRate,20  speed: "normal"21};22 23// Initialize WebSocket connection24const ws = new WebSocket(url, {25  headers: headers26});27 28ws.on('open', () => {29  ws.send(JSON.stringify(metadata));            30});31 32let i = 1;33ws.on('message', (data) => {34  if (Buffer.isBuffer(data)) {35    try {36      const stringData = data.toString('utf8');37      if (stringData && stringData.startsWith("{") && stringData.endsWith("}")) {38        const response = JSON.parse(stringData);39        40        status = response.status;41        translation = response.translation;42        chunk = response.chunk;43        completed = response.completed;44        45        if (!status) 46          console.log("Request Failed: ", response.message || 'Unknown Error');47  48        if (translation) 49          console.log(`Translation ${chunk}: ${translation}`);50        51        if (completed) 52          console.log("Translation completed");53      54      } else {55        const header = data.slice(0, 48);  // first 48 bytes are header56        const content = data.slice(48);    // The rest is audio content57        const status = header[36]; // status 0 or 158        const completed = header[37]; // completed 0 or 159        60        if (!status) { 61          console.log("Request Failed: ", content.toString());62          ws.close(); 63        }64 65        if (completed) {66          console.log("Audio Synthesis Completed");67          ws.close(); 68          return;69        }70 71        console.log(`Received audio chunk of size ${content.length} bytes`);72 73        const writer = new wav.Writer({74            sampleRate: sampleRate,  // Set the sample rate75            channels: 1,             // Mono (1 channel)76            bitDepth: 16             // 16-bit depth (common for audio)77          });78  79        const fileName = `SynthesizedAudio_Chunk${i}.wav`;80        const writeStream = fs.createWriteStream(fileName);81 82        writer.pipe(writeStream);83        writer.write(content);84        writer.end();85  86        console.log(`Saved audio chunk to ${fileName}`);87        i++; 88      }89    } catch (err) {90      console.log("Error processing buffer: ", err);91    }92  } else {93    console.log("Unexpected data type received");94  }95});96 97ws.on('error', (err) => {98  console.error("WebSocket Error: ", err);99});100 101ws.on('close', () => {102  console.log("WebSocket connection closed");103});