ssml-conversion

SSML Conversion

Convert plain-text scripts into W3C-compliant SSML by wrapping content in <speak> and inferring semantic markup from textual cues. The output is a valid XML file suitable for any SSML-compatible TTS engine.

When to use

• You have a plain-text script and need SSML for a TTS engine that supports SSML natively (Google Cloud, AWS Polly, Azure)
• You want to add pacing (<break>), emphasis, and prosody hints without manual markup
• You need W3C-standard output for portability across TTS systems

Inputs to gather

• Source text file (path)
• Optional: working directory for output (defaults to source file's parent)
• Optional: prosody preferences (rate, pitch, volume baseline — applied as defaults in <prosody>)

Procedure

1. Read the source text file and validate UTF-8 encoding.
2. Scan for cues and infer markup:
   • ALL CAPS text → wrap in <emphasis level="strong">
   • Ellipsis ... → insert <break time="500ms"/> before the next word
   • Numbers and dates (e.g., "2024-05-03", "123456") → wrap in <say-as interpret-as="date" or "digits" as appropriate
   • Abbreviations (e.g., "Mr.", "USA", "PhD") → expand or wrap in <sub alias="expanded-form">abbrev</sub>
   • Quoted speech (single or double quotes) → optional: wrap in <emphasis level="moderate"> or note in decisions log
3. Create <workdir>/original/ and copy the source file unchanged.
4. Create <workdir>/edited/ and write the SSML document there.
5. Wrap all content in <speak> root element and validate as well-formed XML.
6. Output filename: <source-stem>.ssml.xml
7. Produce a decisions log (markdown) listing all inferred markup decisions.

Output / side effects

• <source-stem>.ssml.xml in <workdir>/edited/ — the complete SSML document ready for TTS
• <source-stem>.decisions.md — explains which cues triggered which tags and why
• 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.

SSML validation: Use a standard XML validator (e.g., xmllint) to ensure the output is well-formed before returning. Report any validation errors clearly.

Reference: https://www.w3.org/TR/speech-synthesis11/