Adapter System Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Adapter System in the Wikispeech server is a modular architecture designed to enable the integration of third-party text processing and synthesis engines. By decoupling the core server logic from specific Text-to-Speech (TTS) implementations, the system allows for flexible configuration of various backends such as MaryTTS, Matcha, and Piper.
Adapters act as translation layers that convert internal Wikispeech data structures (like the "utterance" dict) into formats required by external services and vice versa. They are dynamically loaded based on voice configuration files, enabling the server to support multiple languages and voices through specialized modules.
Sources: wikispeech_server/adapters/README.md:1-5, wikispeech_server/wikispeech.py:550-570
Architecture and Components
The adapter system consists of two primary types: Textprocessing Adapters and Synthesis Adapters. These are managed through the Textprocessor and Voice classes, which load adapter modules dynamically.
Component Logic
- Textprocessing Adapters: Responsible for pre-processing text (tokenization, normalization). A textprocessing adapter must implement a function specified by the "call" parameter in the configuration file.
- Synthesis Adapters: Responsible for converting processed text into audio. Every synthesis adapter must implement a
synthesisefunction. - Dynamic Loading: Modules are imported using
util.import_modulebased on theadapterormodulepath defined in the JSON configuration.
Sources: wikispeech_server/adapters/README.md:7-12, wikispeech_server/textprocessor.py:65-75, wikispeech_server/voice.py:28-35
Data Flow for Text-to-Speech
The following diagram illustrates how a request flows through the adapters:
The textprocessing step loads the module and sends input through the defined "call" function, returning a dictionary containing processed text. This dictionary is then passed to the synthesis function of the voice's adapter.
Sources: wikispeech_server/adapters/README.md:18-32, wikispeech_server/wikispeech.py:410-430
Synthesis Adapters
Synthesis adapters interface with specific TTS engines. They take processed tokens and return a pointer to generated audio along with timing information for tokens.
Common Implementation Patterns
Adapters like matcha_adapter.py and piper_adapter.py follow a consistent structure:
- testVoice: Validates that the external service (e.g., Matcha or Piper server) is reachable and the requested voice is available.
- utt2[engine]: A helper function that transforms the internal Wikispeech "utterance" (utt) structure into a list of tokens compatible with the target engine.
- synthesise: The main entry point that posts tokens to the external service's API and handles the response.
Sources: wikispeech_server/adapters/matcha_adapter.py:18-35, 48-60, wikispeech_server/adapters/piper_adapter.py:18-35, 48-60
Adapter Function Signatures
| Function | Required Arguments | Returns |
|---|---|---|
synthesise | lang, voice_config, input, hostname, speaker_id, speaking_rate | (audio_url, tokens) |
testVoice | voice_config | None (Raises VoiceException on failure) |
Sources: wikispeech_server/adapters/matcha_adapter.py:62-65, wikispeech_server/voice.py:32-35
Textprocessing Adapters
Textprocessing adapters are often composed of multiple components. The Textprocessor class iterates through these components, which can include lexicon clients or specific adapter modules like marytts_adapter.
Processing Chain
The textproc function in wikispeech.py manages the chain of components:
- It looks up the
Textprocessorby name and language. - It loops over the
componentslist in the configuration. - It calls the specified function (e.g.,
marytts_preproc) for each component. - Each component modifies the "utterance" structure before passing it to the next.
Mapping and Symbol Sets
Adapters frequently use a Mapper client to translate phonemes between different symbol sets (e.g., from ws-sampa to an engine-specific format).
- mapTo[Engine]: Translates phonemes from the internal Wikispeech format to the external engine's format before synthesis.
- mapFrom[Engine]: Translates engine-returned phonemes back to the internal format (often for display or debugging).
The mapping service URL is retrieved from the Services section of the server configuration.
Sources: wikispeech_server/adapters/matcha_adapter.py:102-120, wikispeech_server/voice.py:40-45
Summary
The adapter system provides a standardized interface for extending Wikispeech with new TTS capabilities. By implementing the synthesise and designated textprocessing functions, developers can add support for diverse engines. The system's reliance on JSON-based configuration allows for fine-grained control over which adapters are used for specific languages and voices, ensuring the server remains engine-agnostic.
Sources: wikispeech_server/adapters/README.md:1-5, wikispeech_server/wikispeech.py:730-750