MindMachine/ANDROID_MVP_SPEC.md

MindMachine Android MVP Product Specification

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.

This is a prototype for safe, reliable core experience. It is not a medical product and must not make medical or therapeutic claims.

---

2. MVP Scope

2.1 Goals

The MVP must prove that Android can reliably:

1. present required safety information before use,
2. guide the user through headphone + holder setup,
3. let the user choose a built-in preset,
4. run a timed session with synchronized visual + audio output,
5. handle pause, resume, stop, completion, and interruptions safely,
6. remain usable in low-light, near-eye conditions.

2.2 In Scope

• Android-only native app
• First-run onboarding and mandatory safety acknowledgment
• Home screen with built-in presets: Relax, Focus, Sleep Prep
• Session setup screen with limited edits to preset values
• Active session full-screen experience
• Pause/resume/stop controls
• Session completion screen
• Simple settings screen
• Audio-only and visual-only toggles
• Headphone guidance and runtime handling for output changes
• Keep-screen-awake behavior during session
• Persistence of acknowledgment state, last selected preset, and basic settings

2.3 Explicit Non-Goals for MVP

• Accounts, sync, cloud backup
• Custom preset creation/editor
• Ambient sounds
• Guided voice narration
• Printable holder templates
• Advanced visual editor
• Session history/analytics
• Medical/therapeutic workflows
• iOS version
• Social/community features

2.4 Product Decisions for Ambiguities

To make MVP implementation-ready, the following are fixed decisions:

• Platform: Android only
• Presets shipped: Relax, Focus, Sleep Prep only
• 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
• 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

---

3. Information Architecture

3.1 Primary Screens

1. Welcome / Intro
2. Safety Acknowledgment
3. Home / Preset List
4. Session Setup
5. Active Session
6. Session Paused Overlay
7. Interruption / Headphone Warning Sheet
8. Session Complete
9. Settings
10. Holder Guidance
11. About / Disclaimer (can live inside Settings)

3.2 Navigation Model

• Root stack navigation
• Default landing after first-run completion: Home
• Main forward path: Welcome -> Safety -> Home -> Setup -> Active Session -> Complete
• Settings and Holder Guidance reachable from Home and Setup
• During Active Session, user should not navigate elsewhere except via pause/stop/OS interruption handling

3.3 Back Navigation Rules

• Welcome/Safety: Back exits app or returns to previous onboarding step
• Home: Back exits app
• Setup: Back returns to Home
• Active Session: system back disabled or mapped to Pause sheet; must not silently exit session
• Complete: Back returns Home
• Settings/Holder Guidance: Back returns to prior screen

---

4. User Flows

4.1 First-Run Flow

1. User opens app
2. Welcome explains what the app does in plain language
3. User taps Continue
4. Safety screen shows warnings and disclaimers
5. User must check acknowledgment box and tap I Understand
6. App stores acknowledgment timestamp/version locally
7. User lands on Home

If user declines acknowledgment, app remains unusable for sessions and can only show info screens.

4.2 Returning User Quick Start

1. User opens app to Home
2. User selects preset card
3. Setup screen opens with preset defaults
4. User confirms mode and duration
5. User taps Start
6. If preflight passes, countdown begins
7. Active Session starts full-screen

4.3 Preflight Check Flow

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
• session duration valid
• app not already in active session

Outcomes:

• Pass -> countdown
• Recoverable issue -> inline warning or modal with action
• Blocking issue -> Start disabled until fixed

4.4 Session Flow

1. Countdown shows 5..1 or selected duration
2. Session enters full-screen mode
3. Visual pattern runs if enabled
4. Audio runs if enabled
5. Time remaining updates once per second
6. User may tap screen to reveal controls
7. User may Pause or Stop any time
8. If timer reaches zero, session ends automatically and safely

4.5 Pause / Resume Flow

1. User taps screen during session
2. Minimal controls appear
3. User taps Pause
4. Audio and visual engines pause immediately
5. Paused overlay appears with remaining time
6. User taps Resume -> 3-second resume countdown -> session restarts
7. User taps Stop -> confirmation sheet

4.6 Stop Flow

