Repository navigation
Memorize (احفظ) and Prayer Corrector: offline, private Quran recitation tracking - #3934
Open
amrfahmyt1983-wq wants to merge 33 commits into
Open
amrfahmyt1983-wq wants to merge 33 commits into
amrfahmyt1983-wq wants to merge 33 commits into
Conversation
Memorize (احفظ) hides the words of the mushaf page from a chosen ayah and reveals them as the user recites, entirely on the device: a streaming phoneme recognizer (sherpa-onnx, Quran-Lab zipformer_p-arabic-v3.1 int8, downloaded once or imported from files) and a tracker that aligns what is heard with the expected words. Audio is processed in memory only; nothing is recorded or sent. The prayer corrector (مصحح الصلاة) marks a wrong word without revealing it and, when the user is stuck, gives the next word in Husary's voice (Murattal, Muallim or Mujawwad), one word at a time until they continue. It also follows a passage hands-free during salah, ignoring Al-Fatiha and the prayer's phrases and continuing across rak'ahs. - feature/memorize: session controller, microphone foreground service, page masks, hint voice, settings, model download and import - feature/memorize/tracker: pure Kotlin tracker, salah flow and hint scheduler, golden-tested against the reference implementation - feature/memorize/engine-sherpa: speech engine (sherpa-onnx AAR fetched by tools/memorize/fetch_sherpa_onnx.sh) and an on-device benchmark - app, common: word-level glyphs for madani pages, word hiding, recitation slot hooks, audio bar hint button, Husary Muallim and Mujawwad reciters - tools/memorize: builders for glyph types, lexicon and timing packs, and the on-device test runner (Firebase Test Lab or adb)
… the model license - Add the speech model's license (Quran-Lab No-Profit License 1.2) verbatim as feature/memorize/MODEL_LICENSE, and link the model, its mirror and the pinned versions from the feature's README. - Follow TESTING_STRATEGY.md in the session tests: MemorizeSessionController and LexiconRepository take their scope, dispatcher and clock through forTest(), and the tests run on runTest's virtual time (no sleeps, no runBlocking, Turbine for the failure event). The 13 controller tests now take about half a second. - The on-device session test plays 26 clips in real time: Husary and eight other reciters and styles (QUD, CC-BY-4.0), non-professional readers including real wording mistakes (sobolev210, MIT) and non-native readers from eight countries (RetaSy), reporting what is revealed, mistakes, hints and latency per clip and per group. - Test audio is no longer kept in git: tools/memorize/stage_test_clips.py stages it, with the model, into build/memorize-testlab for the test APKs.
Feedback from testing on a tablet: - Sessions go on into the next suras (taraweeh) until the user ends them: the next suras are loaded ahead and hidden, and the basmala between suras is expected. A session only finishes at the end of the Quran. - A floating mic shows when the session listens (blue, pulsing), pauses and resumes it, ends it, and plays back the recording; it can be dragged out of the way. - Hints: a word gotten wrong again is given at the reciter's next pause; after three single words, hints give the rest of the ayah (if no longer than the line) or of the line, as the page type in use breaks its lines. - Every page type is handled the same: glyph types are worked out from the page type's own glyph boxes and the text (this reproduces the madani types for all 6,236 ayat). Marks are backgrounds under the words, so colored mushafs keep their colors. - Optional recording of the user's recitation (off by default; always or ask each time), per sura or per session, kept until deleted or replaced by a newer recording of the same place. Played back from the audio bar or the mic; My recordings lists, plays, exports (audio, word alignment and a NeMo manifest) and deletes them. Recordings stay in no-backup storage. - Automatic downloads (model and hint voice, as needed) and a bulk "download for offline use"; the start dialog offers the whole Quran. - The model can be imported one file at a time, or from its .zip; files are recognized by their SHA-256.
- The floating mic is on the reading screen before a session too (green): tap to start, long press to choose memorize or salah. It turns blue and pulses once listening. - A session starts where the user starts reciting, anywhere from three pages before the page on screen to three after it. Nothing is hidden until then, and the page doesn't move. Reciting something that isn't there marks the first word on screen (and, while memorizing, gives it after the delay); prayer speech and Al-Fatiha in salah aren't marks. - The reading screen tells the recitation presenter which pages are on screen (one, or two side by side).
Before it is known where the user started, every word around the page on screen is hidden; once found, the words before the start are shown again.
Add a "Swap volume keys" setting under "Volume key navigation" (enabled only when that is on). Off by default, keeping today's behaviour of volume up going to the previous page; when on, volume up goes to the next page and volume down to the previous one. This suits single button Bluetooth page turners that only send volume up. The key-to-pager mapping is extracted into VolumeKeyNavigation so it can be unit tested against the real page/position mapping.
Tested by replaying whole prayers (recordings from mosques) through the session: in a few pages of Quran, two short words match nearly anything, Al-Fatiha included, so a session in salah could start at the wrong place and give hints from there. - The start is three words in a row heard confidently, more if they are short ones; of equally good places, the one nearest the page on screen (the Quran repeats some phrases, e.g. Hud 50, 61 and 84). A mistake within the first words after it means the start was wrong: it is looked for again. - In salah the passage's start isn't looked for while Al-Fatiha is being recited, and a recitation elsewhere is only marked after a few words. - In salah hints stay one word at a time and stop after three in a row: a silence that lasts is more often ruku or sujud than being stuck.
A session may start anywhere around the page on screen: name and split the recording from the first word the user recited, not from where the session looked for the start.
The count of phonemes since Al-Fatiha started at Int.MAX_VALUE and wrapped negative on the first addition, so a session started after Al-Fatiha (e.g. once the imam had finished it) never looked for the passage: it stayed in the Al-Fatiha phase for good. It now saturates. Also adds an opt-in diagnostics trace (adb shell setprop log.tag.MemorizeTrace DEBUG): what the session heard, the start search, salah phases, events and hint decisions, which found this.
…phone Before a hint is spoken, and a second after a mistake before its mark is shown, a larger model (muhdur's Tilawi FastConformer, CC-BY-4.0) listens again to the last 8 seconds the user said. If the word was said after all, nothing is corrected; a dropped hint counts the word as recited. In the lab: false hints in mosque prayers -28 % (-43 % while reciting), tlog clips with false marks -57 %, recall unchanged, 0 of 400 real stalls wrongly dropped. - Off by default; a 92 MB download from the model's own repository, pinned and checksummed. It runs on the sherpa-onnx already in the app (as a raw-audio CTC model), so the APK doesn't grow: CheckGraph adapts the graph once on the phone (3 nodes in front, weights untouched), byte-identical to the lab's onnx conversion and checked by SHA-256. The model store can now convert a verified download (or import). - The comparison rules (CheckText) are ported from the lab and reproduce its tables for all 1,025 pieces and 77,433 words, from the Tanzil text published with the model and the app's lexicon. - DoubleCheckAdvice recommends it on phones with ~6 GB of memory or more and a 64-bit processor, then by the time a check takes on the phone (not above 1.5 s). The setting says whether and why; where it suits, it is also offered with the first model download and in Download for offline use. - The check runs on its own thread, never hears the hints, and is released with the session. Settings and dialogs in English and Arabic.
With sherpa-onnx 1.13.8, a second model decoding in the speech engine's
process corrupts the engine's state. On a Mi 11, the session went deaf for
20-45 s after a check, until its stream started over: a whole prayer
followed 135-289 words instead of 586. This happened whether or not the two
models decoded at the same time, and with or without a lock. On a desktop,
the two failed outright when they did.
The model now runs in DoubleCheckService (":doublecheck"), reached over a
Messenger. If that process goes away, the checks hear nothing and the
session corrects as it would without them. The app skips its own setup in
secondary processes.
On a device, as the app runs it: the model is downloaded as published and converted there, it is loaded in its own process, it finds words of Al-Husary's Al-Mulk 1-5 in the last seconds (not a word from another sura), and the speech engine hears exactly the same with checks running next to it as without. Also passes the session test its (absent) double-check.
The memorize presenter kept the reading screen's callbacks after the screen closed. The presenter itself outlives the screen, because the audio bar's collectors (never cancelled, an existing leak) keep it. So every reading screen opened was kept whole, with its page images: 31 MB each, found with LeakCanary. Over a morning of sessions on a Mi 11, the release build grew to 1.4 GB. The presenter now drops what the screen gave it when the screen closes.
…the device test may download
…process important
Each check sent 8 s of audio to the check's process in a one-way binder
message, and a Bundle stores each short as 4 bytes: 512 KB a message. On
Android 16 (Test Lab, 16 KB pages), those were refused ("FAILED BINDER
TRANSACTION ... No space left on device"), with the process seen as
frozen, so every check silently came back "not said". The audio now goes
through a file in the app's cache, and the binding is BIND_IMPORTANT so
the process runs at the app's priority while a session uses it. The device
test passes on Android 14 and 16 (5 of 5 words found, the other sura's
word not, 0.3 s a check, the speech engine unchanged).
The colored pages quran.com's own app offers under Page Type (experimental), from the same public server it downloads them from (files.quran.app/hafs/tajweed: one width, 1280 px, with its own glyph boxes). The same pages, ayat and reciters as the Madani page type. With a second page type, the existing Page Type (experimental) setting appears. Memorize works on it as on any page type: its words are told apart at runtime from this layout's own glyph boxes (6,232 of 6,236 ayat; the 4 whose end marker isn't a glyph of its own are hidden ayah by ayah), and its marks are drawn under the words, so the colors stay.
Brings in the 99 commits of quran/quran_android main up to c94ebe1 (page themes and the app theme, night mode that keeps tajweed hues, Account & Sync, bookmark page-type mapping, dependency updates). Conflicts resolved: - settings.gradle.kts, gradle/libs.versions.toml: both sides kept (the memorize modules next to :feature:pagetheme; sherpa-onnx and the test runner next to the new AGP version). - QuranApplication: both imports kept (secondary-process check and the direct-boot WorkManager check). - PagerActivity: the night-mode menu item is gone upstream; only the memorize menu item is kept there. - strings.xml (en, ar): both sides' strings kept. The tajweed page type inherits the Madani mushaf type for bookmark sync through its delegation to MadaniPageProvider.
- Recitation audio moving to the next ayah: its animated highlight's key
("2:5->2:6") was taken for a word key on pages whose word glyphs are
derived (Madani and Tajweed here), and parsing it threw in onDraw.
Transitions now keep the bounds they always had.
- Two pages on screen: the current page is the first of the pair, not the
second, so the session started a page early, and with nothing selected
on the first pair it looked up page 0 and crashed. The last pair of a
mushaf with an odd number of pages has one page.
…can be closed The reading screen unbinds the presenter when it pauses (screen off, recents, another screen), and unbinding cancelled the toast's timeout but left the toast up, so it stayed until Undo. Unbinding now takes it down. It goes away after 10 seconds (20 for the first-time explanation), and its x, which only the first-time toast had, is on every toast to close it at once. The timeout runs on the presenter's main scope.
All seven page types of quran.com 3.6.5, from files.quran.app/hafs, under the store app's keys: new_madani (1421), new_madani_1441 (1440), new_madani_1439_lines, madani_1441_lines and shemerly (521 pages), next to madani and tajweed. Titles in English and Arabic come from the store app. - Providers: pages/madani's provider/edition (HafsEditionPageProvider); TajweedPageProvider moves onto it (version 7). - Page tables made from the public ayahinfo databases: Madani1440DataSource for the four newer prints (25 page starts differ from 1405) and ShemerlyDataSource (368 ayat run on to the next page; the derived table fixes 4 errors in the store's). - Line-by-line pages: the new :pages:linebyline provides the PageViewFactoryProvider (open-source build only, app/pluggable.gradle). - Memorize works ayah by ayah where a page has no word boxes: word keys take their ayah's bounds, line pages hide ranges by clipping the line images, and an ayah that runs on to the next page is marked on both (Shemerly). PageLines follows page-type switches. - The page-type picker has a fixed order and opens on the current type.
- The mode window: tapping a mic (floating, the audio bar's, "Recite from here") opens a sheet, Memorization or Recitation (a long press adds salah); RecitationStart replaces showModeSelection. The toolbar's Memorize starts right away. - Recitation (Mode.RECITE) hides nothing: a trail on the words read, hinted words marked, and with "mark mistakes" on, skipped words and the mistake being made; "say the correct word" follows a mistake after the hint delay. Both are switches in Settings. At night an underlay colour with its own alpha keeps it. - Record and contribute (a switch with a one-time explanation): every session is recorded, and its recordings keep what the speech model heard and what the app decided (<id>.heard.jsonl). Nothing is sent. Recording format 2 (per-word mistake counts, contribute); version 1 still reads. Word times no longer drift after the recorder drops audio (AudioClock). - Recording sessions (Settings; was "My recordings"): sessions by day, swipe to delete with Undo, export, and playback on the session's own mushaf pages (PagePreviews in common/recitation, AppPagePreviews in the app): the page turns with the word heard, marks shown from the start, tap a word to play from it, a legend, 5 s back and on. - MemorizeScreensRenderTest (-Pmemorize.render) draws the feature's screens to PNG; README sections for all of the above.
…ssion ahead - The tracker knows which ayah each word is in. In Memorization and Recitation a user who goes on to a later ayah without reciting one is held at its first word, which is marked and given after the hint delay until they are back. After ten hints (or when no hint will give the word) they are followed on and the words left out are marked as skipped. Speech where the words should be (misheard) lets them pass; only words with nothing heard count as left out. Salah keeps following the reciter. - Settings, "Words missed inside a verse": "Let a word or two pass" (default; never more than half an ayah) or "Every word must be heard". - No hint while the start waits on ayat that open alike (2:149/150). - A phrase an ayah says twice (5:46) isn't taken for a repetition: behind the cursor a path starts within backWords, at the ayah's start, or where a repetition goes on. At the 458 nearby look-alike pairs: correct passages clean 133 -> 139, restarts 281 -> 288, QUD recall with every word to be heard 52 % -> 86 %. - A phrase the ayah before also has (5:44/45) isn't taken for going back to it. - 27:30's basmala is the ayah's words, not the phrase before a sura. - A start dropped after a misheard word stays where the user was expected, instead of the first ayah on screen (live on the Mi 11: 5 of 6 places that had lost the reciter now pass). - Test clips are labelled with the ayah they recite (skeleton()'s diacritics range had been reversed, so every text matched ayah 1). - Real fixtures pin each case.
…bookmarks; tablet layouts - :common:progress keeps on the device (progress.db): every reading bookmark move, time with a Quran page open in the reader (paused after 3 minutes without a page turn or touch, credited to the bookmark moved at the end of that reading), and each Memorize session's results (passage, mode, date, length, counts per ayah; no audio, no heard words). A setting turns the session log off and clears it. - A reading cycle starts on its own when a bookmark goes from the last suras back to Al-Fatiha (an Undo within 60 s cancels it); pace, pages needed per day and the projected finish come from QuranInfo, so every page edition counts right. - :feature:progress: the Progress screen (main menu, and a chart button on reading bookmark rows). Per bookmark: pages and minutes per day, the current cycle on a juz line, total reading and the last cycle. Also Memorizing (share of ayat held per juz and sura), Salah and Sessions (recorded ones open in Recording sessions). Rail and two panes on tablets (MatePad 12 X), one pane at a time on phones; English and Arabic, day and night. - A daily reminder (WorkManager, 20:00 by default) to finish the cycle in its days; quiet when the reader is open or today's pages are read. - Reading bookmarks: five more colours kept on the device (green, blue, purple, brown, grey), each with a name, a purpose (reading, memorization, review) and cycle days, set in Settings. They work like teal, orange and red: the ayah menu, underlines, the Bookmarks list, backups (BookmarkData.localReadingBookmarks; old backups still restore). - Memorize on tablets: the mode window's modes as cards, Recording sessions with the list and the session side by side, and a session timeline beside the player. - Tests: the cycle, pace, reading time, recorder and reminder logic; bookmark routing and migration 4; ProgressScreenRenderTest (-Pprogress.render) and an on-device screenshot test.
…ay in Arabic QuranIcons.ArrowBack and ChevronRight are built with autoMirror = true, so they already flip in right-to-left layouts. Modifier.autoMirror() flipped them a second time, and in Arabic the back arrow pointed forward and the chevrons pointed back. The modifier is gone from the four back arrows (Account & Sync, Sync activity, Quran sync, Download manager) and the three chevrons.
On a fresh install nothing is placed, so every bookmark only said "Place this bookmark...", and Progress showed no chart at all, on a tablet's three panes as on a phone. A bookmark not placed yet now shows the same faded sample days, with the "Sample data" label, as one placed but not moved yet. The sentence line is left out when there is nothing to say. Render test: a bookmark not placed yet.
…n the user goes on from it Live on the Mi 11 (Husary's 102:1-3 then 102:5, leaving 102:4 out): the start was found on 102:1-2, then زرتم was misheard and the start dropped. كلا and سوف were misheard too, so the search never heard three clear words in a row again, marked "recited elsewhere" and lost the reciter. The place where a start was dropped is kept. One clear word there or right after it (4 phonemes or more) takes it up again: the word before it was said (misheard), unless nothing was heard there, and the session goes on after it. Found twice at the same place, the start is no longer doubted: a word misheard after it is an ordinary mistake, which the following words recover, and an ayah left out is held at. A new start elsewhere still needs a run of words. Fixtures (RecitationTrackerLiveStartTest), the phone's streams: 102:1-3 then 102:5 (before: only 102:1-2 followed; now 102:3 too, and the session holds at 102:4:1), and 102:1-5 said correctly (followed to its end). Replayed on all 178 Memorize and Recitation sessions the Mi 11 heard, 12 change: false "recited elsewhere" marks go, and 102:3-4 is followed where the old search jumped ahead to 102:5. A clear word two on was tried and left out: in 102:1-5 said correctly it took the start up again where the old search waited, and the session then held at 102:4:1, which differs from 102:3 by one word.
…e pages On a short screen (a phone in landscape, under 480dp tall) the session window gave the mushaf page a strip about 150dp high above the legend and the player. There the pages now take the height, with the legend and the player in a column beside them (mirrored in Arabic); taller screens keep the player under the pages. The render tests also draw a phone on its side, a small phone (360x640dp) and, for Progress, a small tablet (715dp, as the Galaxy Tab A7 Lite); Progress's render test gets a 2 GB heap for its tablet-sized bitmaps.
Test Lab's Robo crawl of the minified tablet build crashed opening Settings > Advanced settings: building the bookmark backup's JSON adapter, Moshi looks ReadingBookmarkType's constants up by name, and R8 had renamed them (TEAL -> m), so it threw "AssertionError: Missing field". Marked @JsonClass(generateAdapter = false), the enum keeps its constants' names under Moshi's own R8 rules.
On Test Lab's Galaxy A05s (a budget phone) the double-check's 92 MB model
download broke off ("unexpected end of stream"), and a download had no
second try: the user had to start it again. Now a file whose connection
drops, comes short, or meets a server error is fetched again, three times
in all (after 2 s, then 4 s). A file that isn't the one pinned, or a
missing one (HTTP 4xx), still fails at once. Both the speech model and the
double-check use it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📖 Memorize · احفظ & 🕌 Prayer Corrector · مصحح الصلاة
Recite from memory with the mushaf page open: the words disappear, and come back as you say them.
Stuck? Sheikh Al-Husary gives you the next word. Fully offline, fully private.
Recorded on a Xiaomi Mi 11 in night mode. Tap the green mic, and the words are hidden. Al-Husary recites Al-Mulk, and they come back as they are said. A wrong passage gets a 🔴 mark, and then the word is given. Then the session is paused from the mic.
🧭 What this PR adds, in one minute
Everything runs on the device: no account, no server, and nothing recorded unless you turn it on.
📸 Screenshots
Taken on a Xiaomi Mi 11 (Android 14), in night mode, with a Husary recording played in place of the microphone.
While listening in the background, the notification shows only where you are, never what was heard, and whether you are being recorded:
On the Madani mushaf with tajweed colors, the experimental page type this PR adds. Same phone, release build, a recitation played aloud from a laptop:
The words come back in their tajweed colors. Night mode uses the app's usual filter, which inverts the page's colors, as quran.com's app does.
بالعربية: the full interface in Arabic
A tour of the PR in pictures
Real screenshots unless marked otherwise: a Xiaomi Mi 11 (Android 14) and Firebase Test Lab's real and virtual devices. "Rendered" means drawn by the PR's screen tests (
-Pmemorize.render,-Pprogress.render).🎙️ Starting a session: the mode window
Tapping the green mic (or Recite from here on an ayah) opens a small window. It says where the session starts and whether it will be recorded, and offers Memorization or Recitation. A long press on the mic adds In prayer (salah). On a tablet the choices sit side by side as cards.
🚫 No ayah is left out
If you go on to a later ayah without reciting one, Memorize holds at the first word of the ayah you skipped. The word is marked, and given after the hint delay, until you come back to it. Ayat that sound alike (2:149 and 2:150 open with the same eight words) no longer pull the session ahead, and going back to the start of an ayah is followed as a restart. Inside an ayah, a setting decides whether a word or two may pass (the default) or every word must be heard.
Over the air on the Mi 11: Husary's recitation played from a laptop, heard by the phone's microphone (
bench/noskip_ota.py).📗 Recitation mode
For reading with the text shown. Nothing is hidden: the words you have read get a light trail, and skipped words and mistakes are marked. After a mistake, the correct word is said in Al-Husary's voice once the hint delay has passed. Both are switches in Settings, next to Memorize's own.
📼 Recording sessions
Settings > Recording sessions lists what you recorded, by day: the mode, the passage, the time and length, and whether it was recorded to contribute. A session opens in a window that plays it back on its own mushaf pages: the page turns with the word being heard, hints, skipped words and mistakes are marked, and tapping a word plays from it. A timeline under the player shows where the hints, skips and mistakes fell. On a tablet the list and the session sit side by side, and on a phone held sideways the player sits beside the page.
📊 Progress on a phone
Menu > Progress, or the chart button on a reading bookmark in the Bookmarks tab. For each reading bookmark:
Memorizing counts the ayat you hold (recited every word without a hint the last time), by juz and sura. Sessions lists every session, ayah by ayah. Everything is kept on the device.
In Arabic, the chart button sits on the reading bookmark's row, and the charts read right to left:
On the Mi 11, with 12 days of sample history from the debug build's "seed" setting.
📱 Progress on tablets
On a tablet in landscape, Progress has three panes: the sections, the bookmarks, and the one chosen. A small tablet gets the rail and two panes, a phone one pane at a time, and a phone held sideways gets three panes too.
Progress, on a tablet and a phone. These are Firebase Test Lab virtual devices: a 1280 × 800 dp tablet in landscape, which gets the same three panes as a 12″ MatePad 12 X, and a phone. Both have 12 days of sample reading. The teal bookmark is 13 pages behind a 30-day pace. Pages per day are above the axis and minutes below.
On real tablets and phones. The same release APK on Test Lab's real devices, right after install: no bookmark is placed yet, so Progress shows faded sample days.
🔖 Eight reading bookmarks
Teal, orange and red stay as they are, and sync with the user's account. Green, blue, purple, brown and grey are new and stay on the device. Each has a name, a purpose (reading, memorization or review) and the days to finish a cycle in. They are placed from an ayah's menu, underlined on the page, listed in Bookmarks, and kept in backups. The toast after moving one now has an ✕ and goes away by itself.
📄 Page types
Settings > Page Type now offers all seven of the store app's page types, in a fixed order, opening on the one in use: Madani, Madani with tajweed colors, the 1421 and 1440 prints, two line-by-line prints, and Shemerly. Each downloads its pages the first time, from quran.com's public file server. Memorize works on all of them: word by word on Madani and tajweed, ayah by ayah on the others, whose pages have no word boxes.
🔧 Fixes you can see
✨ Features
🎙️ A floating mic
📖 Memorize mode
📗 Recitation mode
🗣️ Prayer corrector
🕌 Salah mode
✅ Double-check before correcting (optional)
📼 Record and listen to yourself (opt-in)
alignment.jsonwith every word's time, whether it was recited, hinted or missed, and its phonemesmanifest.jsonlof the ayat you recited entirely, ready for training speech models<id>.heard.jsonl), for improving the models. Nothing is sent: the user exports it.📊 Progress
📥 Downloads, your way
📄 Every page type, and colored mushafs
🔒 Private by design
🧭 How it works
flowchart LR mic["🎙️ Microphone<br/>in memory only"] --> asr["🧠 Speech model<br/>streaming phonemes"] asr --> tracker["🧭 Tracker<br/>finds where you started,<br/>follows the expected words"] tracker --> hints["⏱️ Hint scheduler<br/>mark → wait → next word"] hints --> page["📖 Mushaf page<br/>words reappear · mistakes marked"] hints --> voice["🔊 Al-Husary<br/>speaks the next word"] mic -. "only if you chose to record" .-> rec["📼 Recording<br/>+ word alignment"]T is 4 s by default. With the double-check on, each hint and mark is checked first (about 0.7 s).
When a session doesn't follow, it can say why:
adb shell setprop log.tag.MemorizeTrace DEBUGlogs what it heard and decided (start search, salah phases, words, mistakes, hints). It is off by default, for developers only.✅ Tested on real phones and real voices
Over the air on a Xiaomi Mi 11. Recitations were played from a laptop's speakers, and the phone's own microphone heard them in real sessions. Each clip was played clean, and again with room noise around it, about 10 dB below the voice (living room, café, kitchen, street, meeting, car).
Whole prayers, over the air on the Mi 11. These are YouTube recordings from mosques, used for evaluation only and never redistributed. They are two complete prayers, with every rak'ah's takbir, Al-Fatiha, passage, ruku and sujud, in salah mode with the default delay.
¹ The first minutes of that run were garbled by the laptop's audio, after a run was stopped mid-playback. In clean runs, with and without the check, the start was 12:69.
The double-check on the same phone: a check takes about 0.7 s. Its model runs in a separate process that peaks at about 330 MB, and the app's own memory doesn't change. On 5½ minutes of the Yusuf prayer, played twice with the check and once without, the session followed the same 213 words each time, with 1 and 0 wrong marks against 4. In the lab, on 3 hours of mosque prayers and on users' phone recordings, it cut:
It never dropped a hint that was needed in 400 real stalls, and recall was unchanged.
The release build, used like a user would (R8, one app process for every session). Each clip was played after going to its page and starting from the floating mic, and scored from the session's diagnostics trace. Over 53 sessions:
In Firebase Test Lab (Test Lab): whole sessions, fed a recitation in real time through the real engine, tracker and hint scheduler.
The double-check on Test Lab's virtual phones (Android 14, and Android 16 with 16 KB pages) and on the Mi 11:
Android 16 caught a bug the Mi 11 hadn't shown: the audio sent to the check's process was too big for a binder message, and now goes through a file. A Robo crawl of the release APK found no crash on Android 8.0 or 14.
¹ Listening starts immediately: what you say while the model loads is kept and shown as soon as it's ready.
During development, on recordings not used to build the app:
No ayah left out was tested in the lab and live.
Page types on the Mi 11 (release build): all seven are in the picker; Shemerly downloaded (114 MB) and showed; Memorize followed Husary's Ad-Duha over the air, ayah by ayah (93:1–5), with the ayat before the start shown again.
Progress was checked on the Mi 11 in English and Arabic:
In Test Lab:
On tablets and phones (Test Lab, the minified release build, one APK for both):
ReadingBookmarkType's constants up by name, and once the enum had a field, R8 renamed them.@JsonClass(generateAdapter = false)keeps them, and the tablet that crashed now opens the screen.Unit and integration tests follow TESTING_STRATEGY.md: fakes not mocks, and virtual time. The tracker is golden-tested against its reference implementation, with real recordings as fixtures for the cases found live. The full suite passes: 952 tests, plus device tests for the double-check and the Progress screens.
🧠 Speech model and license
feature/memorize/MODEL_LICENSE: free to use and share, never sold or put behind a paywallAs the model's terms ask, the app tells the user before the first session that automatic feedback can be wrong and does not replace a qualified teacher.
The optional double-check
CheckGraph, 3 nodes in front, weights untouched); the result is checked by its SHA-256.:doublecheck), because with sherpa-onnx 1.13.8 a second model in the speech engine's process corrupts the engine's state: on a phone, the session went deaf for 20–45 s after each check.🔉 Changes not directly about memorization
Each has its own commits, so any of them can easily be split out if you prefer.
Swap volume keys, under Volume key navigation: an optional setting, off by default, that makes volume up turn to the next page. It is for one-button Bluetooth page turners, which only send volume up. Nothing changes for anyone else. (
Allow choosing which page the volume up key turns to)The store app's page types, under the existing Page Type (experimental) setting, which now appears because there is more than one. They use the store app's keys and titles:
The images and glyph boxes come from quran.com's public file server, the same place the Play Store app downloads them from (
files.quran.app/hafs/…).:pages:linebylinedraws the line-by-line pages.Add the Madani mushaf with tajweed colors as a page type,Page editions: …)The reading bookmark toast no longer gets stuck. After moving a reading bookmark, the Undo toast could stay up until Undo was tapped. The reading screen unbinds its presenter when it pauses, which cancelled the toast's timeout but left the toast up. This has been upstream's behavior since
966d521bf.Reading bookmarks: the moved/cleared toast…)Back arrows in Arabic. In Account & Sync and the Download manager, the back arrows pointed forward and the chevrons pointed back in Arabic.
QuranIcons.ArrowBackandChevronRightare built withautoMirror = true, so they already flip in right-to-left layouts, andModifier.autoMirror()flipped them a second time. The modifier is removed from those icons. (Sync and Download manager: back arrows…)📦 What changed (click to expand)
feature/memorize(new)feature/memorize/tracker(new, pure Kotlin)feature/memorize/engine-sherpa(new)common/pagesGlyphTypeResolverreceives each ayah's glyph sizes in the page type in usecommon/recitationRecitationPresenter.setReadingScreen(): the pages on screen, and how to start a session there;RecitationStart(the mode window);PagePreviews(mushaf pages drawn outside the reader, for playback)common/progress(new)progress.db) and the pure logic: cycles, pace, reading time, the reminder's decisionfeature/progress(new)common/data,common/bookmarkReadingBookmarkTypeis@JsonClass(generateAdapter = false)so minified builds keep the names backups use)pages/madani,pages/linebyline(new)feature/memorize/check(new)app,pagesQuranApplicationskips its setup in secondary processes (the double-check's).app/pluggable.gradle:feature:memorizeinto the existing recitation slot instead of the stubs, and the line-by-line pagesfeature/sync,feature/downloadmanagertools/memorizeChanges outside the new modules are additive: existing highlights, selection and audio behave exactly as before.
🧾 The commits, oldest first (click to expand)
f15489fb727f430a54c6261b769d8dbe1e33259de207fe1ca2b19b3d8561d11be41cbfcd,ba0ea965a80e2e9e1db5f425cbc527e79c39ee1f274995dfce92adb9d3b9f275689918cc8d8032a34046a33c78c8c573d7da76d14ee675b20002694200e91949f7b1ea610c7dfd845282896213c49d9c66964ccb40c2232a1b63bb04109f3f34787b47e119c5589📏 Size, dependencies and permissions
tools/memorize/fetch_sherpa_onnx.shdownloads the official AAR and checks its SHA-256, and CI runs it before building.RECORD_AUDIO,FOREGROUND_SERVICE_MICROPHONE,POST_NOTIFICATIONSandWAKE_LOCK.REQUEST_IGNORE_BATTERY_OPTIMIZATIONSis used only when the user sets up background listening for salah. Recording needs no other permission. Progress's reminder usesPOST_NOTIFICATIONSand the app's WorkManager; no new permission.🙏 Credits
👀 Notes for reviewers
This is a big change, and I'm happy to split it: