Transcription API with WhisperX and Diarization

A high-performance API for audio-to-text transcription with speaker identification (diarization). The project uses WhisperX for accurate transcription and time alignment, and is fully packaged with Docker and Docker Compose for easy deployment in any environment.

✨ Key Features

High-Accuracy Transcription: Uses the Whisper large-v2 model via whisperx for top-quality transcriptions.
Speaker Diarization: Identifies and labels who spoke and when, thanks to integration with pyannote.audio.
CPU and GPU Optimized: Automatically detects if a CUDA-enabled GPU is available to accelerate the process. On CPU, it is optimized to use multiple threads.
Easy to Deploy: Thanks to Docker, configuration is minimal. You only need one command to get the API running.
Robust API: Built with FastAPI, it offers a modern, fast interface with automatic documentation.
Efficient Memory Management: Models are loaded only once when the application starts, and memory is managed for stable performance.

🛠️ Tech Stack

Backend: Python, FastAPI
Transcription: WhisperX
Diarization: Pyannote.audio
Containerization: Docker, Docker Compose
AI Inference: PyTorch, CTranslate2

🚀 Getting Started

Follow these steps to get the API up and running on your local machine.

Prerequisites

Docker and Docker Compose installed.
Git to clone the repository.
A Hugging Face access token: Diarization requires this to download the pyannote model.
1. Create an account on Hugging Face.
2. Go to your profile -> Settings -> Access Tokens.
3. Create a new token with the read role.
4. Copy the token.

Installation and Execution

Clone the repository:

git clone [https://github.com/your-username/transcription-api.git](https://github.com/your-username/transcription-api.git)
cd transcription-api

Configure your Hugging Face token: Open the docker-compose.yml file and replace the token_de_hugging_face value with your actual token.

services:
  transcription-api:
    build: .
    ports:
      - "8002:8000"
    restart: unless-stopped
    environment:
      # Paste the token you copied from Hugging Face here
      - HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # <-- PASTE IT HERE

Build and start the container: This command will build the Docker image (it may take several minutes the first time) and start the API.
```
docker-compose up --build
```
If you want it to run in the background, add the -d flag:
```
docker-compose up --build -d
```

Done! The API will be available at http://localhost:8002.

🎤 How to Use the API

Send a POST request to the /transcribir/ endpoint with your audio file.

Endpoint: `POST /transcribir/`

Description: Receives an audio file and returns the transcription with identified segments and speakers.
Request Body: multipart/form-data with an audio_file field.

Example with `curl`

Open your terminal and run the following command, replacing /path/to/your/audio.mp3 with the actual path to your audio file.

curl -X 'POST' \
  'http://localhost:8002/transcribir/' \
  -F 'audio_file=@/path/to/your/audio.mp3'

Example of Successful Response (JSON)

You will receive a JSON object with a segments key containing a list of the detected text fragments. Each segment includes the text, start and end time, and the identified speaker.

{
  "segments": [
    {
      "start": 0.53,
      "end": 2.77,
      "text": " Hello, this is a test audio.",
      "speaker": "SPEAKER_01"
    },
    {
      "start": 3.12,
      "end": 5.45,
      "text": " And this is a second intervention to verify the diarization.",
      "speaker": "SPEAKER_00"
    }
  ]
}

⚙️ Advanced Configuration

Using GPU (NVIDIA)

If your machine has an NVIDIA GPU compatible with CUDA and the drivers installed, you can greatly accelerate the process.

Make sure you have the NVIDIA Container Toolkit installed.

In the docker-compose.yml file, uncomment the deploy section:

# --- OPTIONAL SECTION FOR NVIDIA GPU ---
deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

Restart the container: docker-compose up --build -d.

The application will automatically detect the GPU and use float16 for optimal performance.

File Structure

.
├── docker-compose.yml  # Orchestrates the container deployment.
├── Dockerfile          # Defines the Docker image for the application.
├── main.py             # API logic with FastAPI and WhisperX.
└── requirements.txt    # Python dependencies.

📄 License

This project is distributed under the MIT License. See the LICENSE file for the full terms.