1. User taps Stop from controls or paused state
2. Confirmation sheet: Stop Session / Cancel
3. If confirmed, audio stops, visuals stop, wake behavior released, completion screen shown as “Session ended early”

4.7 Interruption Flow

Triggers include call, alarm takeover, audio focus loss, app backgrounding, screen off intent, headphone disconnect.

1. Session auto-pauses
2. Stimulation stops immediately
3. Interruption sheet explains reason
4. User options:
   • Resume when safe
   • End session
   • Switch to Visual-only if headphone route lost
5. Session never continues silently after interruption

4.8 Completion Flow

1. Timer reaches zero
2. Audio/visual output stop immediately
3. Completion screen shows preset name and session status
4. Actions: Repeat Session / Return Home

4.9 Settings Flow

User can modify:

• countdown preference (Off/5/10)
• default mode preference (Audio+Visual, Audio-only, Visual-only)
• 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)
• about/disclaimer access

---

5. Screen-by-Screen Requirements

5.1 Welcome / Intro

Purpose: orient first-time user.

Content:

• app name
• one-sentence explanation
• short bullet list: blinking light, binaural audio, stereo headphones, not medical
• Continue button

Behavior:

• shown only before safety acknowledgment
• dark theme
• no session actions available

States:

• default only

Acceptance notes:

• readable at standard phone sizes
• content fits without scroll on common devices where possible

5.2 Safety Acknowledgment

Purpose: mandatory risk disclosure.

Required warnings:

• flashing lights may be unsafe for people with epilepsy, seizure sensitivity, or migraine triggers
• do not use while driving, walking, cycling, or operating machinery
• stop immediately if discomfort, dizziness, headache, nausea, anxiety, or eye strain occurs
• binaural mode requires stereo headphones
• app is not a medical device

Components:

• scrollable warning text
• acknowledgment checkbox: “I understand the risks and will stop if I feel discomfort.”
• primary button: I Understand
• secondary link: Holder Guidance

Behavior:

• primary button disabled until checkbox checked
• acknowledgment persisted locally with content version

States:

• unchecked
• checked/enabled

5.3 Home / Preset Selection

Purpose: launch point for returning users.

Components:

• top app bar: title + Settings
• optional info action: Holder Guidance
• three preset cards: Relax, Focus, Sleep Prep
• each card shows duration, pattern type, beat frequency summary, short description
• optional footer disclaimer: not medical / use safely

Preset copy guidance:

• Relax: gentle pulse, slower beat
• Focus: steady flash, alert but conservative beat
• Sleep Prep: slow pulse, longest duration, low intensity

Behavior:

• tap card -> Session Setup for selected preset
• last used preset may show subtle “Last used” badge

States:

• default loaded
• empty state not applicable
• error state only if preset load fails: inline retry + fallback to bundled defaults

5.4 Session Setup

Purpose: confirm and lightly customize before start.

Components:

• selected preset header
• editable duration control
• visual mode section
• audio mode section
• headphone status row
• brightness recommendation row
• holder guidance link
• Start button

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
• 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
• 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

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
• brightness row is advisory text, not a system-permission flow
• optional “Show holder guidance” interstitial before countdown if setting enabled

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

States:

• default
• invalid field state
• blocked by missing headphones
• loading not needed beyond quick preset load

5.5 Holder Guidance

Purpose: give practical safe setup help.

Content blocks:

• use a simple cardboard visor/holder
• keep phone stable and hands-free
• do not press device against eyes/face
• allow airflow and comfort
• test fit before session
• sit or lie down in a safe place

Behavior:

• accessible from onboarding, Home, Setup
• dismiss returns to previous screen

5.6 Countdown

Purpose: prepare user before stimulation starts.

Components:

• full-screen dark background
• large numeric countdown
• short text: “Get comfortable. Session starting…”
• Cancel action

Behavior:

• start only after preflight passes
• cancellation returns to Setup
• audio/visual stimulation does not start until countdown completes

5.7 Active Session

Purpose: core session experience.

Default UI:

• full-screen stimulation surface
• overlay hidden by default
• tapping anywhere reveals controls for 3 seconds, then auto-hides

Overlay controls:

