feat(mindmachine): implement Android MVP app scaffold, session flows, safety gating, and tests
This commit is contained in:
Tretzi
265
REQUIREMENTS.md
Normal file
265
REQUIREMENTS.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# MindMachine - Requirements
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
MindMachine is a mobile phone application that turns a smartphone into a simple audiovisual mind machine. The phone display presents controlled blinking light patterns while stereo audio playback generates binaural beats through headphones. The device is intended to be placed directly in front of the user's eyes using a lightweight cardboard holder, similar in concept to simple glasses or a visor, so the phone can remain positioned comfortably and hands-free.
|
||||
|
||||
The application is intended for relaxation, focus sessions, meditation support, and guided sensory sessions. It is not a medical device and must not make medical or therapeutic claims.
|
||||
|
||||
---
|
||||
|
||||
## 2. Product Goals
|
||||
|
||||
The application shall:
|
||||
- provide synchronized visual blinking patterns on the display,
|
||||
- provide synchronized binaural audio through stereo headphones,
|
||||
- allow the user to start sessions quickly with minimal setup,
|
||||
- support safe and comfortable hands-free use with a simple DIY cardboard holder,
|
||||
- provide configurable sessions for different intended outcomes such as relaxation, focus, and sleep preparation,
|
||||
- remain simple, readable, and reliable during use in dark or eyes-closed/near-eye conditions.
|
||||
|
||||
---
|
||||
|
||||
## 3. Core User Scenario
|
||||
|
||||
A user launches the app, selects a session preset, connects stereo headphones, places the phone into a cardboard holder positioned in front of the eyes, and starts the session. During the session:
|
||||
- the screen displays flashing or pulsing light patterns,
|
||||
- the audio engine outputs binaural tones independently to the left and right channels,
|
||||
- the app keeps the screen awake,
|
||||
- the user may pause, resume, or stop the session easily.
|
||||
|
||||
---
|
||||
|
||||
## 4. Target Users
|
||||
|
||||
### Primary users
|
||||
- people interested in meditation or relaxation,
|
||||
- users experimenting with audiovisual entrainment,
|
||||
- hobbyists building a simple DIY mind machine with a smartphone.
|
||||
|
||||
### Secondary users
|
||||
- developers and designers evaluating guided sensory experiences,
|
||||
- technically curious users wanting to customize frequencies and session behavior.
|
||||
|
||||
---
|
||||
|
||||
## 5. Functional Requirements
|
||||
|
||||
### 5.1 Session management
|
||||
The application shall:
|
||||
- allow the user to start a session from a preset list,
|
||||
- allow the user to create custom sessions,
|
||||
- allow the user to pause, resume, and stop a running session,
|
||||
- display remaining session time,
|
||||
- support session durations configurable by the user,
|
||||
- optionally support a short countdown before the session begins.
|
||||
|
||||
### 5.2 Visual stimulation
|
||||
The application shall:
|
||||
- display full-screen blinking or pulsing visual patterns,
|
||||
- support left/right symmetric visual output suitable for near-eye viewing,
|
||||
- support multiple pattern types, including at minimum:
|
||||
- full-screen flash,
|
||||
- pulse/fade,
|
||||
- alternating brightness patterns,
|
||||
- color-based patterns,
|
||||
- allow configuration of blink frequency,
|
||||
- allow configuration of brightness/intensity within safe device limits,
|
||||
- provide a dark screen or dim idle state between pulses when required by the selected pattern,
|
||||
- keep the display active for the duration of the session.
|
||||
|
||||
### 5.3 Audio stimulation
|
||||
The application shall:
|
||||
- generate stereo audio suitable for headphones,
|
||||
- generate binaural beat output by sending different frequencies to the left and right channels,
|
||||
- allow configuration of carrier frequency,
|
||||
- allow configuration of binaural beat difference frequency,
|
||||
- allow adjustment of output volume within the app,
|
||||
- optionally mix ambient background sound such as rain, noise, or soft drones,
|
||||
- continue audio playback reliably during the active session unless the user stops it.
|
||||
|
||||
### 5.4 Synchronization
|
||||
The application shall:
|
||||
- synchronize visual stimulation timing with the active session timeline,
|
||||
- allow session presets where light frequency and binaural frequency are coordinated,
|
||||
- minimize drift between visual events and audio timing as much as practical on the device.
|
||||
|
||||
### 5.5 Presets
|
||||
The application shall include built-in presets such as:
|
||||
- Relaxation,
|
||||
- Meditation,
|
||||
- Focus,
|
||||
- Sleep preparation,
|
||||
- Custom.
|
||||
|
||||
Each preset should define at minimum:
|
||||
- session length,
|
||||
- visual pattern type,
|
||||
- visual blink rate,
|
||||
- audio carrier frequencies,
|
||||
- binaural beat difference,
|
||||
- brightness recommendation,
|
||||
- safety notes if relevant.
|
||||
|
||||
### 5.6 DIY holder guidance
|
||||
The application shall:
|
||||
- include a brief guide explaining how to build or fold a simple cardboard holder,
|
||||
- explain how the phone should be positioned relative to the eyes,
|
||||
- explain how to keep the phone stable without hand use,
|
||||
- explain that the holder should avoid pressure on the eyes or face,
|
||||
- explain that ventilation and comfort matter during longer sessions.
|
||||
|
||||
### 5.7 Safety and warnings
|
||||
The application shall:
|
||||
- show a safety warning before first use,
|
||||
- require the user to acknowledge warnings before starting the first session,
|
||||
- warn users not to use the app while driving, walking, cycling, or operating machinery,
|
||||
- warn users with epilepsy, seizure sensitivity, migraines triggered by flashing light, or similar conditions not to use the visual stimulation mode without medical clearance,
|
||||
- warn users to use stereo headphones for binaural mode,
|
||||
- warn users to stop immediately if discomfort, dizziness, nausea, eye strain, anxiety, or headache occurs.
|
||||
|
||||
### 5.8 Accessibility and fallback behavior
|
||||
The application shall:
|
||||
- allow audio-only sessions,
|
||||
- allow visual-only sessions,
|
||||
- provide large, clear controls for start, pause, resume, and stop,
|
||||
- use simple language for all safety and setup instructions,
|
||||
- avoid cluttered UI during active sessions.
|
||||
|
||||
---
|
||||
|
||||
## 6. Non-Functional Requirements
|
||||
|
||||
### 6.1 Performance
|
||||
The application should:
|
||||
- launch quickly,
|
||||
- begin sessions with minimal delay,
|
||||
- maintain steady audio output without stutter under normal device conditions,
|
||||
- maintain visually stable timing within practical mobile device limits.
|
||||
|
||||
### 6.2 Reliability
|
||||
The application shall:
|
||||
- recover gracefully from interruptions such as audio route changes,
|
||||
- handle headphone disconnection safely,
|
||||
- stop or pause the session if audio output becomes invalid for binaural use,
|
||||
- avoid accidental screen sleep during active sessions.
|
||||
|
||||
### 6.3 Usability
|
||||
The application shall:
|
||||
- support one-handed setup before the session starts,
|
||||
- require very few steps to launch a preset session,
|
||||
- present a calm, minimal interface appropriate for low-light use,
|
||||
- make all important settings understandable without technical knowledge.
|
||||
|
||||
### 6.4 Maintainability
|
||||
The system should be structured so that:
|
||||
- visual pattern generation, audio generation, session timing, preset management, and safety flows are separate components,
|
||||
- new presets and stimulation modes can be added without large architectural changes,
|
||||
- platform-specific media or brightness handling is isolated cleanly.
|
||||
|
||||
---
|
||||
|
||||
## 7. User Experience Requirements
|
||||
|
||||
### 7.1 First-run experience
|
||||
On first launch, the application shall:
|
||||
- explain what the app does in simple terms,
|
||||
- explain that stereo headphones are required for binaural beats,
|
||||
- explain how to position the phone using a cardboard holder,
|
||||
- present the main safety warnings,
|
||||
- guide the user to a first starter session.
|
||||
|
||||
### 7.2 Session setup screen
|
||||
The setup screen shall show:
|
||||
- selected preset,
|
||||
- session duration,
|
||||
- visual mode,
|
||||
- audio mode,
|
||||
- headphone status if detectable,
|
||||
- brightness level recommendation,
|
||||
- a clear Start button.
|
||||
|
||||
### 7.3 Active session screen
|
||||
The active session screen shall:
|
||||
- switch to full-screen mode,
|
||||
- show the active blinking pattern,
|
||||
- provide minimal overlay controls,
|
||||
- allow pause and stop actions,
|
||||
- display remaining time when the overlay is shown,
|
||||
- avoid distracting text during the running session.
|
||||
|
||||
### 7.4 Session completion
|
||||
At the end of a session, the application shall:
|
||||
- stop flashing and audio safely,
|
||||
- return brightness and audio state as appropriate,
|
||||
- show a completion screen,
|
||||
- allow the user to repeat the session, save it, or return home.
|
||||
|
||||
---
|
||||
|
||||
## 8. Safety-Critical Constraints
|
||||
|
||||
The application must not:
|
||||
- present itself as a medical, therapeutic, or diagnostic product,
|
||||
- force maximum brightness without user awareness,
|
||||
- continue a visual stimulation session after the user presses Stop,
|
||||
- assume the user is wearing headphones if stereo output is unavailable,
|
||||
- hide seizure-related flashing-light warnings.
|
||||
|
||||
The application should:
|
||||
- default to conservative brightness and intensity settings,
|
||||
- provide extra caution around high-frequency or high-contrast flashing modes,
|
||||
- make it easy to disable visual stimulation entirely.
|
||||
|
||||
---
|
||||
|
||||
## 9. Technical Considerations
|
||||
|
||||
The implementation will likely need:
|
||||
- precise audio generation for separate left/right stereo channels,
|
||||
- a timing engine for synchronized session events,
|
||||
- high-brightness full-screen rendering while respecting device limits,
|
||||
- screen wake lock / keep-awake behavior,
|
||||
- optional airplane-mode recommendation to reduce interruptions,
|
||||
- handling for notifications or incoming calls during a session.
|
||||
|
||||
If built natively for Android, the app should use Android audio APIs and full-screen rendering in a way that keeps latency and timing stable.
|
||||
|
||||
---
|
||||
|
||||
## 10. Out of Scope (Initial Version)
|
||||
|
||||
The first version does not need to include:
|
||||
- biometric sensors,
|
||||
- adaptive biofeedback,
|
||||
- cloud sync,
|
||||
- social features,
|
||||
- account creation,
|
||||
- medical treatment recommendations,
|
||||
- VR headset integration,
|
||||
- remote multi-user sessions.
|
||||
|
||||
---
|
||||
|
||||
## 11. Open Questions
|
||||
|
||||
The following product questions should be answered before implementation:
|
||||
- What exact session presets should ship in version 1?
|
||||
- Should the app target Android only, or Android and iPhone?
|
||||
- Should visual patterns be monochrome, color-based, or both?
|
||||
- Should ambient sounds be bundled locally or added later?
|
||||
- Should the cardboard holder guide include printable templates?
|
||||
- Should the app support spoken guidance during sessions?
|
||||
- What safety constraints should be enforced around maximum flash rate and brightness?
|
||||
|
||||
---
|
||||
|
||||
## 12. Success Criteria
|
||||
|
||||
The product will be considered successful for version 1 if:
|
||||
- a user can start a working mind machine session in a few steps,
|
||||
- the phone can reliably display blinking patterns while outputting binaural audio,
|
||||
- the app clearly communicates safe usage,
|
||||
- the user can comfortably use a simple holder to keep the phone in place,
|
||||
- preset and custom sessions both work reliably,
|
||||
- the documentation is clear enough for review, implementation, and end-user use.
|
||||
Reference in New Issue
Block a user