backnforth/README.md

# Bilateral Stimulation Simulator

Simple browser-based tool with a therapist panel and a full-screen Patient view. The therapist controls everything; the Patient views bilateral stimulus as per therapist settings. 

## User Guide

### Getting Started
- Open the app and stay on the Therapist (Admin) page; the Patient view mirrors whatever you set.
- For one computer with two screens: open the Patient view and move it to the patient-facing display, then go fullscreen.
- For two computers: you can also use Network Mode (details below in Nerd Stuff), but the simple two‑screen setup is usually easiest.
- Audio may need a single click in the Patient view to unlock — this is normal browser behavior.

### Set Up the Visuals
- Shape: choose Circle, Square, or Triangle.
- Size: drag the size slider to make the shape larger or smaller.
- Speed: use the speed slider; the number shows how fast the shape moves.
 - Direction: pick Left↔Right (horizontal), Up↕Down (vertical), or Diagonal.
- Color: pick a shape color and a background color; use the swatches or the color picker.
 - Easing and Edge Pause: choose smoother movement (Ease In‑Out) and optional short pauses at the edges.
 - Vertical Position: set a baseline (0–100%) for where the motion track sits.
 - Vertical Oscillation: toggle gentle up/down motion around the chosen baseline.
 - Extras: enable Glow Pulse, Wiggle, Ramp Speed.

### Sound Options
- Programmatic Sounds: built‑in cues like Pink Noise, Hybrid (noise plus edge hits), Click, Ping, Woodblock, Bell, Bass, Kick, Snare, Hi‑Hat, Sweep, Zap, Bubble.
- Pan Sync: optionally pan sound left/right in time with the movement.
- Volume: set an overall volume; use Test Sound to preview.
#### Tone Mode (ADSR)
- Frequency: pitch of the tone in Hertz (e.g., 440 Hz).
- Duration: how long the tone plays on each hit (milliseconds).
- Attack: time to rise from silence to full volume.
- Decay: time to fall from full volume down to the sustain level.
- Sustain: steady level held during the middle of the tone (0.0–1.0).
- Release: time to fade from the sustain level back to silence.
- Pan per hit: tones pan left/right to match where the shape hits the edges.
- Pan Sync (continuous): for pink noise, enables smooth left/right panning following movement.
- Pan Rate: speed of continuous panning when Pan Sync is on.

### Use Your Own Audio
- Choose Folder: select a folder of audio files (MP3/WAV). Then pick a track from the list.
- Play/Pan: the app can pan the file left/right to match movement.
- Tip: the first time you use audio, click once in the Patient view to unlock sound.

### Patients and Sessions
- Save Patient: enter a name and save. Patients are listed for quick loading later.
- Session History: each session records start/end time and duration automatically for the loaded patient.
- Session Notes: pick a session from the list, edit notes, and save; notes stay with the session.
- Manage: load an existing patient, clear a patient’s sessions, or delete a patient.
- Storage: patient info stays on your computer in the browser (no cloud backend).

### Record Movement Changes (Research/Teaching Tool)
- Start Recording: begin capturing every change you make (speed, size, direction, color, etc.).
- Stop & Save: end recording and name it; it appears in your recording list.
- Replay: select a recording and play it back to reproduce the exact sequence of changes.
- Export: save a recording as a JSON file — handy to share or archive.
- Import: load a previously exported JSON file back into your recording list.
- Clear/Delete: remove one recording or clear the entire list.

### Presets
- Save a Preset: name the current setup (visuals and audio) and save.
- Apply: pick a preset to immediately apply all saved settings.
- Delete: remove a preset you no longer need.
- Import/Export: backup or share all presets as a single JSON file.

