---
title: Ishraq Quran Backend
emoji: 📖
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

# Quran Recitation Transcription API

FastAPI backend for Quran recitation transcription using the `Faster-Whisper` model fine-tuned for Quranic Arabic.

## 🚀 Quick Start

The easiest way to get started is by using the provided setup script:

```bash
# Clone the repository (if you haven't already)
git clone <repository-url>
cd ishraq-al-quran-backend

# Run the setup script
python setup.py
```

The script will check your environment, install dependencies, and create a default `.env` file.

### Manual Setup

If you prefer to set up manually:

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the server
uvicorn main:app --host 0.0.0.0 --port 7860 --reload
```

The API will be available at `http://localhost:7860`

## 📚 API Documentation

Once running, visit:
- **Swagger UI**: [http://localhost:7860/docs](http://localhost:7860/docs)
- **ReDoc**: [http://localhost:7860/redoc](http://localhost:7860/redoc)

## 🔌 Endpoints

### Health Check
- `GET /`: Basic status check
- `GET /health`: Detailed health check and model status

### Transcribe Audio
- `POST /transcribe`: Transcribe a single audio file
- `POST /transcribe-batch`: Transcribe multiple audio files simultaneously

**Supported Formats:** MP3, WAV, M4A, FLAC, OGG, WEBM, AAC, OPUS.

## ⚙️ Configuration

The application uses environment variables for configuration. You can customize these in the `.env` file (see `.env.example` for all options).

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `7860` |
| `CORS_ORIGINS` | Allowed CORS origins | `http://localhost:3000,http://localhost:5173` |
| `WHISPER_MODEL` | Hugging Face model ID | `Habib-HF/tarbiyah-ai-whisper-medium-merged` |
| `COMPUTE_TYPE` | Precision (`float32`, `float16`, `int8`) | `float32` |
| `MAX_FILE_SIZE` | Maximum upload size in MB | `100` |
| `DEVICE` | Computation device (`cuda` or `cpu`) | `auto-detect` |

## 🐳 Docker Deployment

To run the API using Docker:

```bash
# Build and start the container
docker-compose up -d
```

The Docker setup includes a persistent volume for model caching and automatic health checks.

## 🎯 Model Information

**Model**: [`Habib-HF/tarbiyah-ai-whisper-medium-merged`](https://huggingface.co/Habib-HF/tarbiyah-ai-whisper-medium-merged)
- Specifically merged and optimized for Quranic Arabic recitation styles.
- High accuracy for tajweed and specific Quranic terminology.

## 🧪 Testing & Examples

- **Test Script**: Run `python test_api.py` to verify all endpoints.
- **Client Examples**: See [client_examples.py](client_examples.py) for implementation examples in Python, JavaScript, and cURL.

## 📁 Project Structure

```
ishraq-al-quran-backend/
├── main.py           # FastAPI application & endpoints
├── config.py         # Configuration management
├── utils.py          # Processing utilities
├── setup.py          # Initial setup script
├── test_api.py       # API verification suite
├── client_examples.py # Library of client implementations
└── requirements.txt  # Project dependencies
```

---
For more information, see the [main project README](../README.md).