guilheogumucio/tts-alignment

🎙️ Forced Alignment Service

TRUE forced alignment using Aeneas.

Overview

This service provides word-level forced alignment between audio files and your provided text. Aeneas performs TRUE forced alignment using TTS synthesis + MFCC/DTW:

• —✅ Uses YOUR exact text directly
• —✅ Does NOT re-transcribe the audio
• —✅ Aligns the words you provide with the audio timing
• —✅ Simple setup - no complex acoustic models required

This is ideal for audiobooks where you already have the text and need accurate word-level timestamps.

Security

To enable API key authentication, set the ALIGNMENT_API_KEY environment variable:

• —When set, all alignment requests must include a valid api_key parameter
• —The health endpoint returns authEnabled: true when authentication is enabled

Technology Stack

API Endpoints

POST /call/align (Gradio API)

Align audio with text to get word-level timestamps.

Request (Gradio format):

{
  "data": [
    "https://r2.example.com/audio.mp3",
    "Chapter One. It was the best of times...",
    "en",
    "507f1f77bcf86cd799439011",
    0,
    "your-api-key"
  ]
}

Note: The api_key (last parameter) is required if ALIGNMENT_API_KEY is configured on the server.

Response:

{
  "success": true,
  "metadata": {
    "engine": "aeneas",
    "ttsEngine": "espeak",
    "language": "en",
    "duration": 12.5,
    "wordCount": 42,
    "confidence": 0.9,
    "processingTime": 3.2,
    "audioId": "507f1f77bcf86cd799439011",
    "paragraphIndex": 0
  },
  "segments": [
    {
      "id": "w0",
      "word": "Chapter",
      "start": 0.5,
      "end": 1.1,
      "confidence": 0.9
    },
    { "id": "w1", "word": "One", "start": 1.15, "end": 1.8, "confidence": 0.9 }
  ]
}

GET /health

Health check endpoint.

Response:

{
  "status": "ok",
  "service": "alignment",
  "engine": "aeneas",
  "version": "1.7.x",
  "authEnabled": true
}

Note: authEnabled indicates whether API key authentication is required.

Supported Languages

Local Development

# Build Docker image
docker build -t alignment-service .

# Run container
docker run -p 7860:7860 alignment-service

# Access UI
open http://localhost:7860

Deployment to Hugging Face Spaces

1. 1.Create a new Space at https://huggingface.co/spaces
2. 2.Select "Docker" SDK
3. 3.Choose "CPU Basic" hardware (FREE)
4. 4.Upload files:
5. 5.Dockerfile
6. 6.app.py
7. 7.requirements.txt
8. 8.README.md
9. 9.Wait for build (~5-10 minutes first time)

Performance

Integration with Main API

The NestJS API calls this service via HTTP (Gradio format):

const response = await axios.post(
  "https://your-alignment-service.hf.space/call/align",
  {
    data: [
      audioUrl,
      paragraphText,
      "en",
      audioId,
      paragraphIndex,
      process.env.ALIGNMENT_API_KEY,
    ],
  },
);
// Response: { data: [jsonStringResult] }
const result = JSON.parse(response.data.data[0]);

Limitations

• —CPU-only inference
• —Best for audio < 10 minutes
• —Text must match audio closely for accurate alignment
• —May queue during high load (max 20 concurrent)

Cost Summary

Total Monthly Cost: $0