Piper & Matcha (Neural) Adapters
Relevant source files
The following files were used as context for generating this wiki page:
The Piper and Matcha adapters are specialized modules within the Wikispeech server designed to enable high-quality neural text-to-speech (TTS) synthesis. These adapters act as intermediaries between the core Wikispeech server and third-party neural TTS engines, specifically Piper (a fast, local neural TTS) and Matcha-TTS (an encoder-decoder based model).
Their primary purpose is to transform processed linguistic data (utterances) into a format compatible with these neural engines, handle phonetic mapping via external symbol set mappers, and manage the resulting audio output. By implementing a standardized synthesise interface, these adapters allow the Wikispeech server to leverage advanced neural models while maintaining a consistent internal architecture for text processing and audio delivery.
Sources: wikispeech_server/adapters/README.md:1-12, wikispeech_server/adapters/piper_adapter.py:1-15, wikispeech_server/adapters/matcha_adapter.py:1-15
Architecture and Integration
The neural adapters are integrated into the Wikispeech server as dynamically loaded modules. The core server identifies the appropriate adapter based on the configuration provided in voice JSON files.
Data Flow Overview
The following diagram illustrates how the core Wikispeech server interacts with the Piper and Matcha adapters and their respective backend services.
The flow starts with the Wikispeech Core sending an utterance structure to the adapter. The adapter iterates through paragraphs, sentences, and phrases to extract tokens. If phonemes are present, it uses the Mapper service to translate them to the internal symbol set required by the specific neural model. Finally, it sends a POST request to the external TTS engine (Piper or Matcha).
Sources: wikispeech_server/wikispeech.py:650-685, wikispeech_server/adapters/piper_adapter.py:65-85, wikispeech_server/adapters/matcha_adapter.py:65-85
Functional Components
Both Piper and Matcha adapters share a near-identical structure, differing primarily in the base URLs used for their respective backend services.
Key Adapter Functions
| Function | Description |
|---|---|
testVoice(voice_config) | Validates the connection to the backend TTS service and checks if the requested voice name exists. |
utt2piper / utt2matcha | flattens the nested Wikispeech utterance structure into a simplified list of token dictionaries containing orthography and mapped phonemes. |
synthesise(...) | The primary entry point. Orchestrates the transformation, service call, and response parsing. |
mapToPiper / mapToMatcha | Interfaces with the external Symbol Set Mapper to convert internal transcriptions to the neural engine's required format. |
Sources: wikispeech_server/adapters/piper_adapter.py:17-105, wikispeech_server/adapters/matcha_adapter.py:17-105
Utterance Transformation Logic
The adapters transform the Wikispeech internal "Utterance" format into a "chunks" format required by the neural engines. This involves extracting orth (orthography), trans (transcription), and handling language markers.
# From piper_adapter.py (Lines 50-63)
def utt2piper(input,lang,voice_config):
chunks = []
for p0 in input["paragraphs"]:
for s in p0["sentences"]:
for p in s["phrases"]:
chunk = []
for t in p["tokens"]:
for w in t["words"]:
token = {"orth": w["orth"]}
if "trans" in w:
trans = mapToPiper(w['trans'],lang,voice_config)
token["phonemes"] = trans
chunk.append(token)
chunks.append(chunk)
return chunks
Sources: wikispeech_server/adapters/piper_adapter.py:50-63, wikispeech_server/adapters/matcha_adapter.py:50-63
Service Configuration
The neural adapters rely on environment variables and central configuration files to locate their backend services.
| Service | Default Port | Description |
|---|---|---|
| Mapper | 8771 | Converts between different phonetic symbol sets (e.g., Sampa to Piper-internal). |
| Matcha | 8009 | The Matcha-TTS wrapper service handling neural synthesis requests. |
| Piper | 8010 | The Piper-TTS wrapper service for fast local neural synthesis. |
Sources: start_wikispeech.sh:130-145, wikispeech_server/adapters/piper_adapter.py:12-13, wikispeech_server/adapters/matcha_adapter.py:12-13
Phoneme Mapping
Neural engines often use specific phonetic alphabets. The adapters utilize the mapper_url to perform synchronous translation of transcriptions.
The mapping process extracts the from and to symbol sets from the voice_config and performs a URL-encoded request to the mapper service.
Sources: wikispeech_server/adapters/piper_adapter.py:107-130, wikispeech_server/adapters/matcha_adapter.py:107-130
Synthesis Workflow
When synthesise is called, the adapter performs a POST request to the /synthesize/ endpoint of the neural service.
-
Request Parameters:
voice: The name of the specific neural model.input_type: Set to "tokens".input: The flattened list of tokens generated byutt2neural.speaking_rate: Speed control (default 1.0).speaker_id: Used for multi-speaker models (default -1).return_type: Always "json".
-
Response Handling:
- The backend returns a JSON object containing an
audiofilename and a list oftokenswith timing information. - The adapter constructs a full URL for the audio file, typically served from the backend's
/static/directory. - Token timing labels are normalized (e.g.,
end_timetoendtime).
- The backend returns a JSON object containing an
Sources: wikispeech_server/adapters/piper_adapter.py:65-88, wikispeech_server/adapters/matcha_adapter.py:65-88
Conclusion
The Piper and Matcha neural adapters provide the necessary abstraction to include state-of-the-art neural synthesis in Wikispeech. By handling the complexities of phonetic mapping and structural transformation, they enable the system to switch between different neural backends seamlessly via simple configuration changes. This architecture ensures that the core Wikispeech logic remains decoupled from the specific implementation details of the underlying neural TTS engines.
Sources: wikispeech_server/adapters/README.md:20-30, wikispeech_server/voice.py:20-35