Files

stephan 2669af6cf1 docs: Update README with container registry workflow

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.

2025-12-04 22:48:33 +01:00

4.2 KiB

Raw Blame History

AudioEngineHub

AudioEngineHub is a local-first, modular, multi-engine Text-to-Speech (TTS) server designed for homelabs and automation. It provides a single, unified API to interact with various TTS engines like Piper and StyleTTS.

Features

Multi-Engine Support: Easily switch between different TTS engines.
Configurable Engines: Activate or deactivate engines on the fly via a simple configuration file.
Caching: Caches generated audio to save resources and provide faster responses for repeated requests.
Dockerized: Runs in a containerized environment for easy setup and dependency management.
Automatic Port Finding: Automatically finds and uses a free port when building locally.
Container Registry Support: Pre-configured to push to and pull from a container registry.

Getting Started

This guide covers local development. For information on using the container registry, see the "Container Registry" section below.

Prerequisites

Local Development Setup

Clone the repository:

git clone <repository_url>
cd AudioEngineHub

Configure the environment: Create a .env file by copying the example file:
```
cp .env.example .env
```
Open the .env file and configure the ACTIVE_ENGINES list to include the engines you want to use. For example:
```
ACTIVE_ENGINES='["piper", "styletts"]'
```
Build and start the container: Use the make dev-up command to build the Docker image from your local source and start the service.
```
make dev-up
```
This command will automatically find a free port, build the image, and run the application.
Note: For the most reliable port detection, it is recommended to run the command with sudo:
```
sudo make dev-up
```

Container Registry

The project is configured to work with the container registry at git.wlkns.org.

Pushing an Image

Log in to the Registry: You only need to do this once per machine.
```
docker login git.wlkns.org
```
Push the Image: This command will build your image, tag it correctly, and push it to the registry.
```
make push
```

Pulling and Running an Image

Pull the Image: To download the latest image from the registry:
```
make pull
```
Run the Image: This command will start the application using the pre-built image from the registry (pulling it if necessary).
```
make up
```

Usage

Endpoints

POST /tts: The main endpoint to synthesize text to speech.
GET /health: Check the health of the API and the status of the loaded engines.
GET /engines: List the currently active engines.
GET /models: List the available models for each active engine. _ GET /speakers: List the available speakers for a given engine and model.

Makefile Commands

The project includes a Makefile with several commands to simplify development and management:

make dev-up: Build the image from local source and start the application. Recommended for development.
make up: Start the application using the image from the container registry (pulls if not present).
make down: Stop the application container(s).
make logs: View the application logs.
make health-check: Run a sanity check to ensure the deployed container is healthy and all engines are "ok".
make pull: Pull the latest image from the container registry.
make push: Build, tag, and push the image to the container registry.
make test: Run the pytest test suite.
make help: Display a list of all available commands.

Configuration

The application is configured through the .env file in the root of the project.

ACTIVE_ENGINES: A comma-separated list of strings specifying which TTS engines to activate. Available engines are defined in app/main.py.
HOST: The host address for the server (defaults to 0.0.0.0).
PORT: The internal port for the server (defaults to 8000).
IMAGE_NAME: The name of the Docker image to build (defaults to audioenginehub).

4.2 KiB Raw Blame History