Most problems with how a line sounds are fixed in the text, not the settings. This page covers what to write, per language, how to record a voice worth cloning, how to get clean transcripts, and how to brief the LLM that writes your lines.
Writing for speech
Write the text the way it should be said. The voice reads what's there, so anything with more than one reading is a guess:
| Instead of | Write |
|---|---|
$1.5M | one and a half million dollars |
3/4 | three quarters, or March fourth |
in 2026 | in twenty twenty-six |
SQL | sequel, or S Q L |
120 km/h | a hundred and twenty kilometres an hour |
iodine.dev | iodine dot dev |
Siobhan | Shiv-awn (a name, spelled as it sounds) |
- Punctuation is pacing. A comma is a short pause, a full stop ends the thought,
…trails off and?lifts. Split long sentences: they're read in one breath. - Send plain text. Markdown, bullet points, emoji and links aren't spoken the way you'd want. Strip them first (there's a snippet below).
- Set
languageto the language of the text. A voice can tell Japanese and Chinese from the script, but not Spanish from English, so without it a Spanish line can come out with an English accent. - One language per sentence. A sentence that switches language is read in one accent.
- A misread word won't fix itself. Respell it until it sounds right, then keep that spelling.
- If a line comes out wrong only sometimes (a misread word, a skipped or repeated phrase), lower
temperature, for example to0.7. Lower is steadier; higher is more varied and expressive.
Japanese
Write English words and names in katakana. Latin letters in Japanese text can be read with English sounds that don't fit, or clipped:
Soulmateの世界へようこそ。 → ソウルメイトの世界へようこそ。 今日はZoomで会議があるよ。 → 今日はズームで会議があるよ。Write a kanji in kana if it's misread. Many have more than one reading, and names most of all:
今夜の海風、気持ちいいね。 → こんやの海風、気持ちいいね。 明日、また会おうね。 → あした、また会おうね。 陽菜ちゃん、おはよう。 → ひなちゃん、おはよう。Counters and numbers in kana when the reading matters:
3人→さんにん,10時→じゅうじ,1日→いちにちorついたち.Use Japanese punctuation (
。、!?) and no spaces between words.
Chinese
- Characters with several readings (多音字) are read from context. If one comes out wrong, rephrase or pick another word: pinyin in the text isn't read as a pronunciation.
- Numbers as you want them said:
2026年→二〇二六年, a phone number110→幺幺零, an amount110→一百一十. - Use full-width punctuation:
。,!?. - English names in Chinese text are fine as they are:
欢迎来到 Soulmate 世界.
Korean
- English words in Hangul for a Korean pronunciation:
Soulmate→소울메이트. - Numbers in Hangul when the counting system matters:
3시→세 시(native),3분→삼 분(Sino-Korean).
Spanish, French, German and other Latin-script languages
- Always send
language, as above. - Keep accents and other marks:
está,garçon,Straße. Without them a word can be read as a different one. - In Spanish, opening
¿and¡help mark a question or exclamation from its start.
Hindi, Arabic, Russian and other scripts
- Write in the language's own script, not romanised. Hindi typed in Latin letters ("aap kaise ho") is read as if it were English.
Realtime
- End sentences with punctuation. The realtime socket speaks a sentence as soon as it's complete, so a reply without full stops waits until 300 characters or a
flush.。!?end a sentence on their own, with no space needed. - Keep a style inside one sentence (
{whisper}…{/whisper}), since sentences are spoken separately. - Send
flushwhen the LLM's turn ends, so the last words don't wait.
Cloning
- The recording is the voice. 10 to 30 seconds of one person, close to the microphone, no music and no other voices (clean it in the Voice isolator first if needed). The delivery carries over too: a calm reading makes a calm voice, an expressive one an expressive voice.
- A clip per language. A voice speaks each language from a clip in that language. With only an English recording it speaks Japanese with an English accent and misreads more (今夜 as きおん, "Soulmate" as ソーマイ). Add a clip for every language the voice will speak: a recording of the speaker if you have one, or one generated from the voice's own recording, which fixes both.
- Give the transcript, exactly. Every word as spoken, fillers and false starts included, in the language spoken. Without one we transcribe it; check the
transcriptin the response and make the voice again if it's wrong. If the speaker switches language, analyze the recording first to get each part's language and transcript, or sendlanguage: "mixed"with your own transcript: a recording is otherwise transcribed in one language. - Test with new lines. If the text you send matches the recording word for word, the voice can carry on with whatever came next in the recording. Real conversations don't repeat your recording, so test with lines it doesn't contain.
Speech to text
- Set
language. It defaults to English, and audio in another language heard as English comes back translated or garbled. If you don't know it,autodetects it; a known language is still more accurate. - One language per request. If the speakers switch language, split the recording where they do.
- Clean audio transcribes better. Run music or background noise through the Voice isolator first, and trim long silences.
- Split long recordings at pauses: 10 minutes is the limit per request.
Getting your LLM to write cues
The voice performs best when the text is written for it, and in a voice agent that's the LLM's job. Brief it once, in the system prompt.
A system prompt to start from
You are speaking out loud: everything you write is read by a text-to-speech voice.
Write for the ear:
- Plain sentences only: no markdown, lists, headings, emoji, links or code.
- Write numbers, dates, money and abbreviations the way they're said ("twenty dollars", not "$20").
- Short sentences and contractions. Talk like a person, not a document.
- In Japanese, write English words and names in katakana.
Direct your voice with cues in curly braces. They are never spoken.
- Start a sentence with an emotion when it changes: {happy} {sad} {angry} {scared} {excited}
{calm} {nervous} {tired} {playful} {serious} {warm} {sarcastic}
- Or describe the delivery in a few words, like a note to an actor: {quietly, trying not to laugh}
- Put sounds exactly where they happen: {laughs} {sighs} {gasps} {small laugh} {pause}
- Wrap a few words in a style and close it: {whisper}just between us{/whisper}, {emphasis}never{/emphasis}
- One emotion per sentence at most, and no more than two or three cues in a row. Most sentences need none.
- Never use *asterisks*, (parentheses) or [brackets] for actions or tone: only {curly braces}.Add your character and the scene above it: the cues follow from who's speaking and what's happening, so a well-described character needs fewer rules.
What good output looks like
Before: *laughs* Oh my god, that's SO funny!!! 😂 You HAVE to see this: https://…
After: {laughs} Oh my god, that's so funny. {playful} You have to show me the rest.Before: I'm sorry to hear that. Here are some things that might help: 1. Rest 2. Water
After: {warm} Oh no, I'm sorry. {soft}Get some rest tonight, okay?{/soft} And drink some water.- Fewer is better. A cue on every sentence sounds acted. Save them for where the feeling changes.
- Short, concrete directions work best:
{tired, a little hoarse}beats a sentence of backstory. - Sounds go where they happen:
I'm fine. {shaky breath} Really., not at the end of the line. - Try lines in the Playground before putting them in a prompt.
Cleaning up LLM output
Even a well-briefed model slips sometimes. Convert or strip the common slips before sending text to the voice:
const speakable = (text) =>
text
.replace(/\*\*([^*\n]+)\*\*/g, '$1') // **bold** → bold
.replace(/\*([^*\n]{1,40})\*/g, '{$1}') // *laughs* → {laughs}
.replace(/\[([^\]\n]+)\]\([^)\n]+\)/g, '$1') // [a link](…) → a link
.replace(/^\s*(#+|[-*•]|\d+\.)\s+/gm, '') // headings, bullets, numbered lists
.replace(/`/g, '')
.replace(/\p{Extended_Pictographic}️?/gu, ''); // emojiAgents building your integration
If a coding agent (Claude Code, Cursor and the like) is writing your integration, point it at /llms-full.txt: every page of these docs in one plain-text file, this one included.