Text-to-Speech

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:

type

string

required

Must be "tts"

payload

object

required

Show payload properties

text

string

required

The text to synthesize. Maximum 2000 characters.

speaker

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.

dialect

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.

languageId

string

required

Language code. (e.g., “ar”).

mulaw

boolean

required

Whether to use mu-law audio encoding. (e.g., false)

expressiveness

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,
    "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 a speaker 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
    }
  }));
};

overview

WebSocket Playgrounds

Quick Start

Request Message

Response Sequence

Dialects and Voice Examples

Available Speakers

Using Custom Cloned Voices

​Quick Start

​Request Message

​Response Sequence

​Dialects and Voice Examples

​Available Speakers

​Using Custom Cloned Voices

Quick Start

Request Message

Response Sequence

Dialects and Voice Examples

Available Speakers

Using Custom Cloned Voices