• Pause/Resume
• Stop
• remaining time
• preset/session name

Visual requirements:

• black background baseline
• white flash or white pulse/fade full-screen
• no extra text while overlay hidden
• no decorative animation unrelated to session timing

Audio requirements:

• continuous stereo tone generation when audio enabled
• no speaker fallback for binaural mode

Behavior:

• keep screen awake
• enter immersive full-screen mode
• prevent accidental exit
• stop means immediate cessation of stimulation
• if user locks screen or app backgrounds, auto-pause

States:

• running with overlay hidden
• running with overlay shown
• paused
• interrupted
• ending/completing

5.8 Paused Overlay

Components:

• Paused title
• remaining time
• Resume button
• Stop button

Behavior:

• stimulation off while paused
• resume uses 3-second countdown

5.9 Interruption / Headphone Warning Sheet

Triggers:

• headphones disconnected
• audio route changed from stereo headset to speaker/unknown
• incoming call / audio focus loss
• app backgrounded

Copy must explain exactly what happened and what session modes remain safe.

Actions:

• Resume Audio+Visual (only if requirements restored)
• Resume Visual-only
• End Session

5.10 Session Complete

Components:

• completion title
• preset name
• status message: Completed or Ended early
• Repeat Session button
• Return Home button

Behavior:

• Repeat restarts from Setup with prior values preserved
• no autoplay into another session

5.11 Settings

MVP contents:

• countdown preference
• default session mode
• show holder guidance before session
• re-open safety information
• about/disclaimer

Out of scope in Settings for MVP:

• account
• analytics
• session history
• downloadable presets

---

6. UI Component Specifications

6.1 Buttons

• Minimum touch target: 48x48 dp
• Primary buttons high contrast
• Disabled state clearly visible but readable
• Dangerous action button style for Stop/End Session

6.2 Preset Cards

• Entire card tappable
• Show title, short description, duration, mode summary
• Pressed state visible
• Support accessibility focus order and spoken summary

6.3 Toggles / Segmented Controls

Used for mode selection.

• Exactly one of: Audio+Visual / Audio-only / Visual-only
• state change updates dependent controls immediately
• disabling audio hides or disables headphone validation row

6.4 Sliders / Steppers

Used for duration and frequency values.

• live value label always visible
• changes preview in text only, not active stimulation
• values snap to safe increments

6.5 Warnings / Inline Errors

• concise, direct language
• use inline messaging near affected control
• blocking warnings also summarized above Start button

6.6 Confirmation Sheets

Used for Stop and risky state transitions.

• must not obscure primary action meaning
• destructive choice clearly labeled

---

7. States, Validation, Empty/Error/Loading

7.1 Global Loading

MVP should avoid heavy loading states. All built-in presets ship locally. Only acceptable loaders:

• app startup while loading local preferences
• brief transition while preparing session engines

7.2 Validation Rules

• at least one stimulation mode must be on
• duration must be within 1–30 min
• blink frequency 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
• safety acknowledgment required before any session start

7.3 Empty States

• none for Home in normal operation because presets are bundled
• if preset load fails, show fallback state with Retry and use embedded defaults automatically

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
• 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

7.5 Recovery Behavior

• users should always have a safe path to end session
• app should never continue flashing or playing audio after fatal error

---

8. Accessibility Requirements

1. All non-stimulation screens must support Android screen readers.
2. Interactive elements must have descriptive labels, roles, and state announcements.
3. Minimum touch target: 48 dp.
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.
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.

Note: the stimulation content itself is intentionally flashing/pulsing; accessibility work applies to surrounding UI and availability of safe alternatives.

---

9. Data Model and Data Needs

9.1 Core Product Models

SessionPreset

• id
• name
• description
• defaultDurationSec
• visualEnabledByDefault
• audioEnabledByDefault
• visualPatternType
• blinkFrequencyHz
• recommendedIntensityPercent
• carrierFrequencyHz
• binauralDifferenceHz
• cautionNote
• isBuiltIn
• sortOrder

SessionConfig

• presetId
• durationSec
• mode (audioVisual | audioOnly | visualOnly)
• visualPatternType
• blinkFrequencyHz
• intensityPercent
• carrierFrequencyHz
• binauralDifferenceHz

