Emotional TTS
Getting Started

Installation

Step-by-step guide to set up the Emotional TTS system on your machine or server using Docker.

Requirements

RequirementsMinRecommended
Docker20.10+Latest
Docker Composev2.0+Latest
NVIDIA Driver525+535+
GPUCUDA-capableNVIDIA RTX 3080+ / A100
RAM8 GB16+ GB
Disk Space10 GB20+ GB
OSLinux (Ubuntu 20.04+)Ubuntu 22.04+

NVIDIA GPU Required for Production

While CPU inference is possible, it is extremely slow. For production use, an NVIDIA GPU with CUDA 12.1 support is strongly recommended.

1. Clone the Repository

git clone <repository-url>
cd tts

2. Environment Variables

Create a .env file in the project root:

.envenv
# TTS API Configuration
API_PORT=8080
FILE_TTL_SECONDS=7200
MAX_WORKERS=2
MAX_ITEMS_PER_JOB=20

# Frontend (docs portal)
NEXT_PUBLIC_API_BASE_URL=http://localhost:8080

# GPU Settings
NVIDIA_VISIBLE_DEVICES=all

3. Build with Docker

Build the backend imagebash
cd Docker
docker build -t emotional-tts-api .
The first build will take several minutes as it downloads PyTorch and all dependencies.

4. Run the Backend

With GPU supportbash
docker run -d \
  --name emotional-tts \
  --gpus all \
  -p 8080:8000 \
  -v $(pwd)/checkpoints:/app/checkpoints \
  emotional-tts-api
CPU-only (slower)bash
docker run -d \
  --name emotional-tts \
  -p 8080:8000 \
  -v $(pwd)/checkpoints:/app/checkpoints \
  emotional-tts-api

5. Docker Compose (Recommended)

Use Docker Compose for a complete setup with the docs portal:

docker-compose.ymlyaml
services:
  tts-api:
    build: ./Docker
    ports:
      - "8080:8000"
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    volumes:
      - ./Docker/checkpoints:/app/checkpoints
    environment:
      - FILE_TTL_SECONDS=7200
      - MAX_WORKERS=2
    restart: unless-stopped

  docs-portal:
    build: ./docs-portal
    ports:
      - "3100:3000"
    depends_on:
      - tts-api
    restart: unless-stopped
Start everythingbash
docker compose up --build -d
docker compose ps
docker compose logs -f tts-api

6. Health Check

curl http://localhost:8080/health

Expected response:

{
  "status": "ok",
  "model_loaded": true,
  "active_jobs": 0,
  "cuda": true
}

7. Model Checkpoints

The model checkpoint files must be placed in the Docker/checkpoints/ directory. The directory should contain:

checkpoints/
├── config.yaml
├── bigvgan_discriminator.pth
├── bigvgan_generator.pth
├── bpe.model
├── dvae.pth
├── gpt.pth
└── ...

8. Linux Server Deployment

For production deployment on a Linux server with Nginx:

Nginx reverse proxy confignginx
server {
    listen 80;
    server_name your-domain.com;

    # Docs portal
    location / {
        proxy_pass http://localhost:3100;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
    }

    # TTS API
    location /api/ {
        rewrite ^/api/(.*) /$1 break;
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_read_timeout 300s;
        client_max_body_size 50M;
    }
}

9. Verify Installation

Test emotion listingbash
curl http://localhost:8080/emotions
Test TTS generationbash
curl -X POST http://localhost:8080/stream_tts_vec \
  -F "speaker_file=@sample_speaker.wav" \
  -F "text=Hello, this is a test." \
  -F "emotion=happy" \
  --output test_output.wav

Common Issues

CUDA not available

Make sure NVIDIA Container Toolkit is installed:sudo apt install nvidia-container-toolkit && sudo systemctl restart docker

Model not loading

Verify checkpoint files exist in the correct directory and the config.yaml is present.

Port already in use

Change the port mapping: docker run -p 9000:8000 ...