MindMachine/ANDROID_MVP_SPEC.md

# 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.

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:** 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

---

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

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. When the user ends a session, audio stops, visuals stop, wake behavior released, completion screen shown as “Session ended early” (no confirmation dialog).

### 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 Audiovisual (only if requirements restored)
   - Resume Visual
   - End session
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 (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)
- 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
- session mode segmented/toggle control
- visual mode section
- audio mode section
- headphone status row
- brightness recommendation row
- 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 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
- 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, 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 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
- 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:
- force landscape orientation while visual output is active
- split stimulation into left and right screen halves
- black background baseline
- 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

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
- 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
- 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 Audiovisual (only if requirements restored)
- Resume Visual
- 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 / 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 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

### 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
- exactly one session mode must be selected
- duration must be within 1–30 min
- flash interval must remain within allowed range
- carrier frequency and beat difference must remain in allowed range
- if selected mode includes audio, 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 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

### 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** 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 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.

---

## 9. Data Model and Data Needs

## 9.1 Core Product Models

### SessionPreset
- id
- name
- description
- defaultDurationSec
- visualEnabledByDefault
- audioEnabledByDefault
- visualPatternType
- flashIntervalMs
- recommendedIntensityPercent
- carrierFrequencyHz
- binauralDifferenceHz
- cautionNote
- isBuiltIn
- sortOrder

### SessionConfig
- presetId
- durationSec
- mode (audioVisual | audioOnly | visualOnly)
- visualPatternType
- flashIntervalMs
- 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
- 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
- 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 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 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
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
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
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
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
39. Last selected preset persists across app relaunch.
40. Settings persist across app relaunch.
41. 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.”

### 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
- 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.
- 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.

---

## 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
- [ ] 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 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 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.