Files
FamReynaBrain/projects/tactility_bible_audio.md
T
2026-11-16 23:00:19 -05:00

68 lines
9.7 KiB
Markdown

# Tactility Bible Audio
## 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.