Messages
{
"type": "tts",
"payload": {
"text": "مرحبا بك في خدمة همسة",
"speaker": "Amjad",
"dialect": "pls",
"languageId": "ar",
"mulaw": false,
"sampleRate": "16k",
"expressiveness": 1
}
}{
"type": "ack",
"payload": {
"message": "Real time text to speach connection establesh"
}
}{}{
"type": "end",
"payload": {
"message": "End of TTS stream"
}
}{
"type": "error",
"payload": {
"message": "Invalid payload for message type: tts"
}
}WebSocket Playgrounds
Text-to-Speech
Convert text to streaming audio via WebSocket
WSS
/
Connect to the WebSocket and send TTS requests to convert text into streaming audio.
Quick Start
- Enter your API key in the authentication field
- Click Connect to establish the WebSocket connection
- Modify the request payload with your text
- Click Send to receive streaming audio
Request Message
After connecting, send a JSON message with the following structure:string
required
Must be
"tts"object
required
Show payload properties
Show payload properties
string
required
The text to synthesize. Maximum 2000 characters.
string
required
Voice name (e.g.
Amjad) or the UUID of a custom cloned voice. Pick a speaker that matches the chosen dialect — see the dialect field below for voice examples.string
required
Dialect to synthesize. One of:
pls, egy, syr, irq, jor, leb, ksa, uae, bah, qat, kuw, oma, msa, ar-sa, en. See Dialects and Voice Examples below.string
required
Language code. (e.g., “ar”).
boolean
required
Whether to use mu-law audio encoding. (e.g., false)
string
default:"16k"
Output sample rate of the PCM audio. One of
8k or 16k. Defaults to 16k. Only applies to PCM output — cannot be combined with mulaw (mu-law output is always 8 kHz).number
default:"1"
Controls how expressive the generated speech sounds, from
0 (flat and monotone) to 2 (highly expressive). Defaults to 1.TTS Request
{
"type": "tts",
"payload": {
"text": "مرحبا بك في خدمة همسة",
"speaker": "Amjad",
"dialect": "pls",
"languageId": "ar",
"mulaw": false,
"sampleRate": "16k",
"expressiveness": 1
}
}
Response Sequence
The server responds with:1. Acknowledgment
{
"type": "ack",
"payload": {
"message": "Real time text to speach connection establesh"
}
}
2. Binary Audio Chunks
// Raw binary audio data streamed in chunks
// Buffer these chunks to reconstruct the complete audio
3. Stream End
{
"type": "end",
"payload": {
"message": "End of TTS stream"
}
}
Dialects and Voice Examples
Pick aspeaker that matches your chosen dialect. Voice examples per dialect:
| Dialect | Code | Voice examples |
|---|---|---|
| Palestinian | pls | Amjad, Layan |
| Egyptian | egy | Mariam, Samir |
| Syrian | syr | Dalal, Mais |
| Iraqi | irq | Lyali, Fatma |
| Jordanian | jor | Lana, Jasem |
| Lebanese | leb | Carla, Majd |
| Saudi | ksa | Hiba, Fahd |
| Emirati | uae | Salma, Dima |
| Bahraini | bah | Mazen, Ruba |
| Qatari | qat | Deema, Faisal |
| Kuwaiti | kuw | Mai, Hatem |
| Omani | oma | Aisha, Jaber |
| MSA / Fusha | msa | Salem, Tamim |
| Arabic – Gulf | ar-sa | Khalid, Rahma |
| English | en | Emma, James |
Available Speakers
Refer to Hamsa Platforms to get the list of the available pre-built speakers where you can take the name of the speaker, or use a UUID for your custom cloned voice.Using Custom Cloned Voices
When using a custom cloned voice (UUID) as the speaker, you must preload the voice before establishing the WebSocket connection. This ensures optimal latency during streaming.Preload Required for Custom VoicesCall the Preload Voice endpoint once when your application starts to avoid latency when using custom cloned voices.
// 1. Preload the custom voice at app startup
await fetch('https://api.tryhamsa.com/v2/tts/voices/custom/preload', {
method: 'POST',
headers: {
'Authorization': 'Token YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ voiceId: 'your-custom-voice-uuid' })
});
// 2. Now connect to WebSocket and use the custom voice
const ws = new WebSocket('wss://api.tryhamsa.com/v1/realtime/ws?api_key=YOUR_API_KEY');
ws.onopen = () => {
ws.send(JSON.stringify({
type: 'tts',
payload: {
text: 'Hello from my custom voice',
speaker: 'your-custom-voice-uuid', // Use the same UUID
dialect: 'pls',
languageId: 'ar',
mulaw: false
}
}));
};
Messages
{
"type": "tts",
"payload": {
"text": "مرحبا بك في خدمة همسة",
"speaker": "Amjad",
"dialect": "pls",
"languageId": "ar",
"mulaw": false,
"sampleRate": "16k",
"expressiveness": 1
}
}{
"type": "ack",
"payload": {
"message": "Real time text to speach connection establesh"
}
}{}{
"type": "end",
"payload": {
"message": "End of TTS stream"
}
}{
"type": "error",
"payload": {
"message": "Invalid payload for message type: tts"
}
}api_key
type:httpApiKey
API key passed as query parameter or X-Api-Key header
TTS Request
type:object
Request to convert text to speech
TTS Acknowledgment
type:object
Server acknowledges the TTS request
TTS Audio Chunk
type:string
Binary audio data chunk
TTS Stream End
type:object
Signals the end of the audio stream
Error Response
type:object
Error message from the server
Was this page helpful?