SessionRuntimeState

• sessionId
• presetId
• state (idle | countdown | running | paused | interrupted | completed | stopped | error)
• startTimeMonotonic
• elapsedSec
• remainingSec
• interruptionReason
• audioRouteState

AppSettings

• safetyAcknowledged
• safetyAcknowledgedVersion
• safetyAcknowledgedAt
• countdownPreference
• defaultModePreference
• showHolderGuidanceBeforeSession
• lastPresetId

9.2 Local Data Storage

Persist locally only:

• safety acknowledgment state/version
• app settings
• last selected preset
• last-used session values for quick repeat
• built-in presets (bundled in app, optionally mirrored into local DB/preferences)

No remote backend required for MVP.

9.3 Remote Data Needs

None for MVP. If crash reporting or analytics is later added, it must be explicitly reviewed and must not block MVP.

---

10. Must-Have vs Nice-to-Have

10.1 Must-Have for MVP

• Android native app
• first-run intro + mandatory safety acknowledgment
• built-in presets: Relax, Focus, Sleep Prep
• Home, Setup, Active Session, Completion, Settings, Holder Guidance
• audio+visual synchronized session engine
• pause/resume/stop
• countdown
• remaining time display
• full-screen flash and pulse patterns
• stereo binaural audio generation
• headphone-required handling for audio mode
• interruption-safe auto-pause behavior
• keep-screen-awake during session
• local persistence for acknowledgment + settings + last preset
• audio-only and visual-only modes

10.2 Nice-to-Have After MVP

• alternating visual pattern
• custom preset editor
• ambient sound layer
• session history
• printable holder template
• advanced color patterns
• spoken guidance
• richer brightness calibration

---

11. Risks and Concrete Mitigations

11.1 Audio Latency / Instability

Risk: glitches or startup delay. Decision: prioritize stable continuous generation over complex audio features; no ambient mixing in MVP.

11.2 Timing Drift Between Audio and Visual

Risk: UI-driven timing may drift. Decision: session timing derived from monotonic clock; visual/audio consume same session timeline.

11.3 Device Brightness Variability

Risk: inconsistent perceived intensity. Decision: do not promise exact brightness; expose conservative recommendation and in-app intensity only.

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.

11.5 Interruptions

Risk: call/notification/backgrounding may leave stimulation running. Decision: any significant interruption forces immediate pause and explicit resume.

11.6 User Comfort / Holder Confusion

Risk: uncomfortable or unsafe placement. Decision: ship concise holder guidance accessible in onboarding and setup; no printable template in MVP.

11.7 Scope Creep

Risk: custom sessions and advanced patterns delay MVP. Decision: lock MVP to built-in presets plus limited per-session edits.

---

12. Technical Acceptance Criteria

Engineering should be able to test these directly.

12.1 Onboarding / Safety

1. On first launch, app shows Welcome then Safety before Home.
2. User cannot access session start flow until safety acknowledgment is completed.
3. Safety acknowledgment persists across app relaunch.
4. If safety content version changes, user is asked to acknowledge again.

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.
8. Setup prevents Start when values are outside allowed ranges.
9. Setup allows duration changes only within 1–30 minutes.

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.

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.

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.

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.

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.

---

13. Recommended Content Defaults

Use concise, plain copy. Avoid wellness hype and all medical claims.

13.1 Safety Screen Headline

“Read before using MindMachine”

13.2 Safety Checkbox Copy

“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.”

13.4 Completion Copy

• Completed: “Session complete.”
• Ended early: “Session ended.”

---

14. Implementation Notes for Product/UX Alignment

• Keep non-session UI dark, minimal, and calm.
• Prefer step-based controls over free text.
• Avoid deep customization in MVP.
• 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.

---

15. Handoff for Andy

Explicit Implementation Checklist

• Build Android-only MVP with screens: Welcome, Safety, Home, Setup, Active Session, Completion, Settings, Holder Guidance
• 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
• 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 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
• 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

If engineering must cut scope further, preserve in this order: safety gating -> stable session timing -> reliable audio -> full-screen visuals -> interruption handling -> polish.