### Controllers and Shortcuts
- Keyboard Mapping: map keys to actions like Start/Stop, Speed Up/Down, Volume Up/Down, Toggle Audio, Glow/Wiggle, Lock/Unlock, Record Start/Stop, Replay, and Next Shape/Direction/Easing/Sound.
- MIDI Controllers: connect a MIDI device and map buttons/knobs to the same actions; the mapping panel shows what’s currently assigned.
- HID Dial/Knob: connect a hardware dial via the “Connect HID” button, then turn the dial to change speed; adjust sensitivity if the dial feels too strong or too subtle.
- Lock/Unlock: press `L` to lock the interface (prevents accidental clicks). Hold `U` to unlock; the banner shows the lock status.

### Tips and Safety
- Go gently: start slow and simple. Adjust based on comfort.
- Pause anytime: you can stop motion and sound immediately.
- Everything is local: patients, presets, and recordings are stored on your device.

## Nerd Stuff

## How It Works

- Two pages:
  - Therapist (Admin) page: where you set motion, colors, and sounds
  - Patient page: fullscreen view that mirrors the Admin
- Two ways to show the Patient page:
  - Same computer (extended monitor): plug a second display facing the patient, open the Patient page on that display, go fullscreen — no network setup needed
  - Two computers on the same Wi‑Fi/LAN: start a tiny local server on the therapist’s computer so both can communicate, then the patient joins from their computer
- Audio note: most browsers need you to click on the page once to activate sound
- Go gently — adjust speed, colors, and sounds to what feels comfortable; pause whenever needed

## Super Simple Guide

### Windows
- First‑Time Setup
  - Double‑click `setup.bat`
  - Allow the Windows Defender Firewall prompt (Private networks)
  - Your browser opens at `http://<your‑IP>:8000/`; “Relay” turns green
- Every Session
  - Double‑click `start-relay.bat`
  - Click “Detect Local IP” in the app; the Patient link auto‑copies
- Stop Server
  - Use “Stop Server” in the app, or press `Ctrl + C` in the relay window

### macOS
- First‑Time Setup
  - Press `Cmd + Space` → type `Terminal` → press `Enter`
  - `cd` into the folder where you unzipped the app eg  'cd documents/bls-sim'
  - Copy and paste: `chmod +x ./setup.sh && ./setup.sh`
  - Allow the macOS firewall prompt (Private networks)
  - Your browser opens at `http://<your‑IP>:8000/`; “Relay” turns green
- Every Session
  - Press `Cmd + Space` → type `Terminal` → `Enter`
  - `cd` into the app folder
  - Copy and paste: `chmod +x ./start-relay.sh && ./start-relay.sh`
  - Click “Detect Local IP”; the Patient link auto‑copies
- Stop Server
  - Use “Stop Server” in the app, or press `Ctrl + C` in the relay Terminal

### Linux
- First‑Time Setup
  - Press `Ctrl + Alt + T` to open Terminal
  - `cd` into the app folder
  - Copy and paste: `chmod +x ./setup.sh && ./setup.sh`
  - Your browser opens at `http://<your‑IP>:8000/`; “Relay” turns green
- Every Session
  - Open Terminal → `cd` into the app folder
  - Copy and paste: `chmod +x ./start-relay.sh && ./start-relay.sh`
  - Click “Detect Local IP”; the Patient link auto‑copies
- Stop Server
  - Use “Stop Server” in the app, or press `Ctrl + C` in the relay Terminal

### What You Should See
- “Relay:” shows a green dot and “Running”
- “Detect Local IP” fills `ws://<your‑IP>:8787` and copies the Patient link
- Admin page loads at `http://<your‑IP>:8000/`

## Admin Options

- Shape
  - Options: Circle, Square, Triangle
- Shape Color
  - Picker + presets: Green, Blue, Yellow, Red, White
- Background Color
  - Picker + presets: Green, Blue, Yellow, Red, White
- Direction
  - Left↔Right, Up↕Down, Diagonal ↘, Diagonal ↗
- Speed
  - Range: 50–600 px/s
  - Speed Boost: 1×, 2×, 3×, 4× multiplier
- Size
  - Range: 10–100 px
