4a46417cba
- First-run safety notice (photosensitivity, clinical use, privacy); glow rate capped at 2.5Hz below the photosensitive trigger band - Patient data: initials/code hint, Export All / Wipe All buttons - Relay sessions get crypto-random room ids instead of guessable room-1 - Fix: Pan Sync off now actually stops pink-noise panning - Fix: slider drags no longer audibly restart the noise source - Fix: switching pink->discrete preset no longer leaves noise running - Fix: Speed Boost no longer compounds into stored speed across reloads - Fix: patient/preset names HTML-escaped in lists - Fix: patientViewport now relays over LAN (old server dropped it) - server.py rewritten stdlib-only: static site + WS relay in one process, no pip/venv; setup.sh/bat deleted, start scripts are now 3 lines - MIT LICENSE added; README rewritten with safety-first quick start Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
116 lines
5.2 KiB
Markdown
116 lines
5.2 KiB
Markdown
# 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](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.
|