Troubleshooting & Common Issues
Relevant source files
The following files were used as context for generating this wiki page:
The Wikispeech server is a complex orchestration of multiple microservices, including lexicon servers, symbol set mappers, and various TTS engines like MaryTTS, Piper, or Matcha. Troubleshooting typically involves verifying the connectivity between these services, ensuring local dependencies like opusenc are installed, and validating that the voice and textprocessor configurations correctly reference active backend endpoints.
This guide covers common failure points during installation, configuration, and runtime, as well as the diagnostic tools provided in the repository to identify the root cause of issues.
Dependency and Environment Issues
One of the most common causes of failure is a missing system-level dependency or an incorrectly initialized Python environment.
Missing opus-tools
The server requires opusenc to convert synthesized WAV files into Opus format for web delivery. The server performs a check at startup and will terminate if the binary is not found.
Sources: wikispeech_server/wikispeech.py:46-55
Virtual Environment Initialization
All server-related code must be run from within the project's virtual environment. Failure to activate the environment results in missing package errors for Flask, Requests, and other dependencies.
Sources: README.md:18-19, README.md:25-26
Directory Permissions
The server writes temporary audio files to a directory defined by audio_tmpdir. If this directory does not exist or is not writeable by the user running the process, synthesis will fail.
Sources: wikispeech_server/wikispeech.py:1082-1097
| Issue | Symptom | Resolution |
|---|---|---|
Missing opusenc | "ERROR: opusenc was not found" on startup | sudo apt install opus-tools |
| Audio Cache | Stale or corrupt audio files | Run bash clear_audio_cache.sh |
| Temp Directory | "audio_tmpdir does not exist or is not writeable" | Create wikispeech_server/tmp manually or check permissions |
Service Connectivity and Startup Errors
The Wikispeech server acts as a gateway. If the underlying microservices are unavailable, the server may fail to load components or fail during synthesis requests.
Startup Test Failures
By default, the server can be configured to run startup tests that verify connectivity to MaryTTS, Lexicon servers, and Symbol Set Mappers. If quit_on_error is set to True in the configuration, the server will shut down immediately if these tests fail.
Sources: wikispeech_server/config-sample.conf:34-36, wikispeech_server/wikispeech.py:34-40
Loading Components on Error
If a backend service is offline, the server may fail to load a specific Textprocessor or Voice. This behavior can be toggled using the load_components_on_error setting. If set to True, the server loads the components anyway, but subsequent API calls will return a 500 Internal Server Error.
Sources: wikispeech_server/config-sample.conf:39-40, wikispeech_server/textprocessor.py:23-28
The following diagram illustrates the dependency flow during a standard synthesis request:
Detailed connectivity issues often stem from the services highlighted in orange.
Sources: wikispeech_server/wikispeech.py:431-480, start_wikispeech.sh:130-145
Configuration Diagnostics
Errors in .conf files or JSON voice configurations are a frequent source of "Voice not defined" or "Language not supported" errors.
Configuration Validation
Users can test a specific configuration file by passing it as a command-line argument to the server binary.
Sources: README.md:61-64
Voice and Textprocessor Mismatches
If the lang parameter in an API call does not match a loaded voice or textprocessor, the server returns an error message.
- Common Error:
ERROR: Textprocessor [name] not defined for language [lang] - Common Error:
ERROR: voice [name] not defined for language [lang]
Sources: wikispeech_server/wikispeech.py:397-399, wikispeech_server/wikispeech.py:560-562
Duplicate Definitions
When loading JSON configuration files, the server checks for duplicate names for voices or textprocessors. If a name is defined more than once across configuration files, the server will terminate with a fatal error.
Sources: wikispeech_server/wikispeech.py:688-692, wikispeech_server/wikispeech.py:702-706
API Troubleshooting
API issues can be diagnosed by observing the response types or using the built-in diagnostic endpoints.
Diagnostic Endpoints
The following endpoints help verify what the server has successfully loaded:
| Endpoint | Description |
|---|---|
/ping | Returns "wikispeech" to verify the Flask app is alive. |
/version | Returns build information and startup timestamp. |
/languages | Lists languages supported by both synthesis and textprocessing. |
/synthesis/voices | Lists all successfully loaded synthesis voices. |
/textprocessing/textprocessors | Lists all successfully loaded textprocessors. |
Sources: wikispeech_server/wikispeech.py:100-155, wikispeech_server/templates/usage.html:43-55
Token Alignment Issues
In some cases, the TTS engine might return tokens that do not match the input text (e.g., due to normalization or character handling). The server includes a internal check checkInputAndOutputTokens to attempt to correct these alignments, but if they differ significantly, a warning message is appended to the JSON result.
Sources: wikispeech_server/wikispeech.py:755-760
Testing and Logs
For developers, the primary tool for troubleshooting is the build_and_test.sh script, which mimics the CI environment.
Using build_and_test.sh
This script attempts to kill existing instances of all sub-services and restart them in a clean state. If the script fails, it indicates that the current environment cannot satisfy the system's integration requirements.
Sources: build_and_test.sh:17-21
Log Files
When using start_wikispeech.sh, logs for all microservices are directed to a log directory (default: ~/wikispeech-server/log).
wikispeech.log: Main server logic and routing errors.mapper.log: Symbol mapping failures.pronlex.log: Lexicon lookup issues.matcha.log/piper.log: Specific TTS engine synthesis errors.
Sources: start_wikispeech.sh:130-150
Conclusion
Most issues in the Wikispeech server are related to the availability of external microservices or missing local dependencies like opus-tools. By utilizing the diagnostic endpoints (/languages, /voices) and checking the centralized log files, administrators can pinpoint whether a failure is occurring in the orchestration layer or within a specific adapter component.