- Vertical Position
  - Range: 0–100% (Reset to 50%)
- Glow Pulse
  - Enable/Disable
  - Glow Radius: 0–200%
  - Glow Rate: 0.1–3.0 Hz
- Ramp Speed
  - Enable/Disable, Seconds: 1–60
  - When disabled, motion uses constant speed (Linear)
- Smoothness / Easing
  - Linear (constant speed)
  - Ease In-Out (slows at edges)
- Edge Pause
  - Range: 0–150 ms
- Wiggle
  - Enable/Disable, Amplitude: 0–10 px

### Audio

- Audio Mode
  - Programmatic, From Files, Off
- Programmatic Presets
  - Pink Noise, Hybrid (noise + edge cues), Click, Ping, Woodblock
  - Bell, Bass, Kick, Snare, Hi-Hat, Sweep, Zap, Bubble
- Pan Sync to Movement
  - Toggle on/off
- Pan Rate (for continuous panning)
  - Range: 0.1–2.0 Hz
- Cue Rate (Hybrid)
  - Range: 0.1–3.0 Hz
- Volume
  - Range: 0–100%
- Test Sound
  - Plays the selected programmatic preset briefly

### File Audio

- Choose Folder, select track from dropdown (MP3/WAV)

### Presets (Admin)

- Save: Enter name and save current state
- Apply: Select from list and apply
- Delete: Remove a preset
- Import/Export: JSON of all presets

### Patient Management

- Patient Name: Save patient
- Load Patient: Select from list
- Clear Sessions: Reset history for loaded patient
- Delete Patient: Remove patient record
- Session History: Auto-listed with start/end time and duration

### Session Controls (Preview Panel)

- Timer (minutes)
- Start Session / End Session
- Status + Elapsed time

## Patient View

- Full-screen canvas with motion synced to Admin
- Audio unlock: most browsers require a user gesture (e.g., click or key press) before audio can play

## How to Run

- Open `index.html` and use the Admin panel
- Click “Open Patient View” to launch `patient.html` in a separate tab/window

### Controllers (Tech)
- Keyboard: uses standard keydown events and a mapping registry stored in `localStorage` (`bls_mappings`).
- MIDI: uses Web MIDI (`navigator.requestMIDIAccess`) and maps Notes/CCs to actions.
- HID: uses WebHID (`navigator.hid.requestDevice`) and listens to `inputreport`; example HID dial adjusts speed with sensitivity scaling.
- Gamepad: not implemented.

## Network Mode Setup (Two Computers on the Same Wi‑Fi/LAN)

### Overview
- Therapist runs a lightweight relay (`server.py`) once on their computer.
- Admin connects to the relay with a Session ID and copies the Patient Join Link.
- Patient opens the link on their computer and performs a quick gesture to unlock audio.

### Quick Start (Double‑Click or Copy‑Paste)
- macOS (double‑click): open the folder and double‑click `start-relay.command`.
- macOS (copy‑paste): `chmod +x ./start-relay.sh && ./start-relay.sh`
- Windows (double‑click): open the folder and double‑click `start-relay.bat`.
- Windows (copy‑paste): `start-relay.bat`
- These start scripts auto‑create a local Python virtual environment, install `websockets`, print your LAN relay URL, and run the relay on port `8787`.

### First‑Time Setup (Recommended)
- macOS/Linux:
  - `chmod +x ./setup.sh && ./setup.sh`
- Windows:
  - Double‑click `setup.bat`
- What it does:
  - Creates a local virtual environment and installs `websockets`
  - Starts the static site server on `http://<IP>:8000/`
  - Starts the WebSocket relay on `ws://<IP>:8787`
  - Opens the Admin page in your browser at `http://<IP>:8000/`

### Every Session (Start/Stop)
- Start Server:
  - macOS/Linux: `chmod +x ./start-relay.sh && ./start-relay.sh`
  - Windows: `start-relay.bat`
