API Reference

Document

The primary class for creating and managing SSMD/SSML documents.

.. autoclass:: ssmd.Document :members: :undoc-members: :show-inheritance:

Construction Methods:

.. automethod:: ssmd.Document.init

.. automethod:: ssmd.Document.from_ssml

.. automethod:: ssmd.Document.from_text

Building Methods:

.. automethod:: ssmd.Document.add

.. automethod:: ssmd.Document.add_sentence

.. automethod:: ssmd.Document.add_paragraph

Export Methods:

.. automethod:: ssmd.Document.to_ssml

.. automethod:: ssmd.Document.to_ssmd

.. automethod:: ssmd.Document.to_text

Properties:

.. autoproperty:: ssmd.Document.ssmd

.. autoproperty:: ssmd.Document.config

.. autoproperty:: ssmd.Document.capabilities

.. autoproperty:: ssmd.Document.source

.. autoproperty:: ssmd.Document.voice_bindings

.. autoproperty:: ssmd.Document.pause_defaults

Document parses YAML front matter by default. doc.ssmd is the body-only SSMD; doc.source and doc.to_ssmd(include_header=True) include a deterministic header when one was present. Pass parse_yaml_header=False when literal leading front matter syntax is required.

Sentence/list APIs such as sentences(), split(), indexing, and len() operate on unversioned legacy and SSMD 0.8 documents. SSMD 0.9 documents, including those created by Document.from_ssml(), reject sentence-level APIs; use structural parsing and explicit sentence spans instead.

Iteration:

.. automethod:: ssmd.Document.sentences

.. automethod:: ssmd.Document.iter

.. automethod:: ssmd.Document.len

List-like Interface:

.. automethod:: ssmd.Document.getitem

.. automethod:: ssmd.Document.setitem

.. automethod:: ssmd.Document.delitem

.. automethod:: ssmd.Document.iadd

Editing Methods:

.. automethod:: ssmd.Document.insert

.. automethod:: ssmd.Document.remove

.. automethod:: ssmd.Document.clear

.. automethod:: ssmd.Document.replace

Advanced Methods:

.. automethod:: ssmd.Document.merge

.. automethod:: ssmd.Document.split

.. automethod:: ssmd.Document.get_fragment

TTSCapabilities

Define TTS engine capabilities for automatic feature filtering.

.. autoclass:: ssmd.TTSCapabilities :members: :undoc-members: :show-inheritance:

SSMLParser

Parse SSML and convert to SSMD format.

.. autoclass:: ssmd.SSMLParser :members: :undoc-members: :show-inheritance:

Parser Functions

Extract structured data from SSMD text.

parse_structure() is the preferred structural API for strict SSMD 0.9. It returns clean text, annotations, structural events, front matter, and diagnostics without sentence detection. Use parse_spans() when only clean text and annotation spans are needed. Both preserve the offset-based metadata needed by downstream TTS normalization and sentence segmentation.

parse_paragraphs(), parse_sentences(), parse_segments(), and parse_voice_blocks() are sentence-/segment-oriented compatibility APIs for unversioned legacy input and SSMD 0.8; do not use them with strict 0.9 documents. See Parser API for dialect guidance.

.. autofunction:: ssmd.parse_paragraphs

.. autofunction:: ssmd.parse_sentences

.. autofunction:: ssmd.parse_segments

.. autofunction:: ssmd.parse_voice_blocks

.. autofunction:: ssmd.parse_spans

.. autofunction:: ssmd.parse_structure

.. autofunction:: ssmd.iter_sentences_spans

.. autofunction:: ssmd.lint

Conversion Functions

Convert between SSMD, SSML, and plain text.

SentenceSpanLike

Protocol for external sentence boundaries supplied to Document.to_ssml() or ssmd.to_ssml(). Implementations expose zero-based, half-open char_start and char_end offsets in the structural clean-text coordinate space.

Sentence (alias: SSMDSentence)

Represents a sentence with voice context and segments.

.. autoclass:: ssmd.Sentence :members: :undoc-members: :show-inheritance:

Segment (alias: SSMDSegment)

Represents a text segment with metadata.

.. autoclass:: ssmd.Segment :members: :undoc-members: :show-inheritance:

VoiceAttrs

Voice configuration attributes.

.. autoclass:: ssmd.VoiceAttrs :members: :undoc-members: :show-inheritance:

ProsodyAttrs

Prosody (volume, rate, pitch) attributes.

.. autoclass:: ssmd.ProsodyAttrs :members: :undoc-members: :show-inheritance:

BreakAttrs

Pause/break attributes.

.. autoclass:: ssmd.BreakAttrs :members: :undoc-members: :show-inheritance:

SayAsAttrs

Say-as interpretation attributes.

.. autoclass:: ssmd.SayAsAttrs :members: :undoc-members: :show-inheritance:

PhonemeAttrs

Phonetic pronunciation attributes.

.. autoclass:: ssmd.PhonemeAttrs :members: :undoc-members: :show-inheritance:

AudioAttrs

Audio file attributes.

.. autoclass:: ssmd.AudioAttrs :members: :undoc-members: :show-inheritance:

StructuralEvent

A zero-width break, mark, or paragraph event in clean-text boundary coordinates.

.. autoclass:: ssmd.StructuralEvent :members:

ParseStructureResult

The sentence-neutral result returned by parse_structure().

.. autoclass:: ssmd.ParseStructureResult :members:

SSML Parser

Internal SSML to SSMD parsing engine.

.. automodule:: ssmd.ssml_parser :members: :undoc-members: :show-inheritance:

Document Module

Document container implementation.

.. automodule:: ssmd.document :members: :undoc-members: :show-inheritance:

Parser Module

SSMD parsing functions for extracting structured data.

.. automodule:: ssmd.parser :members: :undoc-members: :show-inheritance:

Segment Module

Segment class for representing text portions with attributes.

.. automodule:: ssmd.segment :members: :undoc-members: :show-inheritance:

Sentence Module

Sentence class for representing collections of segments.

.. automodule:: ssmd.sentence :members: :undoc-members: :show-inheritance:

Types Module

Data types used throughout the SSMD library.

.. automodule:: ssmd.types :members: :undoc-members: :show-inheritance:

Utilities

Helper functions for SSML processing.

.. automodule:: ssmd.utils :members: :undoc-members: :show-inheritance: