Quran Recitation Feedback v2

A Streamlit web application that provides intelligent feedback on Quran recitation using AI-powered speech recognition and text comparison.

Features

• Automatic Verse Lookup: Choose Surah & Ayah numbers to fetch correct verse text from Al-Quran Cloud API
• AI-Powered Transcription: Uses specialized Arabic Quran Whisper model for accurate speech recognition
• Smart Audio Conversion: Automatically converts any audio format (WAV, MP3, FLAC, M4A, OGG) to optimal format
• Recitation Accuracy Scoring: Compares your recitation with correct text and provides detailed feedback
• Per-Word Playback: Click any word to play audio from that estimated position
• Improved Arabic Text Matching: Removes diacritics (tashkeel) for better comparison

Installation & Setup

1. Clone the repository:

git clone https://github.com/Em-Deesha/Quran-Recitation-feedback-generator.git
cd Quran-Recitation-feedback-generator

2. Install dependencies:

pip install -r requirements.txt

3. Run the application:

streamlit run app.py

4. Access the app:
   • Local URL: http://localhost:8501
   • Network URL: http://your-ip:8501

Usage

1. Select a verse: Choose Surah (1-114) and Ayah number, then click "Fetch verse from API"
2. Upload audio: Upload your recitation in any supported format
3. Get feedback: The app will transcribe your recitation and compare it with the correct text
4. Review results: See accuracy score, differences, and use per-word playback

Technical Details

• Model: Uses tarteel-ai/whisper-base-ar-quran for Arabic speech recognition
• Audio Processing: Automatic conversion to 16kHz WAV format for optimal transcription
• Text Comparison: Advanced Arabic text normalization and word-level comparison
• Deployment: Ready for deployment on Streamlit Cloud, Heroku, or other platforms

Deployment Options

Streamlit Cloud (Recommended)

1. Push your code to GitHub
2. Connect your GitHub account to Streamlit Cloud
3. Deploy directly from your repository

Docker Deployment

# Build Docker image
docker build -t quran-feedback .

# Run container
docker run -p 8501:8501 quran-feedback

Heroku Deployment

1. Add Procfile with: web: streamlit run app.py --server.port=$PORT --server.address=0.0.0.0
2. Deploy using Heroku CLI or GitHub integration

Notes

• First run downloads the AI model (~1GB) - this may take time
• Per-word playback uses proportional alignment (estimated timing)
• For production deployment, consider using GPU instances for faster transcription
• The app automatically handles audio format conversion and optimization

Contributing

Feel free to submit issues, feature requests, or pull requests to improve the application.

License

This project is open source and available under the MIT License.