- Add XTTS v2 configuration to .env.example
- Refactor Dockerfile to multi-stage build with CUDA 12.1 support
- Update Makefile with Kokoro and XTTS test environment targets
- Refactor Piper engine (app/engines/piper.py) to use python module execution
- Add comprehensive documentation for Kokoro and XTTS plans
- Add helper scripts and patches for build process
- Updated README.md to include XTTS engine details and model setup instructions.
- Added section on OpenAI API compatibility in README.md.
- Updated API_DOCUMENTATION.md to include the new POST /v1/audio/speech endpoint.
- Refactor existing tests to use a shared mock engine fixture.
- Add tests for unsupported response formats.
- Add tests for engine synthesis failures.
- Add tests for 'engine:model_id' parsing in the 'model' parameter.
- Add tests for different audio response formats (opus, flac).
- Implements POST /v1/audio/speech endpoint (OpenAI API compatible).
- Integrates Kokoro and XTTS engines (including dependencies and implementations).
- Updates main application to register new engines and router.
- Adds unit tests for OpenAI compatibility.
- Updates requirements.txt for new engines.
This commit fixes all critical bugs identified in the Piper engine that were
causing server crashes, hung processes, resource leaks, and audio synthesis
failures.
## Bug Fixes
**Bug #1: Invalid --stdin CLI flag**
- Removed non-existent --stdin flag from piper command
- Piper reads stdin by default, flag was causing undefined behavior
**Bug #2: Temp file race conditions**
- Replaced NamedTemporaryFile context manager with tempfile.mkstemp()
- Prevents file handle locking issues on some systems
**Bug #3: Missing process timeouts**
- Added asyncio.wait_for() with 30s timeout for piper synthesis
- Added 60s timeout for ffmpeg conversion
- Prevents hung processes from accumulating and exhausting memory
**Bug #4: Orphaned temp files**
- Implemented comprehensive temp file tracking list
- Added cleanup in finally block to ensure all temp files are removed
- Prevents /tmp/ from filling with orphaned audio files
**Bug #5: FFmpeg error suppression**
- Removed quiet=True from ffmpeg calls
- Added capture_stdout and capture_stderr for full error context
- Improved error messages with actual ffmpeg output
**Bug #6: No config file validation**
- Added upfront validation for .onnx and .onnx.json files
- Validates speaker exists in config before synthesis
- Provides clear error messages with available speakers list
**Bug #7: Poor error context**
- Added comprehensive logging with DEBUG/INFO/ERROR/WARNING levels
- Error messages now include full command, model, speaker, text preview
- Added success logging with file sizes and synthesis details
## New Features
**Cache Versioning System**
- Added CACHE_VERSION constant to automatically invalidate cache on bug fixes
- Old cached files (with bugs) are automatically bypassed
- Includes cleanup_old_cache_files() utility for removing stale cache
- Version history documented in code comments
**Configurable Timeouts**
- PIPER_TIMEOUT_SECONDS: defaults to 30s (configurable via .env)
- FFMPEG_TIMEOUT_SECONDS: defaults to 60s (configurable via .env)
**Path Fixes**
- Fixed audio file path validation in main.py (Bug causing 404s)
- Updated AUDIO_CACHE_DIR to use relative paths for better portability
**Documentation**
- Added CLAUDE.md for future AI assistant context
- Updated .env.example with new timeout configuration options
## Testing
- ✅ Health check passed
- ✅ Synthesis working correctly
- ✅ No temp file leaks
- ✅ No hung processes
- ✅ Cache versioning prevents old buggy files from being served
- ✅ Voice preview in wizard working correctly
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit adds a crucial "Downloading Models" section to the README.md.
- Explains that models are not included in the Docker image and must be downloaded manually.
- Provides detailed instructions for downloading Piper models from Hugging Face, including an example for the voice.
- Clarifies the expected directory structure for placing the downloaded models.
- Mentions that StyleTTS is currently a placeholder and does not require model downloads.
This commit updates the main README.md file to reflect the recent changes related to the container registry integration.
- Clarifies the difference between Starting development environment by pulling image from registry...
export IMAGE_NAME=audio-engine-hub && \
export REGISTRY=git.wlkns.org && \
export USERNAME=stephan && \
export TAG=latest && \
docker compose up -d (for registry images) and Starting development environment (local build) on port 8000... (for local builds).
- Adds a dedicated "Container Registry" section explaining the push/pull workflow.
- Updates the "Makefile Commands" section with the new , , and targets.
This commit integrates support for pushing and pulling Docker images from a container registry and enhances the Makefile for a more flexible development workflow.
Key changes include:
- **Container Registry Configuration:** Added and variables to the Makefile and updated and targets to correctly tag and push images to the configured registry.
- **Docker Compose Registry Integration:** Modified to use the image from the registry by default instead of building locally.
- **Makefile Workflow Enhancements:**
- Introduced a target (Pulling image git.wlkns.org/stephan/audio-engine-hub:latest from registry...
docker pull git.wlkns.org/stephan/audio-engine-hub:latest) for explicitly downloading images from the registry.
- Modified the target (Starting development environment by pulling image from registry...
export IMAGE_NAME=audio-engine-hub && \
export REGISTRY=git.wlkns.org && \
export USERNAME=stephan && \
export TAG=latest && \
docker compose up -d) to use the registry image.
- Added a target (Starting development environment (local build) on port 8000...) for local development, which explicitly builds the image from source () before starting the service.
- Updated and GNU bash, Version 5.1.16(1)-release (x86_64-pc-linux-gnu)
Diese Shellkommandos sind intern definiert. Geben Sie »help« ein, um diese
Liste zu sehen. Geben Sie »help Name« ein, um die Beschreibung der Funktion
»Name« zu sehen. Geben Sie »info bash« ein, um die vollständige Dokumentation
zu sehen. Geben Sie »man -k« oder »info« ein, um detaillierte Beschreibungen
der Shellkommandos zu sehen.
Ein Stern (*) neben dem Namen kennzeichnet deaktivierte Kommandos.
Jobbezeichnung [&] history [-c] [-d Offset] [n] oder history -anrw [Dateiname] oder histor>
(( Ausdruck )) if Kommandos; then Kommandos; [ elif Kommandos; then Kommandos; ]... [ >
. Dateiname [Argumente] jobs [-lnprs] [Jobbezeichnung ...] or jobs -x Kommando [Arg]
: kill [-s Signalname | -n Signalnummer | -Signalname] pid | jobspec ... >
[ Argument... ] let Argument [Argument ...]
[[ Ausdruck ]] local [Option] Name[=Wert] ...
alias [-p] [Name[=Wert] ... ] logout [n]
bg [Jobbezeichnung ...] mapfile [-d Begrenzer] [-n Anzahl] [-O Quelle] [-s Anzahl] [-t] [-u fd]>
bind [-lpsvPSVX] [-m Tastaturtabelle] [-f Dateiname] [-q Name] [-u Name]> popd [-n] [+N | -N]
break [n] printf [-v var] Format [Argumente]
builtin [Shell-Kommando [Argument ...]] pushd [-n] [+N | -N | Verzeichnis]
caller [Ausdruck] pwd [-LP]
case Wort in [Muster [| Muster]...) Kommandos ;;]... esac read [-ers] [-a Feld] [-d Begrenzer] [-i Text] [-n Zeichenanzahl] [-N Z>
cd [-L|[-P [-e]] [-@]] [Verzeichnis] readarray [-d Begrenzer] [-n Anzahl] [-O Quelle] [-s Anzahl] [-t] >
command [-pVv] Kommando [Argument ...] readonly [-aAf] [Name[=Wert] ...] oder readonly -p
compgen [-abcdefgjksuv] [-o option] [-A action] [-G globpat] [-W wordlis> return [n]
complete [-abcdefgjksuv] [-pr] [-DEI] [-o option] [-A action] [-G globpa> select Name [in Wortliste ... ;] do Kommandos; done
compopt [-o|+o Option] [-DEI] [Name ...] set [-abefhkmnptuvxBCHP] [-o Option] [--] [Argument ...]
continue [n] shift [n]
coproc [Name] Kommando [Umleitungen] shopt [-pqsu] [-o] [Optionsname ...]
declare [-aAfFgiIlnrtux] [-p] [Name[=Wert] …] source Dateiname [Argumente]
dirs [-clpv] [+N] [-N] suspend [-f]
disown [-h] [-ar] [Jobbezeichnung ... | pid ...] test [Ausdruck]
echo [-neE] [Argument ...] time [-p] Pipeline
enable [-a] [-dnps] [-f Dateiname] [Name ...] times
eval [Argument ...] trap [-lp] [[Argument] Signalbezeichnung ...]
exec [-cl] [-a Name] [Befehl [Argument …]] [Umleitung …] true
exit [n] type [-afptP] Name [Name ...]
export [-fn] [Name[=Wert] ...] oder export -p typeset [-aAfFgiIlnrtux] [-p] Name[=Wert] …
false ulimit [-SHabcdefiklmnpqrstuvxPT] [Grenze]
fc [-e Editor] [-lnr] [Anfang] [Ende] oder fc -s [Muster=Ersetzung] [Kom> umask [-p] [-S] [Modus]
fg [Jobbezeichnung] unalias [-a] Name [Name ...]
for Name [in Wortliste ... ] ; do Kommandos; done unset [-f] [-v] [-n] [NAME ...]
for (( Ausdruck1; Ausdruck2; Ausdruck3 )); do Kommandos; done until Kommandos; do Kommandos; done
function Name { Kommandos ; } oder Name () { Kommandos ; } variables - Namen und Bedeutung einiger Shell-Variablen
getopts optstring name [arg ...] wait [-fn] [-p var] [id ...]
hash [-lr] [-p Pfadname] [-dt] [Name ...] while Kommandos; do Kommandos; done
help [-dms] [Muster ...] { Kommandos ; } targets accordingly.
- **Session Resume Update:** Updated to document the container registry integration.
This commit fixes several critical issues that prevented the service from deploying correctly and loading the TTS models.
- **Fix Model Loading:** Corrected the volume mount path in to point to the correct source directory. The engine code was also updated to use absolute paths () inside the container, making the model loading mechanism robust.
- **Update Session Resume:** The has been updated to reflect the final debugging steps and the successful resolution of all issues.
