joe/MindMachine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Auto commit Mon Mar 16 11:04:20 AM CDT 2026

Browse Source
This commit is contained in:
Tretzi
2026-03-16 11:04:21 -05:00
parent a4d81f41b0
commit d441ead98b
1 changed files with 140 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
ANDROID_MVP_SPEC.md
View File

@@ -1,5 +1,14 @@
# MindMachine Android MVP Product Specification
## CHANGELOG
- Revised per latest UX feedback:
- mode selection is a clear single-select segmented/toggle control, not plain buttons
- active visual sessions temporarily require forced landscape orientation with left/right split output
- flash visuals use red and green with black between flashes
- flash timing is defined as **interval in milliseconds**, not Hz, with allowed range **50 ms to 2000 ms** and explicit helper text
- setup/config surfaces must avoid user-facing Hz wording for timing controls; config-facing timing copy should use plain duration/interval language
- setup/config screen must be scrollable in both portrait and landscape, respect safe areas/system insets, and keep the primary action reachable near the bottom of the screen
## 1. Product Summary
MindMachine Android MVP is a native Android app that turns a phone into a simple audiovisual session device. The MVP must let a user safely start a short session using built-in presets, deliver synchronized full-screen visual stimulation plus binaural stereo audio, and allow immediate pause/stop at any time.
@@ -51,13 +60,18 @@ To make MVP implementation-ready, the following are fixed decisions:
- **Custom sessions:** Not in MVP
- **Visual patterns in MVP:** Flash and Pulse/Fade only
- **Alternating patterns:** Nice-to-have, not MVP
- **Color use:** Monochrome white-on-black only for MVP to reduce complexity and risk
- **Color use:** For active visual sessions in MVP, Flash uses **red and green with black between flashes**; Pulse/Fade remains conservative and must use a black baseline with no extra decorative colors
- **Visual layout (temporary requirement):** active visual sessions force **landscape orientation** and render stimulation as **left/right split halves**
- **Brightness control:** App shows recommendation + optional in-app screen-intensity slider that affects in-app render intensity only; app does **not** force system brightness to max
- **Volume control:** App provides guidance to use device volume; no separate app-owned media mixer UI required for MVP
- **Headphone requirement:** Stereo headphones strongly required for binaural mode; if no wired/Bluetooth headset route is detected, app blocks starting audio-enabled session and offers Visual-only fallback
- **Countdown:** Default 5 seconds, user-adjustable in Settings: Off / 5 / 10 seconds
- **Default session durations:** Relax 10 min, Focus 15 min, Sleep Prep 20 min
- **Interruption handling:** Any call, audio focus loss, or headphone disconnect pauses session and shows recovery sheet
- **Mode control:** Session mode is chosen with a **single-select segmented/toggle control** with exactly one active option: Audio / Audiovisual / Visual
- **Flash timing parameter:** Use **flash interval in milliseconds** rather than flash frequency in Hz
- **Config-facing timing language:** For editable session timing controls, helper text, and validation/error copy, use plain interval/duration wording in **milliseconds or seconds/minutes as appropriate**, never Hz for flash timing
- **Setup layout behavior:** Session Setup must be vertically scrollable in both portrait and landscape, respect safe-area/system inset padding, and keep the Start action reachable without trapping controls behind the bottom edge
---
@@ -119,8 +133,8 @@ If user declines acknowledgment, app remains unusable for sessions and can only
Triggered when user taps Start.
Checks:
- safety acknowledgment completed
- at least one stimulation mode enabled (audio or visual)
- if audio enabled, stereo headphone route available
- exactly one session mode selected via segmented/toggle control
- if selected mode includes audio, stereo headphone route available
- session duration valid
- app not already in active session
@@ -159,9 +173,9 @@ Triggers include call, alarm takeover, audio focus loss, app backgrounding, scre
2. Stimulation stops immediately
3. Interruption sheet explains reason
4. User options:
- Resume when safe
- Resume Audiovisual (only if requirements restored)
- Resume Visual
- End session
- Switch to Visual-only if headphone route lost
5. Session never continues silently after interruption
### 4.8 Completion Flow
@@ -173,7 +187,7 @@ Triggers include call, alarm takeover, audio focus loss, app backgrounding, scre
### 4.9 Settings Flow
User can modify:
- countdown preference (Off/5/10)
- default mode preference (Audio+Visual, Audio-only, Visual-only)
- default mode preference (Audiovisual, Audio, Visual)
- keep screen on during session (default on, locked on for session regardless)
- show holder guidance before every session (default off)
- theme behavior if needed (dark only for MVP preferred)
@@ -258,6 +272,7 @@ Purpose: confirm and lightly customize before start.
Components:
- selected preset header
- editable duration control
- session mode segmented/toggle control
- visual mode section
- audio mode section
- headphone status row
@@ -265,35 +280,47 @@ Components:
- holder guidance link
- Start button
Layout and reachability:
- Setup screen must be vertically scrollable in both portrait and landscape orientations
- content must respect safe areas/system bars/display cutouts
- bottom content and Start button must remain reachable on small screens, large font sizes, and landscape layouts
- screen should allow comfortable access to the final controls without requiring precision gestures at the very bottom edge
Editable fields for MVP:
- duration: preset default, editable within safe range
- mode toggle: Audio+Visual / Audio-only / Visual-only
- visual pattern: only if visual enabled and only within preset-supported options
- blink frequency: adjustable within limited safe range
- mode control: **single-select segmented/toggle control** with exactly one selected option: **Audio / Audiovisual / Visual**
- visual pattern: only if visual is part of selected mode and only within preset-supported options
- flash interval: adjustable within limited safe range and always labeled in **milliseconds (ms)**
- carrier frequency: adjustable within limited range
- binaural beat difference: adjustable within limited range
Validation ranges (product-level; engineering may refine but must enforce equivalent guardrails):
- duration: 1 to 30 minutes
- blink frequency: 1.0 to 20.0 Hz
- flash interval: 50 ms to 2000 ms
- carrier frequency: 80 to 400 Hz
- binaural beat difference: 0.5 to 20 Hz
Recommended preset defaults:
- Relax: 10 min, Pulse, 6 Hz visual, 200 Hz carrier, 6 Hz binaural difference
- Focus: 15 min, Flash, 10 Hz visual, 220 Hz carrier, 10 Hz binaural difference
- Sleep Prep: 20 min, Pulse, 3 Hz visual, 180 Hz carrier, 3 Hz binaural difference
- Relax: 10 min, Pulse, 167 ms interval, 200 Hz carrier, 6 Hz binaural difference
- Focus: 15 min, Flash, 100 ms interval, 220 Hz carrier, 10 Hz binaural difference
- Sleep Prep: 20 min, Pulse, 333 ms interval, 180 Hz carrier, 3 Hz binaural difference
Behavior:
- Start disabled if invalid config or no enabled mode
- if audio is enabled and no headset detected, show blocking warning and CTA: Continue as Visual-only
- Start disabled if invalid config or no selected mode
- if selected mode includes audio and no headset detected, show blocking warning and CTA: Continue as Visual
- brightness row is advisory text, not a system-permission flow
- optional “Show holder guidance” interstitial before countdown if setting enabled
- helper text for flash interval must explain that lower ms = faster flashing and higher ms = slower flashing
- Setup must preserve access to all controls when the device rotates between portrait and landscape
- scrolling behavior must keep validation messages, helper text, and the Start action discoverable rather than hidden below a clipped layout
Field interaction details:
- use sliders or stepper controls rather than free-form numeric input where possible
- if text input is used, numeric keyboard only
- invalid edits revert or clamp on blur with helper text
- mode control must read as a mutually exclusive toggle group, not three independent buttons
- config-facing labels, helper text, and errors for flash timing must use interval language (for example, milliseconds or seconds), not Hz
- duration-facing controls should prefer minutes/seconds wording that matches what the user is editing
States:
- default
@@ -345,8 +372,11 @@ Overlay controls:
- preset/session name
Visual requirements:
- force landscape orientation while visual output is active
- split stimulation into left and right screen halves
- black background baseline
- white flash or white pulse/fade full-screen
- Flash pattern uses red and green flashes with black between flash states
- Pulse/Fade pattern must preserve a black baseline and avoid unrelated decorative animation
- no extra text while overlay hidden
- no decorative animation unrelated to session timing
@@ -360,6 +390,7 @@ Behavior:
- prevent accidental exit
- stop means immediate cessation of stimulation
- if user locks screen or app backgrounds, auto-pause
- if selected mode is Audio only, active session does not need forced landscape visual layout because no visual output is shown
States:
- running with overlay hidden
@@ -389,8 +420,8 @@ Triggers:
Copy must explain exactly what happened and what session modes remain safe.
Actions:
- Resume Audio+Visual (only if requirements restored)
- Resume Visual-only
- Resume Audiovisual (only if requirements restored)
- Resume Visual
- End Session
## 5.10 Session Complete
@@ -437,13 +468,17 @@ Out of scope in Settings for MVP:
### 6.3 Toggles / Segmented Controls
Used for mode selection.
- Exactly one of: Audio+Visual / Audio-only / Visual-only
- Exactly one of: Audio / Audiovisual / Visual
- must be visually presented as a single mutually exclusive control group
- must not appear as three equivalent standalone buttons
- state change updates dependent controls immediately
- disabling audio hides or disables headphone validation row
### 6.4 Sliders / Steppers
Used for duration and frequency values.
Used for duration and timing values.
- live value label always visible
- flash interval labels must include `ms`
- helper text must explain the interval meaning in plain language
- changes preview in text only, not active stimulation
- values snap to safe increments
@@ -468,11 +503,11 @@ Only acceptable loaders:
- brief transition while preparing session engines
### 7.2 Validation Rules
- at least one stimulation mode must be on
- exactly one session mode must be selected
- duration must be within 1–30 min
- blink frequency must remain within allowed range
- flash interval must remain within allowed range
- carrier frequency and beat difference must remain in allowed range
- if audio enabled, stereo headset route required before Start and Resume
- if selected mode includes audio, stereo headset route required before Start and Resume
- safety acknowledgment required before any session start
### 7.3 Empty States
@@ -481,8 +516,8 @@ Only acceptable loaders:
### 7.4 Error States
Handle explicitly:
- audio engine init failure -> cannot start audio-enabled session; offer Visual-only
- visual renderer failure -> cannot start visual-enabled session; offer Audio-only
- audio engine init failure -> cannot start audio-enabled session; offer Visual fallback
- visual renderer failure -> cannot start visual-enabled session; offer Audio fallback
- headphone disconnect during session -> auto-pause + warning sheet
- interruption / focus loss -> auto-pause + recovery sheet
- unexpected session engine failure -> stop safely + show non-technical error message and return options
@@ -500,12 +535,17 @@ Handle explicitly:
4. Text contrast must meet WCAG AA on non-session UI.
5. Text should support dynamic type/font scaling up to at least 200% without loss of critical actions.
6. Motion outside the stimulation experience should be minimal.
7. The app must provide **Audio-only** and **Visual-only** session modes.
7. The app must provide **Audio** and **Visual** session modes, plus **Audiovisual** as the combined mode.
8. Safety content must use plain language and short sentences.
9. Active session controls must remain discoverable and operable with screen reader focus when overlay is shown.
10. Session must never rely on color alone for meaning.
11. Any icon-only controls must include accessible text labels.
12. For users unable to tolerate flashing, app must make Visual-only off-state easy to find before session start.
12. For users unable to tolerate flashing, app must make non-visual mode easy to find before session start.
13. Mode selection control must announce the current selected option as a single-choice control group.
14. Flash interval helper copy must explicitly say the value is measured in milliseconds.
15. Session Setup must remain usable at up to 200% font scaling in both portrait and landscape via vertical scrolling.
16. Session Setup must respect safe-area/system inset padding so bottom controls are not obscured by gesture/navigation areas or display cutouts.
17. Config-facing timing labels and error messages must use interval/duration wording rather than Hz for flash timing.
Note: the stimulation content itself is intentionally flashing/pulsing; accessibility work applies to surrounding UI and availability of safe alternatives.
@@ -523,7 +563,7 @@ Note: the stimulation content itself is intentionally flashing/pulsing; accessib
- visualEnabledByDefault
- audioEnabledByDefault
- visualPatternType
- blinkFrequencyHz
- flashIntervalMs
- recommendedIntensityPercent
- carrierFrequencyHz
- binauralDifferenceHz
@@ -536,7 +576,7 @@ Note: the stimulation content itself is intentionally flashing/pulsing; accessib
- durationSec
- mode (audioVisual | audioOnly | visualOnly)
- visualPatternType
- blinkFrequencyHz
- flashIntervalMs
- intensityPercent
- carrierFrequencyHz
- binauralDifferenceHz
@@ -594,6 +634,9 @@ If crash reporting or analytics is later added, it must be explicitly reviewed a
- keep-screen-awake during session
- local persistence for acknowledgment + settings + last preset
- audio-only and visual-only modes
- single-select segmented/toggle mode control
- landscape left/right split visual layout for active visual sessions
- flash interval configuration in milliseconds
### 10.2 Nice-to-Have After MVP
- alternating visual pattern
@@ -623,7 +666,7 @@ Decision: do not promise exact brightness; expose conservative recommendation an
### 11.4 Unsafe Use Without Headphones
Risk: speaker playback breaks binaural assumptions.
Decision: block start/resume for audio-enabled session unless stereo headset route is detected; offer Visual-only fallback.
Decision: block start/resume for audio-enabled session unless stereo headset route is detected; offer Visual fallback.
### 11.5 Interruptions
Risk: call/notification/backgrounding may leave stimulation running.
@@ -651,41 +694,51 @@ Engineering should be able to test these directly.
### 12.2 Presets / Setup
5. Home displays exactly 3 built-in presets: Relax, Focus, Sleep Prep.
6. Tapping a preset opens Setup with correct default values.
7. Setup prevents Start when all stimulation modes are off.
7. Setup shows mode selection as a single segmented/toggle control with exactly one selected option: Audio, Audiovisual, or Visual.
8. Setup prevents Start when values are outside allowed ranges.
9. Setup allows duration changes only within 1–30 minutes.
10. Setup constrains flash interval to 50–2000 ms and labels the control in milliseconds.
11. Flash interval helper text explains that the value is time between flashes, not Hz.
12. Setup remains vertically scrollable and fully usable in both portrait and landscape orientations.
13. On devices with gesture/navigation bars or display cutouts, Setup keeps the bottom controls and Start action reachable and unobscured.
14. Setup validation and helper copy use user-facing interval/duration wording for timing controls; flash timing is never presented as Hz in config-facing UI.
### 12.3 Audio / Headphones
10. If audio mode is selected and no supported headset route is detected, Start is blocked.
11. If user chooses Visual-only, session can start without headphones.
12. During an audio-enabled session, headset disconnect causes session to pause within 1 second and shows recovery UI.
13. Resuming Audio+Visual is blocked until a valid headset route is restored.
15. If a selected mode includes audio and no supported headset route is detected, Start is blocked.
16. If user chooses Visual, session can start without headphones.
17. During an audio-enabled session, headset disconnect causes session to pause within 1 second and shows recovery UI.
18. Resuming Audiovisual is blocked until a valid headset route is restored.
### 12.4 Session Runtime
14. Starting a valid session enters countdown, then active full-screen mode.
15. Active session keeps screen awake until pause/stop/completion.
16. Remaining time updates correctly and reaches zero without negative values.
17. Pause stops stimulation and preserves remaining time.
18. Resume restarts from paused remaining time after resume countdown.
19. Stop ends stimulation immediately and does not resume automatically.
20. On natural completion, app shows completion screen with Repeat and Return Home.
19. Starting a valid session enters countdown, then active full-screen mode.
20. Any session with visual output enters forced landscape orientation before stimulation begins.
21. Active visual session renders stimulation in left/right screen halves.
22. Flash visual renders red and green states with black between flashes.
23. Active session keeps screen awake until pause/stop/completion.
24. Remaining time updates correctly and reaches zero without negative values.
25. Pause stops stimulation and preserves remaining time.
26. Resume restarts from paused remaining time after resume countdown.
27. Stop ends stimulation immediately and does not resume automatically.
28. On natural completion, app shows completion screen with Repeat and Return Home.
### 12.5 Interruptions / Safety
21. App backgrounding during session pauses stimulation immediately.
22. Incoming call or audio focus loss pauses session immediately.
23. After interruption, session never resumes without user action.
24. Fatal engine error stops all stimulation and presents user-safe recovery messaging.
29. App backgrounding during session pauses stimulation immediately.
30. Incoming call or audio focus loss pauses session immediately.
31. After interruption, session never resumes without user action.
32. Fatal engine error stops all stimulation and presents user-safe recovery messaging.
### 12.6 Accessibility / UI
25. All interactive controls outside active stimulation have accessible labels.
26. Primary controls meet 48 dp minimum target size.
27. Non-session text supports system font scaling without clipping primary actions.
28. Audio-only and Visual-only are available from Setup.
33. All interactive controls outside active stimulation have accessible labels.
34. Primary controls meet 48 dp minimum target size.
35. Non-session text supports system font scaling without clipping primary actions.
36. Audio, Audiovisual, and Visual are available from Setup as a single-choice control group.
37. Setup remains operable in portrait and landscape with vertical scrolling and without clipping the final action area.
38. Config-facing timing copy avoids Hz wording for flash interval and uses user-facing interval/duration terms instead.
### 12.7 Persistence
29. Last selected preset persists across app relaunch.
30. Settings persist across app relaunch.
31. Completion -> Repeat preloads the just-finished config.
39. Last selected preset persists across app relaunch.
40. Settings persist across app relaunch.
41. Completion -> Repeat preloads the just-finished config.
---
@@ -699,12 +752,20 @@ Use concise, plain copy. Avoid wellness hype and all medical claims.
“I understand the risks and will stop immediately if I feel discomfort.”
### 13.3 Headphone Warning
“Stereo headphones are required for binaural audio. Connect headphones or switch to Visual-only.”
“Stereo headphones are required for binaural audio. Connect headphones or switch to Visual.”
### 13.4 Completion Copy
- Completed: “Session complete.”
- Ended early: “Session ended.”
### 13.5 Flash Interval Helper Copy
“Flash interval is the time between flashes, in milliseconds. Lower numbers flash faster.”
### 13.6 Timing Error/Validation Copy Guidance
- Prefer: “Enter a flash interval between 50 ms and 2000 ms.”
- Avoid: user-facing error copy that describes flash timing in Hz
- For session length, prefer plain time wording such as minutes and seconds over technical labels
---
## 14. Implementation Notes for Product/UX Alignment
@@ -714,6 +775,18 @@ Use concise, plain copy. Avoid wellness hype and all medical claims.
- During active session, every interaction should reduce cognitive load, not add it.
- Safety text should be direct, not alarmist.
- The fastest valid path for a returning user should be: Home -> preset tap -> Start.
- Treat Audio / Audiovisual / Visual as mutually exclusive user-facing mode labels.
- Do not present mode choice as three plain buttons; it should read as one toggle group.
- For visual sessions, settle orientation/layout before stimulation begins to avoid flashing during rotation.
- On Setup, favor user-facing time language that matches the edited control: minutes/seconds for duration, milliseconds for flash interval.
- Setup should be designed as a scrollable form first, not a fixed-height panel; assume landscape, inset-heavy devices, and large text from day one.
- Keep the primary action reachable near the bottom with sufficient padding so gesture navigation areas do not compete with tapping.
## 14.1 Short UX Recommendations (MVP-safe)
- Consider making the Start button sticky or persistently visible once the user scrolls past the midpoint; this reduces hunting on small landscape screens.
- Group advanced edits under a simple “Fine-tune session” disclosure so the default preset path stays fast for first-time users.
- When audio is unavailable, offer a one-tap mode switch to Visual in the warning area instead of requiring the user to manually reselect mode.
- Add a compact summary row above Start (mode, duration, flash interval if applicable) so users can confirm their setup without rescanning the full form.
---
@@ -724,18 +797,28 @@ Use concise, plain copy. Avoid wellness hype and all medical claims.
- [ ] Implement bundled presets: Relax, Focus, Sleep Prep with defaults from this spec
- [ ] Persist safety acknowledgment version, settings, last preset, and repeat-session config locally
- [ ] Implement preflight validation for mode selection, parameter ranges, and headphone route
- [ ] Ensure Setup is vertically scrollable in portrait and landscape with safe-area/inset-aware bottom padding and reachable Start action
- [ ] Keep config-facing timing labels, helper text, and validation/error copy consistent with user-facing interval/duration language (no Hz wording for flash timing)
- [ ] Implement session countdown (Off/5/10 setting; default 5)
- [ ] Implement full-screen Active Session with hidden overlay controls and tap-to-reveal behavior
- [ ] Implement Flash and Pulse/Fade monochrome visual patterns only
- [ ] Implement Flash and Pulse/Fade visual patterns only
- [ ] Implement stereo binaural tone engine with carrier + binaural difference config
- [ ] Use shared session timeline / monotonic timing source for audio + visual coordination
- [ ] Implement pause, resume, stop, and natural completion flows
- [ ] Auto-pause on backgrounding, call/audio focus loss, and headphone disconnect
- [ ] Block/resume Audio+Visual only when valid stereo headset route is present
- [ ] Offer Visual-only fallback when audio requirements fail
- [ ] Block/resume Audiovisual only when valid stereo headset route is present
- [ ] Offer Visual fallback when audio requirements fail
- [ ] Keep screen awake during active session and release correctly afterward
- [ ] Add accessibility labels, minimum touch targets, scalable text, and safe alternative modes
- [ ] Add test coverage for onboarding gating, setup validation, session transitions, interruption handling, and persistence
- [ ] Keep all copy non-medical and aligned to the safety wording in this spec
### Brief UX Handoff Note for Andy
- Mode selector should feel unmistakably single-choice: one segmented/toggle group, one active state, immediate update of dependent controls.
- Temporary visual-session rule: if the selected mode includes visuals, lock to landscape before stimulation begins and render the session as left-half/right-half output.
- Flash is not white-on-black anymore for this temporary requirement: use red and green with black between flashes. Keep black as the resting state.
- Timing control is **interval in ms**, not frequency in Hz. UI labels, helper text, validation, and tests should all use ms language consistently, and config-facing errors should avoid Hz wording too.
- Setup should scroll cleanly in both portrait and landscape, with inset-aware spacing so the final controls and Start action remain comfortably reachable.
- Edge cases to handle cleanly: rotating into visual mode from Setup, resuming after interruption, switching from Audiovisual to Visual after headphone loss, and avoiding any visible flash during orientation/layout transitions.
If engineering must cut scope further, preserve in this order: safety gating -> stable session timing -> reliable audio -> full-screen visuals -> interruption handling -> polish.