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
• Docker Compose

Local Development Setup

1. Clone the repository:

   git clone <repository_url>
   cd AudioEngineHub
   

2. 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"]'
   

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.

   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

1. Log in to the Registry: You only need to do this once per machine.

   docker login git.wlkns.org
   

2. 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

1. Pull the Image: To download the latest image from the registry:

   make pull
   

2. 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).