MaryTTS Adapter

Relevant source files

The following files were used as context for generating this wiki page:

• wikispeech_server/adapters/marytts_adapter.py
• wikispeech_server/conf/voice_config_marytts.json
• wikispeech_server/wikispeech.py
• wikispeech_server/textprocessor.py
• wikispeech_server/voice.py
• wikispeech_server/adapters/README.md

The MaryTTS Adapter is a critical component within the Wikispeech server that facilitates integration with the third-party MaryTTS (Modular Architecture for Resynthesis of Speech) system. It acts as a bridge, enabling the Wikispeech server to utilize MaryTTS for both advanced text processing (phonetization and intonation analysis) and speech synthesis.

The adapter is implemented as a Python module that handles the conversion between Wikispeech's internal data structures and the MaryXML format required by the MaryTTS server. It supports multiple languages, including English, Swedish, Arabic, and Norwegian, by managing locales and symbol set mappings via an external mapper service.

Sources: wikispeech_server/adapters/README.md:1-25, wikispeech_server/adapters/marytts_adapter.py:1-50

Architecture and Core Functions

The MaryTTS Adapter operates as a set of callable functions defined in the system configuration. It is categorized into two primary phases: text processing and synthesis.

Functional Workflow

The following diagram illustrates the high-level interaction between the Wikispeech server, the MaryTTS Adapter, and the remote MaryTTS service.

The adapter uses requests to communicate with the MaryTTS service URL, which is defined in the server's global configuration.

Sources: wikispeech_server/adapters/marytts_adapter.py:15-20, wikispeech_server/wikispeech.py:530-580

Text Processing (marytts_preproc)

The marytts_preproc function handles the initial transformation of raw text or SSML into a structured "utterance" (utt) format.

• Locale Mapping: Converts Wikispeech language codes to MaryTTS locales (e.g., en becomes en_US, nb becomes no).
• Input Handling: Supports both TEXT and SSML. For SSML, it performs symbol mapping to ensure transcriptions are compatible with MaryTTS's expectations.
• Remote Call: Sends a GET request to MaryTTS with OUTPUT_TYPE=INTONATION. This allows MaryTTS to perform phonetization while still allowing Wikispeech to modify the results later (e.g., via lexicon lookup).
• Data Conversion: Uses maryxml2utt to parse the returned MaryXML and build the internal Wikispeech utterance structure.

Sources: wikispeech_server/adapters/marytts_adapter.py:54-94, wikispeech_server/conf/voice_config_marytts.json:2-15

Speech Synthesis (synthesise)

The synthesise function is responsible for generating audio and precise timing information for tokens.

Synthesis Process

1. Format Conversion: Converts the Wikispeech utterance (containing sentences and phrases) into a MaryXML string using utt2maryxml.
2. Timing Extraction: Calls MaryTTS with OUTPUT_TYPE=REALISED_ACOUSTPARAMS to obtain detailed token durations.
3. Token Parsing: The maryxml2tokensET function parses the resulting XML to extract orthography and calculate end times for every token in milliseconds.
4. Audio Generation: Prepares a GET request URL for OUTPUT_TYPE=AUDIO with the WAVE_FILE format.

Symbol Mapping and Transcription

Because different TTS engines often use varying phonetic symbol sets (e.g., different versions of SAMPA), the adapter utilizes a Mapper service.

Function	Purpose
mapperMapToMary	Converts Wikispeech SAMPA to MaryTTS-specific SAMPA before sending data.
mapperMapFromMary	Converts MaryTTS phonetic output back to Wikispeech's internal format.
mapSsmlTranscriptionsToMary	Specifically handles <phoneme> tags within SSML inputs.

For Swedish, the adapter includes specific regex logic to handle pre-r allophones (e.g., distinguishing E and {) which MaryTTS's older phoneme sets may not natively differentiate.

Sources: wikispeech_server/adapters/marytts_adapter.py:168-190, wikispeech_server/adapters/marytts_adapter.py:534-600

Configuration Data Model

The MaryTTS adapter is configured via JSON files. Each configuration defines how the adapter is called and which mapping sets to use.

Example Configuration Snippet

{
    "module": "adapters.marytts_adapter",
    "call": "marytts_preproc",
    "mapper": {
        "from": "sv-se_ws-sampa",
        "to": "sv-se_sampa_mary"
    }
}

Voice Parameters

Voices using this adapter require specific metadata:

• name: The technical name of the MaryTTS voice (e.g., stts_sv_nst-hsmm).
• locale: The MaryTTS locale (e.g., en_US, no).
• engine: Always set to marytts.
• adapter: Path to the adapter module (adapters.marytts_adapter).

Sources: wikispeech_server/conf/voice_config_marytts.json:1-120, wikispeech_server/voice.py:14-40

Conclusion

The MaryTTS Adapter is a sophisticated bridge that enables Wikispeech to leverage the rich linguistic capabilities of MaryTTS. By handling complex MaryXML transformations and integrating with an external mapping service, it ensures that Wikispeech can provide high-quality, timed speech synthesis across multiple languages while maintaining a consistent internal data model.