DrKO999/darija-transcription

Darija Transcription & Diarization API

A FastAPI-based service for transcribing and diarizing Moroccan Darija audio using OpenAI Whisper with LoRA fine-tuning and pyannote speaker diarization.

Features

✨ Speech-to-Text: Transcribes Darija audio using Whisper + LoRA fine-tuned model 👥 Speaker Diarization: Identifies and labels different speakers 📤 Multiple Export Formats: JSON, VTT, SRT, TXT 🚀 GPU-Accelerated: Optimized for CUDA devices 🔄 Retry Logic: Automatic retries for robust downloads

Deploy to Hugging Face Spaces 🤗

Step 1: Prepare Your GitHub Repository

1. 1.Create a new GitHub repository (or use an existing one)
2. 2.Clone it locally:

   git clone https://github.com/YOUR_USERNAME/darija-transcription.git
   cd darija-transcription

1. 1.Add these files to your repo:
2. 2.app.py ✓
3. 3.requirements.txt ✓
4. 4.Dockerfile ✓
5. 5..gitignore ✓
6. 6.README.md (this file)

1. 1.Commit and push:

   git add .
   git commit -m "Initial commit: Darija transcription API"
   git push origin main

Step 2: Create a Hugging Face Space

1. 1.Go to huggingface.co/spaces
2. 2.Click "Create new Space"
3. 3.Fill in:
4. 4.Space name: darija-transcription (or your preferred name)
5. 5.License: Apache 2.0 (or your choice)
6. 6.Space SDK: Docker
7. 7.Space hardware: GPU T4 (free tier: ~20 hrs/week)
8. 8.Private or Public: Choose your preference

1. 1.Click "Create Space"

Step 3: Connect Your Repository

1. 1.In your newly created Space, click "Settings" (⚙️ icon)
2. 2.Under "Linked Repository", paste your GitHub repo URL:

   https://github.com/YOUR_USERNAME/darija-transcription

1. 1.Click "Link repository"

The Space will automatically build and deploy from your GitHub repo!

Step 4: Add Environment Variables (Important!)

1. 1.Go to Settings → "Repository secrets"
2. 2.Add HF_TOKEN:
3. 3.Generate a token at huggingface.co/settings/tokens
4. 4.Make sure it has "repo" permissions
5. 5.Copy and paste it as HF_TOKEN secret

This allows the pyannote diarization model to download (it requires authentication).

Local Development

Prerequisites

• —Python 3.10+
• —CUDA 12.1 (or CPU-only mode)
• —~20 GB disk space for models

Installation

1. 1.Clone the repo:

   git clone https://github.com/YOUR_USERNAME/darija-transcription.git
   cd darija-transcription

1. 1.Create a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 1.Install dependencies:

   pip install -r requirements.txt

1. 1.Create .env file:

   echo "HF_TOKEN=your_huggingface_token_here" > .env

Get your token from huggingface.co/settings/tokens

1. 1.Run the app:

   python app.py

The API will be available at http://localhost:8000

API Usage

Health Check

curl http://localhost:8000/health

Transcribe Audio

curl -X POST "http://localhost:8000/transcribe" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio.wav",
    "num_speakers": 2,
    "merge_same_speaker": true
  }'

Request Parameters:

Response:

{
  "utterances": [
    {
      "start": 0.5,
      "end": 2.3,
      "text": "السلام عليكم ورحمة الله وبركاته",
      "speaker": "SPEAKER_00",
      "confidence": 0.95
    },
    {
      "start": 2.8,
      "end": 5.1,
      "text": "عليكم السلام ورحمة الله وبركاته",
      "speaker": "SPEAKER_01",
      "confidence": 0.92
    }
  ],
  "total_duration": 5.1,
  "num_speakers": 2,
  "language": "ar",
  "processing_time_seconds": 12.4
}

Export to Different Formats

# Export to VTT (WebVTT subtitles)
curl -X POST "http://localhost:8000/transcribe_with_export?format=vtt" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio.wav"
  }' | jq -r '.content'

# Export to SRT (SubRip subtitles)
curl -X POST "http://localhost:8000/transcribe_with_export?format=srt" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio.wav"
  }' | jq -r '.content'

# Export to TXT (plain text)
curl -X POST "http://localhost:8000/transcribe_with_export?format=txt" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio.wav"
  }' | jq -r '.content'

Interactive Documentation

Once the API is running, visit:

• —Swagger UI: http://localhost:8000/docs
• —ReDoc: http://localhost:8000/redoc

You can test endpoints directly from the browser!

Performance Notes

First Deployment

• —Model loading takes ~3-5 minutes on first startup
• —Subsequent requests are much faster

Free Tier Limitations (HF Spaces)

• —GPU available: ~20 hours/week (T4)
• —Space sleeps after 48 hours of inactivity
• —Cold starts take longer

Optimize Performance

To reduce model size (trades accuracy for speed):

# In app.py, change to:
BASE_MODEL = "openai/whisper-base"  # 150MB instead of 3GB

Troubleshooting

"HF_TOKEN not found"

• —Make sure you added HF_TOKEN to Space secrets
• —Token needs "repo" access level at minimum

"CUDA out of memory"

• —Reduce chunk size in app.py:

  chunk_length_s=15,  # Reduce from 30

Models not downloading

• —Check your HF token is valid: huggingface-cli login
• —Ensure you have enough disk space

Slow first request

• —Normal! Models are loading from cache on first startup
• —Takes 3-5 minutes; subsequent requests are faster

Project Structure

darija-transcription/
├── app.py                 # FastAPI application
├── requirements.txt       # Python dependencies
├── Dockerfile            # Docker configuration for HF Spaces
├── .gitignore           # Git ignore rules
└── README.md            # This file

Models Used

• —ASR: OpenAI Whisper Large V3 Turbo + LoRA fine-tune for Darija
• —Diarization: pyannote/speaker-diarization-3.1
• —Hardware: CUDA GPU (T4 on HF Spaces)

License

Apache 2.0 — Feel free to use, modify, and distribute!

Support

For issues or questions:

1. 1.Check the troubleshooting section
2. 2.Review API logs in Space runtime
3. 3.Open an issue on GitHub

Built with ❤️ for Darija speakers