ΨWAVE — Quantum Instrument

A browser-based theremin/synthesizer/sequencer with MIDI output, OSC bridge for Ableton Live, and real-time data streaming to TouchDesigner.

---

What It Is

ΨWAVE (pronounced Psi-Wave) is a playable quantum-themed instrument built from first principles using the Web Audio API. It operates as three things simultaneously:

1. A standalone instrument — play it in any modern browser, no plugins, no installs
2. A MIDI controller — outputs standard MIDI via Web MIDI API to any DAW
3. An OSC data source — streams continuous performance data to Ableton Live and TouchDesigner via a Node.js OSC bridge

The "quantum" aesthetic is functional, not decorative. Three quantum-inspired modes change the synthesis behavior:

Mode	Physics Metaphor	Audio Behavior
Superposition	Multiple states until observed	Dual-oscillator with micro-detuning
Entanglement	Correlated at a distance	Automatic octave coupling
Wave Collapse	Single definite state	Monophonic mode, one note at a time

---

Play It

Open src/index.html in Chrome or Edge (Web MIDI requires Chromium).

Controls

Input	Action
Mouse drag in field	XY theremin — X=pitch, Y=velocity
Z X C V B N M	Chromatic keyboard (bottom row)
A S D F G H J	Chromatic keyboard (top row)
Space	Play / Stop sequencer
Knob drag / scroll	Adjust parameter
BPM display drag	Adjust tempo
Pitch ribbon (right edge)	Pitch bend ±100 cents

---

Architecture

Browser (ΨWAVE)
  Web Audio API · Web MIDI API · WebSocket client
       |                  |
  MIDI (direct)     WebSocket :8080
       |                  |
  DAW via OS        OSC Bridge (Node.js)
  IAC / Loop           osc-bridge/server.js
                         |            |
                      UDP :9000    UDP :7000
                         |            |
                    Ableton Live  TouchDesigner

---

Testing

JavaScript (Jest)

npm test                # run all JS tests
npm run test:coverage   # with coverage report
npm run test:watch      # watch mode

Python (pytest)

pip install pytest
python -m pytest        # runs tests/ against Ableton and TouchDesigner modules

Tests live in tests/. CI runs both suites automatically on every push via GitHub Actions (.github/workflows/test.yml).

---

Setup

Standalone (browser only)

# Just open the file — no server needed
open src/index.html

With Ableton Live / TouchDesigner

cd osc-bridge
npm install
node server.js

Then open src/index.html — the status indicators will go green.

See ableton/ABLETON_SETUP.txt and touchdesigner/TOUCHDESIGNER_SETUP.txt.

---

OSC Message Reference

All messages broadcast to both Ableton (:9000) and TouchDesigner (:7000):

/psiwave/note          int(midi)  int(velocity)  float(hz)
/psiwave/noteoff       note
/psiwave/freq          float(hz)
/psiwave/amp           float(0-1)
/psiwave/xy            float(x)  float(y)
/psiwave/pitchbend     float(cents -100..+100)
/psiwave/waveform      string
/psiwave/superposition int(0|1)
/psiwave/entanglement  int(0|1)
/psiwave/collapse      int(0|1)
/psiwave/seq/step      int(0-15)
/psiwave/param/*       float(0-1)

---

MIDI CC Map

CC	Parameter	CC	Parameter
73	Attack	91	Reverb
75	Decay	94	Delay
64	Sustain	78	Distortion
72	Release	74	Chaos
E0	Pitch Bend (14-bit)	76	Detune

---

Scales

ΨWAVE snaps notes to the selected scale in real time: Chromatic · Major · Minor · Pentatonic · Whole Tone · Diminished · Phrygian

---

Sequencer

16-step, 4-row grid. Each row maps to a pitch interval (root, 5th, octave, 5th+octave). Click to toggle steps, drag BPM, press Space to start/stop. Broadcasts /psiwave/seq/step on every tick for TD animation sync.

---

File Structure

quantum-instrument/
├── src/
│   └── index.html              ← Main instrument (open this)
├── osc-bridge/
│   ├── server.js               ← Node.js OSC/WebSocket bridge
│   └── package.json
├── touchdesigner/
│   ├── psiwave_td.py           ← TD Python integration script
│   └── TOUCHDESIGNER_SETUP.txt
├── ableton/
│   └── ABLETON_SETUP.txt
└── README.md

---

Browser Requirements

Web Audio API (Chrome 66+, Firefox 76+, Safari 14+) · Web MIDI API (Chrome/Edge) · WebSocket (any modern browser)

---

License

MIT — use, modify, perform, sell. Attribution appreciated.

Built with Web Audio API, Web MIDI API, OSC, and obsessive attention to the physics of sound.