README.md

metadata

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:

# 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:

# 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
• 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:

# 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

• 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 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.