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

One computer, two screens (easiest — nothing to run):

1. Open index.html in a browser. This is the therapist panel.
2. Click Open Patient View, 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 session relay in one process and opens the therapist page for you.
2. Click Detect Local IP — the patient join link is auto-copied.
3. Open that link on the patient device; one tap unlocks audio.
4. 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.
• 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. 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.