Request Lifecycle

Relevant source files

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

• wikispeech_server/wikispeech.py
• wikispeech_server/voice.py
• wikispeech_server/options.py
• wikispeech_simple_player.js
• wikispeech_server/adapters/piper_adapter.py
• wikispeech_server/adapters/flite_adapter.py

The Request Lifecycle in Wikispeech Server describes the end-to-end journey of a Text-to-Speech (TTS) request, starting from a client-side interface and concluding with the delivery of audio data and timing information. The system is designed as a modular pipeline that separates text processing (linguistic analysis and tokenization) from synthesis (audio generation via various TTS engines).

This lifecycle ensures that raw text or SSML input is transformed into a structured "markup" format, which is then consumed by specific voice adapters to produce high-quality speech. The architecture supports multiple languages and a variety of synthesis backends including MaryTTS, Piper, Matcha, and Flite.

Sources: wikispeech_server/wikispeech.py:168-230, wikispeech_server/options.py:5-48

Entry Points and Client Interaction

Requests typically originate from a web client using wikispeech_simple_player.js. The client identifies the content to be spoken (either as plain text or SSML) and sends a POST or GET request to the main /wikispeech endpoint.

The diagram shows the high-level flow from the initial client request through the internal service handoffs to the final response.
Sources: wikispeech_simple_player.js:106-140, wikispeech_server/wikispeech.py:171-205

API Parameters

Parameter	Type	Required	Description
lang	string	Yes	ISO 639-1 code for the target language.
input	string	Yes	The text or SSML to be synthesized.
input_type	string	No	Either text or ssml (default: text).
textprocessor	string	No	Name of a specific textprocessor configuration.
voice	string	No	Name of a specific voice engine.
output_type	string	No	Format of response, usually json or html.

Sources: wikispeech_server/options.py:9-41, wikispeech_server/wikispeech.py:207-210

Text Processing Phase

When the /wikispeech endpoint is called, the server first invokes the textproc function. This phase converts raw input into a structured "utterance" (UTT) format.

Component Pipeline

The textprocessor is composed of a list of components defined in the configuration. Each component executes a specific module and function (e.g., tokenization).

1. Tokenization: The first component typically splits text into paragraphs, sentences, phrases, and tokens.
2. Linguistic Analysis: Subsequent components may add part-of-speech (POS) tags or phonetic transcriptions to the tokens.
3. IPA Mapping: If the input is SSML with IPA alphabets, the system uses a mapper service to convert transcriptions into a format the synthesis engine understands (e.g., X-SAMPA).

Sources: wikispeech_server/wikispeech.py:382-446, wikispeech_server/wikispeech.py:449-473

Synthesis Phase

After processing, the structured markup is passed to the synthesise function. This function identifies the correct Voice object and its associated adapter.

Adapter Execution

Adapters (such as piper_adapter.py or flite_adapter.py) act as wrappers for external TTS engines.

• Data Conversion: The adapter converts the Wikispeech markup into the engine-specific format (e.g., utt2piper).
• Engine Call: The adapter makes a request to the underlying service (e.g., a Piper server via HTTP POST).
• Response Handling: The adapter receives audio and timing info, then normalizes the timing data into Wikispeech's token format.

Sources: wikispeech_server/wikispeech.py:566-611, wikispeech_server/adapters/piper_adapter.py:82-109

Audio Post-Processing

Once an adapter provides an audio source (usually a URL or a WAV file), the server performs the following:

1. Download/Capture: Retrieves the raw audio content.
2. Conversion: Uses opusenc to convert the audio to the Opus format for web efficiency.
3. Base64 Encoding: Encodes the resulting audio into a string to be included directly in the JSON response if required.
4. Token Normalization: Converts token end-times from seconds to milliseconds.

Sources: wikispeech_server/wikispeech.py:614-635, wikispeech_server/wikispeech.py:843-883

Client-Side Rendering and Playback

The client receives a JSON object containing audio_data (Base64) and a tokens list. The wikispeech_simple_player.js then:

1. Audio Injection: Creates an HTML5 <audio> element and sets its source to the data URI.
2. Highlighting Setup: Maps the token list to the original HTML content. It adds data-begin and data-dur attributes to <span> tags wrapping each word.
3. Read-Along Sync: Uses an event listener on the audio element's timeupdate (via connectTimingAndAudio) to highlight the currently spoken word by comparing audio.currentTime with token metadata.

This flow illustrates how the client-side JavaScript handles the server's response to enable synchronized text-to-speech highlighting.
Sources: wikispeech_simple_player.js:142-168, wikispeech_simple_player.js:192-264, wikispeech_simple_player.js:337-430

Summary

The Wikispeech Request Lifecycle follows a strict "Process -> Synthesize -> Convert -> Sync" pattern. By decoupling the linguistic processing from the audio generation through a standardized internal markup, the system allows for flexible configuration where different textprocessors and voices can be mixed and matched based on the target language and desired voice quality.

Sources: wikispeech_server/wikispeech.py:168-230, wikispeech_server/voice.py:15-48