- Stop Server:
  - Use the Admin page “Stop Server” button, or press `Ctrl + C` in the relay terminal

### One‑Time Install (WebSocket Relay)
- Windows:
  - Press `Windows` key → type `PowerShell` → `Enter`
  - Check Python: `python --version` (or `py --version`)
  - Quick option: double‑click `start-relay.bat` (or run it in PowerShell/CMD)
  - Manual option: `python -m pip install websockets` (or `py -m pip install websockets`), then `python server.py` (or `py server.py`)
  - If prompted by Windows Defender Firewall, click “Allow access”.
- macOS:
  - Press `Cmd+Space` → type `Terminal` → `Enter`
  - Check Python: `python3 --version`
  - Quick option: double‑click `start-relay.command` (or run `chmod +x ./start-relay.sh && ./start-relay.sh`)
  - Manual option: `python3 -m pip install websockets`, then `python3 server.py`
- Linux (Ubuntu/Debian/Fedora etc.):
  - Press `Ctrl+Alt+T` to open Terminal
  - Check Python: `python3 --version`
  - Quick option: `chmod +x ./start-relay.sh && ./start-relay.sh`
  - Manual option: `python3 -m pip install websockets`, then `python3 server.py`

### Find Your Therapist Computer’s IP Address
- Windows: run `ipconfig` → use the `IPv4 Address` on your active adapter (e.g., `192.168.1.5`).
- macOS: run `ipconfig getifaddr en0` (Wi‑Fi) or `ipconfig getifaddr en1` (alternate); or `ifconfig | grep "inet "`.
- Linux: run `hostname -I` and pick the local `192.168.x.x` address; or `ip addr show`.

### Connect Admin (Therapist Computer)
1) Open Admin in a browser: `http://localhost:8000/`
2) In “Network Mode”:
   - Server URL: `ws://<THERAPIST_IP>:8787` (e.g., `ws://192.168.1.5:8787`)
   - Session ID: any label you like (e.g., `room-1`)
   - Click `Connect`
3) Copy the Patient Join Link shown below the connection fields.

### Connect Patient (Second Computer)
1) Open the copied Patient Join Link in a browser
2) Perform a quick gesture (mouse move or key press) to unlock audio (browser policy)
3) The Patient view will mirror Admin changes in real time

### Tips
- If the Patient does not connect, verify both computers are on the same network and can reach `ws://<THERAPIST_IP>:8787`.
- On Windows, allow the relay through the firewall when prompted.
- You can disconnect Network Mode and continue Local Mode at any time.

## Display Options

- Same Computer (Extended Display)
  - Connect a second monitor facing the patient
  - Open `patient.html` in a second browser window
  - Drag the Patient window to the patient‑facing monitor and use browser fullscreen
  - Audio unlock: have the patient do one quick gesture (mouse/key) on the Patient screen
  - Pros: zero network setup, minimal friction

- Separate Computer (LAN WebSocket)
  - Use the Network Mode steps above with the Python relay
  - Share the short Patient link (e.g., `http://<therapist-ip>:8000/patient.html#room-1`)
  - Audio unlock: one quick gesture on the Patient device; Programmatic audio is recommended

## Data Storage

- Presets: `localStorage` key `bls_presets`
- Patients: `localStorage` key `bls_patients`
- App State (current settings): `localStorage` key `bls_state`
- Recordings: IndexedDB database `bls_rec_db`, store `recordings` (legacy `localStorage` key `bls_recordings` may exist and is auto‑migrated)

## Notes

- If Audio is enabled and Programmatic mode is selected, the Patient tab may need one user interaction to unlock audio
- Speed Boost multiplies the slider value for effective motion speed

## ⚠️ Disclaimer

This tool is for research, education, and personal experimentation with bilateral stimulation, or maybe the fancy lightbar broke down and you need a backup option, or maybe you sprained both your index fingers. It is NOT a substitute for professional therapy, diagnosis, or treatment. Use at your own discretion. You can freely copy or share this with blessings.