Wartilho

Wartilho is an Android Quran reader and on-device AI recitation assistant by Mohamed Marzouk.

Wartilho focuses on a native Uthmani Quran reading experience, Quran audio workflows, and local AI models for recitation recognition and Tajweed-oriented feedback. The app is designed so recitation audio can be processed on the phone without cloud inference.

Public source, non-commercial license. Commercial use requires written permission from Mohamed Marzouk.

Status

This repository is an early public source release. It contains the current Android app, embedded mobile ONNX models, the unified training notebook, evaluation tooling, and documentation. Raw private training audio, signing keys, and private experimental checkpoints are not included.

Features

• Native Android app built with Kotlin and Jetpack Compose.
• Uthmani Quran page rendering with selectable Mushaf font packs.
• Surah, juz, hizb, rub, search, bookmarks, tafsir/translation, sharing, and audio playback flows.
• Quran audio playback built around Media3, reciter catalogs, ayah timing databases, background playback, and Android media controls.
• On-device ASR model embedded as ONNX.
• On-device Tajweed verifier and duration models embedded as ONNX.
• Unified ASR/Tajweed training notebook.
• Evaluation script and generated metrics/graphs for the embedded Android ONNX model.

Repository Layout

android/      Android source, resources, Quran assets, and embedded ONNX models
Audio/        Reciter metadata and ayah timing database packages
dataset/      Lightweight Quran text metadata used by tooling
docs/         Architecture notes, runtime notes, evaluation, and release notes
tools/        Quran/content utilities and model evaluation tools
train/        Unified ASR/Tajweed training notebook

AI Runtime

The Android runtime currently ships:

android/app/src/main/assets/models/wartilho_asr_conformer_ctc_features.onnx
android/app/src/main/assets/models/wartilho_tajweed_verifier.onnx
android/app/src/main/assets/models/wartilho_tajweed_duration.onnx
android/app/src/main/assets/models/vocab.json

Runtime pipeline:

flowchart LR
    A["Microphone PCM"] --> B["16 kHz mono audio"]
    B --> C["Log-mel feature extraction"]
    C --> D["Conformer CTC ASR ONNX"]
    D --> E["Quran-aware decoding and alignment"]
    D --> F["Backbone features"]
    F --> G["Tajweed verifier ONNX"]
    F --> H["Duration head ONNX"]
    E --> I["Word-level recitation feedback"]
    G --> J["Rule-level Tajweed feedback"]
    H --> J

Loading

Training and Android inference must preserve the same feature contract:

• Sample rate: 16 kHz
• Mono PCM
• Mel bins: 80
• FFT size: 512
• Window length: 400
• Hop length: 160
• Log-mel power spectrogram

Evaluation

The embedded Android ASR ONNX model was evaluated locally on real ayah MP3 recordings from held-out readers with deterministic stratified sampling across readers and duration buckets.

Latest evaluation:

• Samples: 300
• Average audio duration: 8.57s
• CER: 1.21%
• WER: 5.82%
• Exact ayah match: 68.00%
• Average ONNX inference: 23.17 ms/sample
• P95 ONNX inference: 63.73 ms/sample

Graphs and full per-sample results:

• Android ONNX ASR Evaluation
• Evaluation JSON

Re-run locally:

python tools/evaluate_android_onnx_asr.py `
  --dataset-root E:\APPs\Wartilho\dataset `
  --limit 300 `
  --max-duration 30

Training

Training source:

train/quran_asr_tajweed_unified.ipynb

Private training data is expected outside this repository:

dataset/
  all_ayat.json
  transcripts.tsv
  audio_data/

Private checkpoints, signing keys, and newer experimental retraining artifacts are intentionally excluded.

Release

The signed APK is distributed through GitHub Releases, not committed into the source tree.

• Latest tag: v0.1.0
• Release notes: docs/RELEASE_NOTES.md

Build

Android Studio is the recommended development environment.

cd android
$env:JAVA_HOME = "C:\Program Files\Android\Android Studio\jbr"
.\gradlew.bat :app:assembleRelease

Signing requires your own private keystore and should be done outside the public source tree or through a private release workflow. Do not commit keystores, passwords, generated signed APKs, or local signing configuration.

License

Copyright (c) 2026 Mohamed Marzouk.

Released under the Wartilho Non-Commercial Source-Available License v1.0. Non-commercial personal, educational, and research use is allowed. Commercial use, resale, paid SaaS use, app-store redistribution for revenue, or use inside a commercial product requires a separate written license.

See LICENSE.