18 KiB
Tactility Bible Audio
Listening-first implementation — approved and started
User liked the WhatsApp reference images and requested deliverables and implementation. Authoritative checklist: /Users/adolforeyna/Projects/electronics/tactility/tactility_apps/Apps/BibleAudio/UX_DELIVERABLES.md. Seven deliverables: D1 durable state/resume-first; D2 listening history; D3 persistent chapter-limit sessions; D4 native reference UI; D5 offline/interruption handling; D6 simulator/regression QA; D7 ESP32 package and separately authorized hardware pilot.
D1 is parent-verified complete:28 actual-C/real-MP3 tests, zero skips; live320x240 and480x320 checks of latest-of-multiple chapters, no audio/download on paused startup, exact fractional-sample Resume, durable Pause, repeated preview-close preservation, and first-use closing without fake history. Worker repairs deleg_18ce6e7c plus parent fixes restored sample rate, atomic dirty generations/deferred capture, shutdown writer ordering and backward-seek checkpoint cadence. Acceptance: /Users/adolforeyna/output/bible-audio-ux-implementation/d1-acceptance.md; tests/build/runtime logs and screenshots in that directory. Simulator package equals installed simulator binary. During D1 QA, the480x320 simulator was paused at Genesis2 0:04/3:06 with no audio; the live process has since been replaced for D2 QA below. This is not the final visual redesign or chapter-limit implementation.
D2 is parent-verified complete:51 actual-C/real-MP3 tests, zero skips, and live320x240/480x320 checks. Repaired contiguous coverage, full-catalog part metadata, mute gating, heap snapshots and bounded persistence; parent additionally fixed per-play recency, short-stop flush, accepted-byte fatal-write position, pending/nonblocking Recent preview, last-played preservation when preview closes unplayed, readable two-row Recent pages and explicit offline/listening labels. Full real-MP3 worker tests now prove Finished on continuous output and no false Finished from mute or skipping. Native tests persisted Started for Genesis1/2, reopened without sound, previewed an older chapter without changing last played, and moved Genesis2 to first only after explicit Resume; merged exact persisted span202752-395136 samples. Evidence: /Users/adolforeyna/output/bible-audio-ux-implementation/d2-parent-live-qa.md; current source/package/hash snapshot and tests logs are alongside it. During D2 acceptance the480x320 simulator was in Recent with audio stopped; current D3 runtime is recorded below. Focused worker deleg_89c6201e repaired original padded-v1 migration, negative-position rejection and exact persistence validation; parent reviewed it, reran the51-test suite and verified final C source hashes match the simulator-tested package. Final acceptance: /Users/adolforeyna/output/bible-audio-ux-implementation/d2-acceptance.md. Package SHA-256 e8f115a70673690eafd2cb453adc8889c0885727e927ba7a3d0c48b416bb5c77; preserved as d2-verified.sim.app with d2-verified-source.tar.gz. Temporary cache-absence test preserved Started/history while showing Needs download; cache restored. D2 has been simulator-deployed only; kitchen untouched. Worker owns BibleAudio source/tests only and may build/test, not operate the live simulator, modify checklist/manifest, write hardware or commit. D3 remains in progress, not accepted. Repairs deleg_08d14167 delivered serialized background persistence/controller changes and limit/stop UI. Parent fixed live overlay flex clipping, missing root deletion, compact overlap, true Close, and startup-ready rendering; full62tests and simbuild pass. Native480 five real natural endings Genesis2..6 decremented5->0 and persistedGenesis7ready0:00, with no7audio/cache; receipt d3-five-chapter-live-receipt.json. At320 coldrestart restoredexhaustedgentlestop; actualAnother5 downloaded/started7once, paused27648@44100; selectingNoLimitCancel preserved state andexplicitUse1savedlimit1/rem1. Repeated appreopen intermittently fails catalog despite backend200; failedinstance6 hasnoCatalogHTTP/resultlogs, likelytaskcreate failure butrootcauseunproven. Filepreservation isNOTsuccessful UIresume proof. Latestreview /Users/adolforeyna/output/bible-audio-ux-implementation/d3-parent-native-qa.md. Currentruntime320x240PID45772, failedcatalogUI, audiooff; statev2limit1/rem1chapter7samples27648ready0. Read-onlydiagnosis deleg_00d4d7a5 completed: task-allocation failure is workinghypothesis, not runtime-proven. Parent nm -m verified TrackInfo calloc resolveslibSystem, separate from simulatorFreeRTOSheap; do not addthatallocation toRTOSbudget or extrapolate POSIXstackwordunits toESP-IDF. Correctednote d3-reopen-diagnosis.md and findingsrelayedtoresidualcontrollerworker; require actualcreationreturn/heap diagnostics beforefixclaim. Residualcontroller/book-enddurability/exhaustednavigation/actualworkerintegrationtests ownedby deleg_5a778ee5/sa-0-33e6d30b; samebatch sa-1-ca2710b8 owns ONLY new test_limit_view_runtime.py actual-C event/lifetime tests. ParentownsUI module/header andallnativeoperations. Workersmaybuild/test, never simulator/hardware/manifest/checklist operations. D4-D7 remain pending. Parent owns acceptance and live QA. Baseline archive/hashes and evidence: /Users/adolforeyna/output/bible-audio-ux-implementation/. Kitchen remains installed0.3.0 and unchanged; no new hardware installation/launch authorization inferred. No final ESP32 build/ABI/runtime verification for the new UX has occurred yet.
Latest D3 blocker and current runtime
D3 remains unaccepted. All workers completed; parent full suite67tests/zero skips and simulatorbuild succeed, including actual-C ASAN/UBSAN UI events, realMP3five-ending gate, and statev3 with v1/v2migration/book-end marker. Parent verified nativefiveendings Genesis2..6 stopbefore7, andAnother5explicitlystarts7. Stackunits correctedapp-only: POSIXworddepthconvertedfrombytes withhostminimum16384; ESPargumentsunchanged. This mitigates overallocation, NOT the underlyingcleanupbug.
Runtime taskallocationfailure is nowproven: return-1/freeheap25216. Correctedstackstressstillloses45824Bperreopen;15successes thenfailurecycle16. ActualuxTaskGetSystemStatetrace shows3additionalpending-deletedtasks eachcycle (1,4,7,10), withheap695040,649216,603392,557568. Simulator deferredcleanupnotreclaimingtask allocations; exactruntimeidle/reapermechanism stillneedsinvestigation. Evidence /Users/adolforeyna/output/bible-audio-ux-implementation/d3-simulator-task-retention-blocker.md. No simulator/firmwaresourcechangesmade. Scopeapproval request forlocalsimulator-onlyruntimefix timed out unanswered; do not change runtime until explicituserapproval. Allworkersfinished; appclosed/audiooff. Hardware unchanged. Current320x240PID48974, appclosed/audiooff. Statev3 limit1/rem1, chapter7 samples28800/rate44100, ready0/book_end_stopped0. Oldqa_d3_helpers.py assumesv2; updatebeforeparsing. RemainingD3nativebookend/manualconfirmation cases andD4-D7pending. Earlier inline D3 worker/runtime references above are historical, supersededbythissection.
Original design-only UX proposal — implementation now approved
User requested no coding: rethink UI, open on latest played chapter, retain chapter-playback history, consider automatic stop after five chapters, and render references. Proposed resume-first paused home, stable player controls, independent offline/listening state, current-chapter-centered tiles, Recent listening, explicit five-chapter session settings and gentle stop with next chapter ready. The five includes the resumed current chapter; introductions/split parts do not count separately, and restart does not silently reset the allowance. These were initially design-only proposals; the subsequent user request approved implementation under the checklist above, but the new features are not yet verified implemented. Seven reference states rendered at320x240 and960x720 plus overview boards; all positions/statuses in images are illustrative, not device history. Files: /Users/adolforeyna/output/bible-audio-ux-reference/00-experience-overview.png, 00-main-flow.png, and design-proposal.md in that directory. No app code, firmware or device changes were made for this design request; deployed0.3.0 remains the last installation recorded below.
Current revision — player 0.3.0
User requested responsive UI while downloading, fullscreen player content, MP3 Player-style volume UI/status bar, and auto-play next chapter. Implemented full window-manager content area while retaining the firmware-owned system status bar; accurate elapsed/total and progress bar; persistent app-scoped volume slider above transport controls; background download progress, Cancel, paging/Back/cached playback while downloading; natural-EOF next-track playback within the same book, downloading the next track if needed. Back/Stop/errors/closing suppress auto-next. Both decoding and duration scanning use heap decoder state; scan is header-only. Download work yields one actual FreeRTOS tick per chunk to avoid UI starvation. Volume persistence happens outside LVGL callbacks.
Verified 320x240 and 480x320 simulator layouts. Real Genesis1 EOF triggered download and native output explicitly tagged track2 (Genesis2, 3:06); Genesis2 EOF scheduled chapter3, and Back canceled it with no track3 output. Slow real-download test (25ms/chunk) kept paging/Back/Cancel below one second; canceled partials removed. Volume28 persisted and reloaded after restart. Eighteen tests pass with all six real-MP3 worker tests running (none skipped); native C helpers test volume gain/clamping/mute and same-book/natural-only auto-next. ESP32-S3 build audited135 imports against1662 source exports. Installed simulator binary and packaged ELF/manifest independently match their builds.
Artifact: /Users/adolforeyna/output/bible-audio-player-v03/BibleAudio-0.3.0-esp32s3.app (81920bytes), SHA-256 50d7bd801d670782fa8b294644ec45dfbc11159af1509b60e380051eee97f73c. Receipts/logs/screenshots: /Users/adolforeyna/output/bible-audio-player-v03/. Installed 0.3.0 on Kitchen kidsos_591c after fresh exact-MAC Deco verification (14:C1:9F:D0:59:1C, IP 192.168.68.113), direct/registry sysinfo and mounted-SD target listing. Live app inventory confirms Bible Audio. Read back installed 71,012-byte ELF and manifest; both match the selected 0.3.0 package byte-for-byte. ELF SHA-256 3ada6fd0292a79528325ede48f4d0110b5ab6239a0f34df7d8aa9730ab3193b5. Receipt: /Users/adolforeyna/output/bible-audio-player-v03/kitchen-install-receipt.json. Install only: no launch, audio test, reboot, firmware change or other-board writes; hardware runtime remains unverified. Final simulator320x240 PID8583, no test throttling, left at book picker with audio stopped. ESP32 runtime responsiveness remains unverified until a hardware pilot.
Previous revision — player 0.2.0
User feedback requested better chapter selection and a dedicated player with Play/Pause, -15s/+15s and Back to Chapters. Implemented six-tile numbered pages with Saved/Download status and distinct introductions; duplicate chapter tracks retain separate part labels. Dedicated player shows chapter, elapsed time, Pause/Resume and real sample-backed seeks. Back stops audio asynchronously and preserves the book/page. Pending track switches are canceled on navigation; new playback resets seek state. Long seeks decode from the beginning to preserve MP3 reservoir state and may take time on ESP32.
Verified latest revision in the Mac mini simulator at 320x240 and 480x320. Paused UI stays stable; repeated +15s moves 1s to31s, -15s returns16s, resume logs actual output after705600 skipped samples. Download-to-player and Back-to-same-page pass. Sixteen tests pass, including actual C seek callbacks and six real-MP3 worker/PCM comparisons covering seeking both directions, pause/resume, negative clamp, beyond EOF and paused shutdown. Final simulator binary matches its package. ESP32 build passes all126 imports against1662 source exports.
Package: /Users/adolforeyna/output/bible-audio-player-v02/BibleAudio-0.2.0-esp32s3.app, SHA-256 67bff7fdd728d4b9f04d394986e63d3f41c8946e6c716305054a1c6f1a5c1ae8. Evidence, screenshots and receipt in /Users/adolforeyna/output/bible-audio-player-v02/. Current simulator process PID85276, 320x240, left on chapter page2 with audio stopped. Installed 0.2.0 on Kitchen kidsos_591c after fresh live Deco exact-MAC verification (14:C1:9F:D0:59:1C, IP 192.168.68.113), direct/registry sysinfo, mounted SD, and /sdcard/tactility/app listing. Live app inventory contains Bible Audio. Installed manifest and 66,916-byte ELF were downloaded and match the 0.2.0 package exactly; ELF SHA-256 7a890a64901ba8a93a24347063e85fa6641c97f311dcf275c556772706c8d776. Receipt: /Users/adolforeyna/output/bible-audio-player-v02/kitchen-install-receipt.json. Install only: no app launch, playback, reboot, firmware change or other-board update. Hardware 0.2.0 runtime remains unverified.
Initial milestone — 2026-11-13
User requested an initial audio Bible app using the existing BibleVerse book-selection UI, first on the Mac mini emulator. Implemented a native Tactility app and functionally verified it in the Mac mini simulator. No physical boards were installed or modified, and no server catalog records were changed.
Source: /Users/adolforeyna/Projects/electronics/tactility/tactility_apps/Apps/BibleAudio/
App ID: one.tactility.bibleaudio
Simulator package: Apps/BibleAudio/build/one.tactility.bibleaudio.sim.app
Builder: python3 Apps/BibleAudio/build-simulator.py from tactility_apps root.
Evidence: /Users/adolforeyna/output/bible-audio-simulator/
Local simulator viewer: http://127.0.0.1/sim
Verified implementation
- Same BibleVerse-style horizontal 66-book picker with arrows, scrub slider, dark colors, and embedded Georgia Regular 24 font.
- Real PocketBase catalog on FamReynaServer
.110:8095, usingaudio_libraries,audio_collections, andaudio_tracks. - Native chapter listing, pagination, back navigation, downloads with exact catalog-size validation, cached-play indicators, stop, clean exit/reopen.
- Real minimp3 decoding through firmware audio-stream0 → SDL/CoreAudio, not the legacy Mp3Player silent simulator branch.
- Tested at 480x320 and 320x240. Genesis chapter 1 downloaded 2,070,582 bytes, SHA-256
5e3dd36bc35dcdf4284bd0d36ccae0c6f59c3d83815244268b7bcdf4fed6e4f5, exactly matching server bytes. - Native audio logs show 44,100 Hz mono output and decoded samples written; tested stop and cached replay. This is output-path verification, not independent microphone confirmation of audibility.
- Eight tests compile and run actual C book-mapping and PCM-write logic, including partial timeout writes, bounded no-progress retry and fatal driver errors. Two SDL simulator audio suites pass.
- Delayed review was reconciled with final source: all reviewed alias/lifecycle/download/catalog defects fixed; Back cancels pending download/autoplay, malformed pages fail explicitly, PCM partial writes retry safely. Rebuilt, reinstalled, exact installed/package binary match verified; playback/stop/exit/reopen retested. Final binary SHA-256:
9e46b4842fe13d336bd11f49b7da1f440a0200cd6b5e789d902e6ba924ada6b5.
Important source-library limitation
Live backend: 1 library, 18 collections, 1,167 MP3 tracks. Actual C mapping recognizes 1,163 tracks across 53 canonical books. Four records are general section introductions (history/wisdom/prophets/New Testament), not canonical books.
Absent source audio: Daniel, Hosea, Joel, Amos, Obadiah, Jonah, Micah, Nahum, Habakkuk, Zephaniah, Haggai, Zechariah, Malachi. App keeps these books in canonical order and labels them unavailable. Do not describe the hosted library as a complete audio Bible.
Remaining work
Persistent catalog/offline restart browsing, resume/history, source-audio gap restoration and ESP32 runtime verification of the 0.3.0 player, including SD-download responsiveness on hardware.
ESP32-S3 build — 2026-11-13
Latest source built successfully against a fresh SDK from local firmware revision dcfd4e9bcc12da39f3af8cc80f7bc6388e29b56f. Package: /Users/adolforeyna/output/bible-audio-esp32/BibleAudio-0.1.0-esp32s3.app (71,680 bytes), SHA-256 3d190068cadb841d5959103f2bb1fa03a8bcf3de10c94e412af72038f4da9857.
- Package manifest and embedded ESP32-S3 ELF match source/build artifacts exactly.
- Source export audit: 125 imports, 1,662 exports, zero missing imports. Both locally compiled ES3C28P and ES3C35P firmware ELFs contain all imported symbols; this is not proof of the firmware currently flashed on any board.
- Eight app tests pass. MP3 decoder moved from task stack to heap because it occupies 23,068 bytes vs the 8 KiB ESP-IDF playback stack. Host heap-decoder smoke test decoded 20 real Genesis frames / 23,040 samples.
- Receipt:
/Users/adolforeyna/output/bible-audio-esp32/build-receipt.json. - Build only: no hardware installs, launches, firmware flashes or device changes performed. Device runtime remains unverified. Simulator was not redeployed for this heap-allocation-only change.
Kitchen installation — 2026-11-13
Installed Bible Audio 0.1.0 on Kitchen kidsos_591c, exact live Deco MAC 14:C1:9F:D0:59:1C, resolved IP 192.168.68.113. Preflight verified ESP32-S3, mounted SD and /sdcard/tactility/app listing. App is present in live app inventory. Downloaded installed bin/esp32s3/BibleAudio.elf (62,820 bytes) and manifest; both match local artifacts byte-for-byte. ELF SHA-256 100aec865873adddc1613da43370edeff95ed410d8c0dbe5197097c37d4e8a3d. Receipt: /Users/adolforeyna/output/bible-audio-esp32/kitchen-install-receipt.json. Installation only, as requested: app not launched, no playback test, no reboot or firmware changes.
Continuity
Earlier server setup was completed in session 20260919_215532_5e469e (Extend Discovery Mountain for Bible audio). Audio resides at /mnt/mydisk/media/podcasts/Bible Message/episodes/, served through read-only Nginx at http://192.168.68.110:8098/bible-message/. Original external-drive archive was preserved.