| 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
- Read the source text file and validate encoding.
- 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., "user@example.com" → "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.
- Create
<workdir>/original/ and copy the source file unchanged.
- Create
<workdir>/edited/ and write the sanitised text there.
- Output filename:
<source-stem>.tts-safe.txt
- 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).
