86 lines
18 KiB
Markdown
86 lines
18 KiB
Markdown
# 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`, using `audio_libraries`, `audio_collections`, and `audio_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.
|