Microservices Orchestration
Relevant source files
The following files were used as context for generating this wiki page:
The Wikispeech server functions as an orchestration layer that coordinates multiple specialized microservices to transform raw text into synthetic speech. It manages the lifecycle of a request by routing data through text processing, lexicon lookup, symbol mapping, and various TTS (Text-to-Speech) engines.
Sources: README.md:1-10, wikispeech_server/wikispeech.py:65-75
Architecture Overview
The system architecture is decentralized, relying on a main Python Flask server that acts as a gateway and several independent backend services. These services are typically started via shell scripts and communicate over HTTP.
System Flow
The diagram below illustrates how the main server orchestrates data flow between the client and the specialized microservices.
The Gateway server handles routing, configuration loading, and audio conversion using opusenc.
Sources: start_wikispeech.sh:105-125, wikispeech_server/wikispeech.py:850-870
Component Orchestration
The orchestration is defined by configuration files and managed during runtime through dynamic module loading.
Service Discovery and Configuration
Services are defined in .conf files under the [Services] section. The main server uses these URLs to proxy requests or direct-call internal APIs.
| Service | Default URL | Purpose |
|---|---|---|
| Lexicon | http://localhost:8787 | Word pronunciation lookups. |
| Mapper | http://localhost:8771 | Translates phoneme symbol sets (e.g., IPA to X-SAMPA). |
| Matcha | http://127.0.0.1:8009 | Neural TTS engine orchestration. |
| Piper | http://localhost:8010 | Fast local neural TTS engine. |
Sources: wikispeech_server/hanna-clockwork.conf:20-25, wikispeech_server/wikispeech.py:410-420
Initialization Sequence
The start_wikispeech.sh script manages the process dependencies and startup order:
- Pronlex: Starts the lexicon server.
- Symbolset Mapper: Starts the symbol translation service.
- TTS Wrappers: Launches Matcha and Piper servers via
uvicorn. - Main Server: Launches the Wikispeech gateway after a configurable sleep period to ensure backends are ready.
Sources: start_wikispeech.sh:105-135
Data Transformation Pipeline
The server orchestrates a sequential pipeline where data is transformed across multiple formats.
Synthesis Request Flow
When a synthesis request is received, the following sequence occurs:
- Text Processing: Text is broken into paragraphs, sentences, and tokens.
- Transcription Mapping: The
piper_adapterormatcha_adaptercalls themapperservice to ensure phonemes match the specific engine's requirements. - Engine Call: The adapter sends a JSON payload containing chunks of tokens to the target TTS microservice.
- Post-Processing: The gateway converts returned WAV data to Opus and updates token timings to milliseconds.
Sources: wikispeech_server/wikispeech.py:250-300, wikispeech_server/adapters/piper_adapter.py:75-100, wikispeech_server/adapters/matcha_adapter.py:110-130
Adapter Logic
Orchestration between the gateway and synthesis engines is handled by specialized adapters. These adapters are responsible for converting the generic Wikispeech "markup" format into service-specific formats.
Mapping Functions
Adapters like piper_adapter.py implement internal mapping orchestration:
mapToPiper: Calls the mapper microservice to translate symbol sets before synthesis.utt2piper: Orchestrates the nested iteration through paragraphs, sentences, and phrases to build a chunked token list.
def mapToPiper(trans,lang,voice):
url = mapper_url+"/mapper/map/%s/%s/%s" % (from_symbol_set, to_symbol_set, quote(trans))
r = requests.get(url)
response_json = json.loads(r.text)
return response_json["result"]
Sources: wikispeech_server/adapters/piper_adapter.py:110-125, wikispeech_server/adapters/matcha_adapter.py:65-80
Error Handling in Orchestration
The orchestration layer provides several flags to manage component failures:
run_startup_tests: If set toTrue, the server verifies connectivity to MaryTTS and Pronlex on boot.load_components_on_error: Determines if the server should continue starting if a backend service is unreachable. IfFalse, the server fails fast; ifTrue, it loads the component but will return a500error upon use.
Sources: wikispeech_server/wikispeech.py:45-55, wikispeech_server/hanna-clockwork.conf:30-35
Summary
Microservices orchestration in Wikispeech-server is centered around a Python-based gateway that manages a multi-stage pipeline. By decoupling text processing, symbol mapping, and audio synthesis into independent services, the system allows for modular TTS engine integration while providing a unified API for clients. Orchestration is strictly governed by configuration files and shell-level process management.