Recipes

Emotion and speaking style

Make a voice sound happy or sad, whisper, or read like a newscaster, using tags in the text.

Put a tag such as [happy] in front of the words. The SDKs send text unchanged, so tags work with the SDK you already use. A tag the voice can't apply is skipped, never spoken.

Check the voice

In the voice list, profile.emotions and profile.styles list what each voice can do. If they're missing, don't send tags. The SDKs return them in 0.18.1, or 0.19.0-beta.3 or later (Python: 0.18.1, or 0.19.0b3 or later).

const [voice] = await client.listVoices({ timeoutSeconds: 5 });
const emotions = voice.profile?.emotions ?? [];
const styles = voice.profile?.styles ?? [];
console.log(voice.label, emotions, styles);

Tag the text

Change only text in Play speech as it streams:

const text = "[happy] I can't believe the results came in this morning.";

for await (const chunk of client.synthesizeStream(text, {
  voice_id: voice.id,
  model: TtsModel.Nebula,
  timeoutSeconds: 30,
})) {
  process.stdout.write(chunk.audio);
}

Switch inside one request

Each tag applies until the next one. The parts play one after another in the same audio stream.

text
[news] Breaking news: the new terminal opens today. [storytelling] But for one traveller, it was the start of a long journey home. [happy] And she made it just in time!
[news] عاجل: افتتاح المبنى الجديد اليوم. [storytelling] لكن بالنسبة لمسافرة واحدة، كانت هذه بداية رحلة طويلة إلى الوطن. [happy] ووصلت في الوقت المناسب تماماً!

Set a starting delivery (optional)

generation_config.emotion sets the delivery before the first tag, here news. Tags switch from it.

tts request
{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "model": "nebula",
  "voice_id": "42e38a63-849a-481a-b5bf-3c1b7a985de3",
  "text": "Good evening. [happy] And now, some good news.",
  "generation_config": { "emotion": "news" }
}

Hear every delivery

Voice mul_nourah. Every emotion reads the same sentence: "I can't believe the results came in this morning." / "لا أصدق أن النتائج وصلت هذا الصباح."

EmotionTagListen
neutral (default)None
happy[happy]
sad[sad]
angry[angry]
fearful[fearful]
surprised[surprised]
whisper[whisper]
StyleTagListen
news · Good evening. Riyadh hosted the regional tech summit today…[news]
storytelling · Long ago, in a quiet village by the sea…[storytelling]
advertising · This weekend only, get twenty percent off every plan…[advertising]
call_center · Thank you for calling. Your account is verified…[call_center]
conversational · Honestly, I wasn't sure about it at first…[conversational]

Before you ship, check the rules and limitations.

Scenarios

On this page