--- name: tts-dialogue-writing description: | Write natural, human-like dialogue scripts optimized for AI text-to-speech generation. Use when: (1) Creating podcast scripts, audiobook chapters, YouTube video scripts, documentary narration, or any spoken content, (2) Rewriting existing scripts to sound more natural when spoken aloud, (3) Adding supported paralinguistic tags for TTS voice synthesis, (4) Converting word counts to speech duration (150 WPM standard), (5) Structuring multi-speaker dialogue that flows naturally. version: "2.0.1" --- # TTS Dialogue Writing Create natural, engaging spoken content optimized for AI voice synthesis. ## Core Principles ### 1. Write for the Ear, Not the Eye Written text and spoken dialogue are fundamentally different: | Written Text | Spoken Dialogue | |--------------|-----------------| | Long sentences with subordinate clauses | Short, punchy sentences | | Formal transitions ("Furthermore," "In conclusion") | Natural bridges ("So here's the thing," "And that's when") | | Dense information | Breathing room between ideas | | Passive voice acceptable | Active voice preferred | | Abstract concepts | Concrete examples and stories | ### 2. Speech Duration Formula **Standard TTS rate: 150 words per minute** | Target Duration | Word Count | |-----------------|------------| | 5 minutes | 750 words | | 10 minutes | 1,500 words | | 15 minutes | 2,250 words | | 20 minutes | 3,000 words | | 30 minutes | 4,500 words | ### 3. Speaker Tag Rules **Minimize redundant tags.** Only add a speaker tag when the speaker changes: ``` BAD (redundant tags): [Host]: Welcome to the show! [Host]: Today we're discussing productivity. [Host]: I'm really excited about this topic. GOOD (speaker continues without re-tagging): [Host]: Welcome to the show! Today we're discussing productivity. I'm really excited about this topic. ``` **Tag changes only when needed:** ``` [Host]: Let me ask you about your morning routine. [Guest]: Oh, that's a great question. I actually don't have one! I know that sounds crazy, but hear me out. I tried the whole 5 AM club thing for about six months. Meditation, journaling, cold showers. [Host]: And it didn't work for you? [Guest]: It made me miserable. Here's what I realized... ``` ### 4. Paralinguistic Tags: Strategic, Not Systematic Vois supports vocal reaction tags, not broad acting-emotion tags. Do not write unsupported tags like `[happy]`, `[sad]`, `[excited]`, `[nervous]`, `[warm]`, `[whisper]`, or `[dramatic]` as bracket tags. Those words should be expressed through the prose, speaker direction, or an engine style instruction. **BAD (unsupported tags):** ``` [Host]: [excited] Welcome back everyone! [Guest]: [nervous] I'm a little nervous actually. [Host]: [warm] Don't worry, we'll take it easy. ``` **GOOD (supported tag plus natural writing):** ``` [Host]: Welcome back, everyone! Today we have someone whose work changed how I think about productivity. [Guest]: Thanks for having me. I don't usually do podcasts, so I may need a second to settle in. [Host]: [laugh] That's completely fair. We'll keep it easy. Just a conversation between friends. ``` **When to use paralinguistic tags:** - A real vocal sound is useful: a laugh, sigh, gasp, sniff, cough, or backchannel - The moment would be unclear without the reaction - A scene needs a small human texture, not a full acting direction - The active engine supports the tag you are using For tone and performance, prefer natural wording. Use `--instruct` with Expressive or `--voice-design-instruct` / voice design with Omni when you need voice-level direction. **Plan gate:** Omni and Voice Design are Pro features. If the user is on Free or Subscriber, write scripts that work with Fast, Expressive, or Multilingual (legacy), and do not assume Omni tags or `--voice-design-instruct` will run. ### 5. Dialogue Flow Techniques **Interruptions and overlaps (use sparingly):** ``` [Guest]: The thing about morning routines is... [Host]: They're completely personal, right? [Guest]: Exactly! Everyone's different. ``` **Trailing thoughts:** ``` [Guest]: I've been thinking about this a lot lately... like, why do we even need routines at all? ``` **Reactions integrated into speech:** ``` [Host]: [laugh] Okay, I love that. So you're telling me the secret to productivity is... having no routine? ``` **Natural fillers (use sparingly for authenticity):** ``` [Guest]: So, here's the thing about habits. They're, I mean, they're kind of overrated, honestly. ``` ### 6. Pacing and Rhythm **Vary sentence length:** ``` Short sentences create urgency. They punch. They grab attention. But then you need longer sentences that allow the listener to breathe, to process what they've just heard, to let the ideas settle before the next point arrives. Then short again. ``` **Use paragraph breaks for pauses:** In TTS, paragraph breaks create natural pauses. Use them to: - Signal topic shifts - Create dramatic effect - Allow processing time after important points **Punctuation-based pacing (no SSML needed):** The TTS engines interpret punctuation as timing cues. Use them deliberately: | Punctuation | Pause Duration | Best For | |-------------|---------------|----------| | Ellipsis `...` | ~0.4-0.6s | Reflective pauses, trailing thoughts, suspense | | Period `.` | ~0.3-0.5s | Clean sentence stops, declarative weight | | Comma `,` | ~0.1-0.2s | Breathing room, list pacing, clause separation | | Semicolon `;` | ~0.2-0.4s | Mid-weight pause, connecting related ideas | ``` SLOW, REFLECTIVE: [Narrator]: She looked at the letter... then at the door... then back at the letter. URGENT, STACCATO: [Reporter]: The building collapsed. Three exits blocked. One left. ``` **Paralinguistic tags** add human texture to speech. Available tags depend on the active engine. Use sparingly for key moments. **Expressive Engine Native Tags (9):** | Native tag | Use for | |------------|---------| | `[laugh]` | Natural laughter | | `[chuckle]` | Soft chuckle | | `[gasp]` | Sharp intake of breath | | `[sigh]` | Audible exhalation | | `[groan]` | Frustrated or pained groan | | `[cough]` | Cough sound | | `[clear throat]` | Throat clearing | | `[sniff]` | Sniffing sound | | `[shush]` | Hushing sound | **Omni Engine Native Tags (14, Pro-only):** | User intent | Native tag to write in CLI scripts | Notes | |-------------|------------------------------------|-------| | Laugh | `[laughter]` | Omni's laugh tag is not `[laugh]` | | Sigh | `[sigh]` | Shared with Expressive | | Sniff | `[sniff]` | Shared with Expressive | | Agreement | `[confirmation-en]` | Short "mm-hmm" style acknowledgement | | Curious | `[question-en]` | Unsure or curious acknowledgement | | Puzzled ah | `[question-ah]` | Puzzled "ah?" sound | | Oh? | `[question-oh]` | Questioning or realizing "oh?" | | Skeptical | `[question-ei]` | Doubtful "eh?" sound | | Confused | `[question-yi]` | Confused "huh?" sound | | Startled | `[surprise-ah]` | Startled surprise | | Oh wow | `[surprise-oh]` | Warm surprise or realization | | Wow | `[surprise-wa]` | Amazed or impressed surprise | | Whoa | `[surprise-yo]` | Energetic surprise | | Disapproval | `[dissatisfaction-hnn]` | Dissatisfied or disapproving sound | The desktop editor may show friendlier labels such as `[laugh]`, `[mm-hmm]`, `[wow]`, or `[disapprove]` and map them internally. CLI scripts should use the native tag for the selected engine so the model receives exactly what it supports. ``` # Expressive engine [Host]: [laugh] Okay, that's a hot take. But seriously... [Guest]: [sigh] I know, I know. But hear me out. # Omni engine [Host]: [laughter] Okay, that's a hot take. But seriously... [Guest]: [sigh] I know, I know. [confirmation-en] But hear me out. ``` **Omni voice design instruct** -- the Pro-only Omni engine supports a `--voice-design-instruct` flag that takes comma-separated voice attributes from a fixed vocabulary (NOT free text): gender (`male`, `female`); age (`child`, `teenager`, `young adult`, `middle-aged`, `elderly`); pitch (`very low pitch` through `very high pitch`); style (`whisper`); accent (10 English accent labels such as `british accent`). At most one item per category: ```bash vois-cli tts generate --text "Welcome to the show." \ --voice voice_design \ --engine omni --output designed.wav \ --voice-design-instruct "male, middle-aged, low pitch, american accent" ``` **Omni pronunciation control** -- the Omni engine supports inline pronunciation overrides: Chinese pinyin override (append pinyin with tone number after the character): ``` 这批货物打ZHE2出售 ``` English CMU phoneme override (use CMU notation in square brackets): ``` You could probably still make [IH1 T] look good. ``` **Chunk boundaries:** Each new `[Speaker]:` line creates a separate audio chunk with a crossfade gap between them. Use speaker changes strategically to control pacing in multi-speaker content. Rapid back-and-forth creates energy, while longer monologues build depth. ### 7. Content Structure by Format **Podcast/Interview:** - Open with energy and hook - Build rapport through natural conversation - Include disagreement and genuine curiosity - End with actionable takeaway **Audiobook (Fiction):** - Show don't tell through dialogue and action - Vary narrator tone with scene mood - Use supported paralinguistic tags for true vocal reactions - Create distinct character voices through word choice, not just tags **Audiobook (Non-fiction):** - Open chapters with compelling hook - Use stories and examples liberally - Direct address to listener ("Here's what this means for you...") - Summarize key points naturally, not mechanically **YouTube/Tutorial:** - Hook in first 15 seconds - Promise value immediately - Use conversational, energetic tone - Include "pattern interrupts" every 2-3 minutes - Clear calls-to-action **Documentary:** - Establish atmosphere through description - Use expert voices for credibility - Personal stories for emotional connection - Let silence (paragraph breaks) create weight ## Anti-Patterns to Avoid 1. **Mechanical tagging:** Not every line needs a speaker tag or paralinguistic tag 2. **Over-explanation:** Trust the listener to follow along 3. **Written-style transitions:** Avoid "In conclusion," "Furthermore," "As mentioned previously" 4. **Uniform sentence length:** Creates monotonous rhythm 5. **Abstract without concrete:** Always ground concepts in examples 6. **Announcing emotions:** "I'm so excited!" instead of showing excitement through word choice 7. **Perfect grammar in casual speech:** Real people use fragments, contractions, trailing thoughts ## Quality Checklist Before finalizing any script: - [ ] Read aloud. Does it flow naturally? - [ ] Word count matches target duration (150 WPM) - [ ] Speaker tags only at speaker changes - [ ] Paralinguistic tags are supported by the active engine and used sparingly - [ ] Variety in sentence length and rhythm - [ ] Concrete examples ground abstract concepts - [ ] Opening hooks attention immediately - [ ] Ending provides closure or call-to-action