backnforth/README.md

# backnforth — Bilateral Stimulation Simulator

A browser-based bilateral stimulation (BLS) tool: a therapist control panel
and a full-screen patient view, with visual, auditory, and mixed stimulus.
Built to run on whatever hardware exists — an old laptop, a donated desktop, a
second-hand phone as the patient screen. No accounts, no cloud, no installs,
works fully offline. If the fancy lightbar broke down, or there never was a
fancy lightbar, this is the backup plan.

## ⚠️ Safety first

- **Photosensitivity:** moving and pulsing visuals can trigger seizures in
  people with photosensitive epilepsy. Ask about seizure history before use,
  keep Glow Pulse rate low (the app caps it below the common trigger band),
  and stop immediately if the viewer feels unwell.
- **Clinical use:** bilateral stimulation can surface intense memories and
  emotions. This tool assists a trained clinician — it is not therapy by
  itself and is not for unsupervised trauma processing.
- **Privacy:** patient records and notes are stored unencrypted in the
  browser. Use initials or a code instead of full names, and treat the
  computer itself as part of the clinical record. There are Export/Wipe
  buttons in Patient Management.

## Quick start

**Easy Mode — start here.** `easy.html` is a big-buttons control page for
non-technical users: one start button, plain-word sliders (how fast, how big,
how loud), friendly sound names, a live preview of what the patient sees.
The full control panel (`index.html`) is one tap away under "Advanced
controls".

**One computer, two screens (nothing to run):**
1. Open `easy.html` in a browser.
2. Tap **Open patient screen**, drag that window to the patient-facing
   display, make it fullscreen.
3. One click on the patient view unlocks audio (browser rule).

**Two devices on the same Wi-Fi:**
1. Double-click `start-relay.command` (Mac) or `start-relay.bat` (Windows),
   or run `./start-relay.sh` (Linux). Needs only Python 3 — no pip, no
   installs, no internet. It serves the app and the relay in one process and
   opens Easy Mode for you.
2. Easy Mode connects to the relay automatically — tap **Copy link for
   patient's phone / tablet** and open it on the patient device; one tap
   there unlocks audio. (The advanced panel's Detect Local IP flow still
   exists too.)
3. Allow the firewall prompt (private networks) if one appears.

## The therapist panel

### Visuals
- **Shape**: circle, square, triangle · size slider · shape/background colors
  with swatches or custom picker.
- **Motion**: speed (px/s) with 1–4× boost, direction (left↔right, up↕down,
  diagonals), easing (linear or ease-in-out), edge pause, vertical position
  and gentle vertical oscillation, wiggle, ramp-up over 1–60 s.
- **Glow Pulse**: optional pulsing glow; rate capped at 2.5 Hz because the
  photosensitive-epilepsy trigger band starts around 3 Hz.

### Sound
- **Programmatic presets**: pink noise, hybrid (noise + edge cues), click,
  ping, woodblock, bell, bass, kick, snare, hi-hat, sweep, zap, bubble.
- **Tone designer**: frequency, duration, and full ADSR envelope, with tone
  presets from warm-low to crisp.
- **Panning**: discrete sounds pan to the edge the shape hits; pink noise can
  pan continuously (Pan Sync) or stay centered.
- **Your own audio**: pick a folder of MP3/WAV files; playback pans with the
  movement.

### Patients and sessions
- Save patients (initials or codes — see Safety), auto-recorded session
  history with durations, per-session notes.
- **Export All Patient Data** downloads a JSON backup; **Wipe All Patient
  Data** clears everything from the browser (two confirmations).

### Recording and replay (research/teaching)
- Record every settings change during a session, replay it exactly, and
  import/export recordings as JSON.

### Presets
- Save/apply/delete full setups (visuals + audio); import/export all presets
  as one JSON file.

### Controllers
- Map keyboard keys, MIDI notes/CCs, or a WebHID dial to actions: start/stop,
  speed, volume, toggles, next shape/direction/sound, lock.
- Press `L` to lock the interface against stray clicks; hold `U` to unlock.

## Network mode details

- The relay (`server.py`, Python 3 stdlib only) serves the therapist page on
  `http://<your-ip>:8000/` and the WebSocket relay on `ws://<your-ip>:8787`.
- **Session IDs are random by default** (e.g. `room-k3x9q2f1`). Anyone on the
  same network who knows a session ID can join it and control what the
  patient sees — leave the random ID alone and share only the join link.
- **Hosting it on the internet?** Run `server.py --tokens FILE` (one access
  code per line, `#` comments allowed). Hosts must present a valid code to
  open a session; patients never need one — they can only join a session
  that's already live, via the therapist's link. Without a code the app still
  works fully in one-computer mode.
- Stop the server with the **Stop Server** button (works from the therapist
  machine only) or `Ctrl+C` in the terminal.
- A manual peer-to-peer WebRTC mode exists for networks where the relay is
  blocked: create an offer on the admin, paste it on the patient, paste the
  answer back.

## Data storage

Everything stays in the browser on the therapist machine:

- Settings: `localStorage` key `bls_state` · presets: `bls_presets` ·
  patients/sessions: `bls_patients` · key mappings: `bls_mappings`
- Recordings: IndexedDB `bls_rec_db` (legacy `bls_recordings` auto-migrates)

Nothing is sent anywhere except live stimulus state to the patient view.

## License

MIT — see [LICENSE](LICENSE). You can freely copy, hack, and share this with
blessings.

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