stephan
2669af6cf1
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.
117 lines
4.2 KiB
Markdown
117 lines
4.2 KiB
Markdown
# 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
|
|
|
|
- [Docker](https://docs.docker.com/get-docker/)
|
|
- [Docker Compose](https://docs.docker.com/compose/install/)
|
|
|
|
### Local Development Setup
|
|
|
|
1. **Clone the repository:**
|
|
```bash
|
|
git clone <repository_url>
|
|
cd AudioEngineHub
|
|
```
|
|
|
|
2. **Configure the environment:**
|
|
Create a `.env` file by copying the example file:
|
|
```bash
|
|
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"]'
|
|
```
|
|
|
|
3. **Build and start the container:**
|
|
Use the `make dev-up` command to build the Docker image from your local source and start the service.
|
|
```bash
|
|
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`:
|
|
> ```bash
|
|
> sudo make dev-up
|
|
> ```
|
|
|
|
## Container Registry
|
|
|
|
The project is configured to work with the container registry at `git.wlkns.org`.
|
|
|
|
### Pushing an Image
|
|
|
|
1. **Log in to the Registry:**
|
|
You only need to do this once per machine.
|
|
```bash
|
|
docker login git.wlkns.org
|
|
```
|
|
|
|
2. **Push the Image:**
|
|
This command will build your image, tag it correctly, and push it to the registry.
|
|
```bash
|
|
make push
|
|
```
|
|
|
|
### Pulling and Running an Image
|
|
|
|
1. **Pull the Image:**
|
|
To download the latest image from the registry:
|
|
```bash
|
|
make pull
|
|
```
|
|
|
|
2. **Run the Image:**
|
|
This command will start the application using the pre-built image from the registry (pulling it if necessary).
|
|
```bash
|
|
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`).
|