External Services Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Wikispeech server acts as an orchestration layer that integrates several external microservices to handle text processing, phonetic mapping, and speech synthesis. By delegating specialized tasks like lexicon lookups and acoustic modeling to external providers, the system maintains a modular architecture capable of supporting diverse languages and synthesis engines.
Integration is primarily achieved through specialized adapters located in the wikispeech_server/adapters/ directory. These adapters communicate with external REST APIs using standard HTTP protocols to transform input text into audio data.
Sources: README.md, wikispeech_server/wikispeech.py:12-30
Integration Architecture
The Wikispeech server manages a pipeline where an input request is passed through a text processor (which may call external lexicon and mapping services) before being sent to a synthesis adapter.
Core Service Components
| Service | Description | Default URL |
|---|---|---|
| Lexicon Server | Provides phonetic transcriptions for words. | http://localhost:8787 |
| Mapper Server | Maps transcriptions between different symbol sets (e.g., IPA to SAMPA). | http://localhost:8771 |
| MaryTTS | External Java-based TTS engine used for processing and synthesis. | http://localhost:59125/process |
| Piper/Matcha | Modern neural TTS services integrated via specialized adapters. | http://localhost:8010 / http://127.0.0.1:8009 |
Sources: README.md:45-55, wikispeech_server/wikispeech.py:380-400
Service Communication Flow
The following diagram illustrates how the Wikispeech server interacts with various external services during a standard synthesis request.
The server uses requests to perform synchronous calls to these services. For example, the lexicon_client.py uses GET requests to the /lexicon/lookup endpoint to retrieve phonetic data.
Sources: wikispeech_server/adapters/lexicon_client.py:45-55, wikispeech_server/wikispeech.py:382-390
Specific Service Adapters
Lexicon and Mapping Clients
The system relies on external lexicon servers for G2P (Grapheme-to-Phoneme) conversion. The Lexicon class in lexicon_client.py handles the connection and provides methods for looking up individual words or entire sentences.
The Mapper service is used to translate between phonetic alphabets, which is critical when a text processor produces one format (e.g., IPA) but the synthesis engine requires another (e.g., X-SAMPA).
Neural TTS Adapters (Piper & Matcha)
Modern neural adapters like piper_adapter.py and matcha_adapter.py follow a consistent pattern for external integration:
- Validation: A
testVoicefunction pings the external service's/voices/endpoint to ensure the requested voice is available. - Transformation: The internal Wikispeech "utterance" (utt) structure is converted into a format the external service understands (e.g.,
utt2piper). - Synthesis: A POST request is sent to the service's
/synthesize/endpoint. - Audio Retrieval: The external service returns a path to an audio file, which the Wikispeech server then downloads and converts to Opus.
Sources: wikispeech_server/adapters/piper_adapter.py:17-45, wikispeech_server/adapters/matcha_adapter.py:84-110
Configuration and Connectivity
External service locations are defined in the .conf files under the [Services] section. These configurations are loaded at runtime and used by the Voice and Textprocessor classes to initialize their respective components.
# wikispeech_server/wikispeech.py
mapper_url = config.config.get("Services", "mapper")
def mapIpaInput(ssml, textprocessor, sampa=None):
# logic to call external mapper
If a service is unavailable during the startup test, the server may fail to load the corresponding component unless load_components_on_error is set to True in the configuration.
Sources: wikispeech_server/wikispeech.py:382-385, wikispeech_server/hanna-clockwork.conf:25-35, wikispeech_server/voice.py:25-35
Audio File Post-Processing
When an external synthesis service (like Piper or Matcha) generates a WAV file, the Wikispeech server integrates with opusenc to convert the file for web delivery.
- Download: The server fetches the raw WAV from the external service's static directory.
- Conversion: It executes a system call to
opusenc. - Serving: The resulting file is stored in a temporary directory (
audio_tmpdir) and served via a static proxy.
Sources: wikispeech_server/wikispeech.py:560-590, wikispeech_server/adapters/piper_adapter.py:82-85
Conclusion
External services integration in Wikispeech Server is a decoupled system where core logic resides in the main server while phonetic and acoustic heavy-lifting is delegated. This is managed through a configuration-driven adapter pattern, allowing the system to easily expand to new TTS technologies like Piper and Matcha by simply implementing a new adapter module that follows the established communication protocols.