tts-safety-review

name	tts-safety-review
description	Review and edit text for TTS-unfriendly elements — URLs, emails, emojis, ALL-CAPS, abbreviations, markdown artefacts, and special characters. Produces a sanitised edited/ copy with original/ preserved.

TTS Safety Review

Scan and sanitise scripts for elements that don't translate well to speech: URLs, emails, emojis, shouting-style capitalisation, unexpanded abbreviations, markdown syntax, and bracketed stage directions. Output is TTS-ready and grounded in what real TTS engines handle poorly.

When to use

• You have text from web content, markdown docs, or chat that may contain URLs, emojis, or markdown artefacts
• You're converting user-submitted copy to TTS and want to catch rendering issues before synthesis
• You need a clean audit trail of what was changed and why

Inputs to gather

• Source text file (path)
• Optional: working directory for output (defaults to source file's parent)
• Optional: target TTS engine or flavour (SSML, ElevenLabs, generic) — informs how bracketed directions are handled

Procedure

1. Read the source text file and validate encoding.
2. Scan for problematic elements:
   • URLs: Replace with prose form (e.g., "https://example.com" → "link in the description" or "visit example.com") or remove entirely.
   • Emails: Spell out (e.g., "[e-mail]" → "user at example dot com") or replace with contact instruction.
   • Emojis: Strip entirely or transcribe to text (e.g., 😀 → "(smiling)").
   • ALL-CAPS: Downcase unless the context signals genuine emphasis (all-caps shouting, acronyms). Convert acronyms to "U.S.A." or spell out as "United States".
   • Abbreviations: Expand (e.g., "etc." → "et cetera", "Dr." → "Doctor") or wrap in SSML <sub> tags.
   • Markdown: Strip syntax (**bold** → "bold", # heading → "heading", [text](url) → "text"), keep content.
   • Bracketed stage directions (e.g., "[pause]", "[whispers]"): If target is SSML, strip; if ElevenLabs, convert to audio tags (e.g., [pause] is not standard, use ... instead). Flag ambiguous directions.
   • Repeated punctuation (e.g., "!!!!", "......"): Normalise to single or double instances.
   • Smart quotes and dashes: Normalise to ASCII equivalents for compatibility.
3. Create <workdir>/original/ and copy the source file unchanged.
4. Create <workdir>/edited/ and write the sanitised text there.
5. Output filename: <source-stem>.tts-safe.txt
6. Produce a per-issue review log (markdown) listing line numbers, the original text, the replacement, and the reason.

Output / side effects

• <source-stem>.tts-safe.txt in <workdir>/edited/ — plain text ready for TTS without rendering surprises
• <source-stem>.review.md — detailed audit log of all sanitisations, with line references and reasoning
• Original source file preserved in <workdir>/original/

Safety / constraints

Non-destructive editing (brand rule): Never overwrite the user's source file. Always create original/ and edited/ subdirectories in the working directory. Default <workdir> to the source file's parent directory; allow the user to override.

Ambiguous directions: If a bracketed direction (e.g., "[meaningful pause]") is unclear or context-specific, do not strip silently. Flag it in the review log and ask the user for clarification or preference.

Preserve tone: When expanding abbreviations or removing emojis, preserve the intent (e.g., "lol" → "laugh out loud" maintains the casual tone; 😀 transcription should match context).