MIDI Setup
General MIDI setup guidance for BeamTracer apps — Web MIDI requirements, browser permissions, MIDI Learn and Program Change.
MIDI control is available in OSC-1 Oscilloscope, Audio Visualizers, and the laser tools, where a pad can black out or stop the laser and nothing else. All of them use the Web MIDI API. Chrome and Edge work directly; Firefox asks you to approve a one-time site-permission add-on.
Web MIDI works in Chrome and Edge, and in Firefox after a one-time site-permission add-on. Safari does not support Web MIDI. Connect your controller before opening the page so Firefox can show its permission prompt.
First-Time Setup
- Connect your MIDI device via USB before opening the browser
- Open OSC-1 or Visualizers in Chrome, Edge, or Firefox
- When prompted, click Allow to grant MIDI access. In Firefox, approve the one-time site-permission add-on.
- Your device appears in the app's MIDI settings — OSC-1: Settings → MIDI; Visualizers: Performer Settings → MIDI; laser tools: Laser Output → ADVANCED → MIDI LEARN
If Chrome or Edge does not prompt for MIDI permission, open the browser's MIDI site settings and ensure MIDI access is set to ask. In Firefox, connect the controller before reloading the page; you can review the permission under Add-ons and themes → Site Permissions.
macOS — MIDI Permissions (macOS 13+)
On macOS Ventura and later, your browser needs explicit MIDI permission:
- System Settings → Privacy & Security → MIDI
- Enable Chrome, Edge, or Firefox in the list
Windows
Most class-compliant MIDI devices need no extra driver on Windows 10/11. If your device isn't detected, check Device Manager to verify the device is recognized by the OS, and install the manufacturer's driver when the device requires one.
MIDI Learn
OSC-1 — M buttons
A small M button sits next to every mappable knob, slider and button. It learns a MIDI control or an OSC message:
- Left-click the M button — it pulses while waiting
- Move a control or press a button on your device, or send an OSC message
- Done — the button shows the CC number (N and the note number for a pad or key, OSC for an OSC address) and the mapping is active immediately
Right-click the M button to remove an existing mapping. If you don't see the buttons, enable them under Settings → MIDI → Show MIDI Learn Buttons.
To map several controls in a row, click START MIDI LEARN in Settings → MIDI: every M button is outlined, and each click-then-move saves one mapping until you click DONE or press Esc. Settings → MIDI → LEARNED MAPPINGS lists every mapping with a remove button and CLEAR ALL. A knob takes over a control only once it reaches the control's current value, so nothing jumps. See Hardware Control.
Audio Visualizers — START MIDI LEARN
- Open Performer Settings → MIDI and click START MIDI LEARN — Settings closes and a MIDI LEARN bar appears
- Open the visualizer's settings: every slider, toggle and button is outlined. Performer controls without a slider (OUTPUT LEVEL, BLACKOUT, NEXT PRESET, PREVIOUS PRESET, TAP TEMPO) are buttons in the bar
- Click a control, then move a knob or press a pad — the bar names the mapping
- Click DONE or press Esc
Performer Settings → MIDI → LEARNED MAPPINGS lists every mapping with a remove button and CLEAR ALL. See MIDI Integration.
OSC messages
MIDI Learn accepts OSC in every app: after you click a control, send an OSC message from TouchOSC, TouchDesigner, QLab or any show-control software instead of moving a knob. OSC reaches the browser through an OSC bridge on your computer; connect it under Settings → OSC in OSC-1, Performer Settings → OSC in Audio Visualizers, or Laser Output → ADVANCED → OSC in the laser tools. The MIDI LEARN panel and its LEARNED MAPPINGS list also appear in OSC-1's and Audio Visualizers' OSC settings; in the laser tools they sit beside OSC under ADVANCED.
- Only a value that moves is learned, so software that sends several addresses all the time maps the one you move.
- The first value sets the range the control spans (0 to 1, −1 to 1, 0 to 127, or wider), and the range grows if your software sends past it. An OSC row in LEARNED MAPPINGS shows it, such as AUTO 0–1; click it to type a range.
- A message with no value, or a value rising into the top half of the range, presses a button once.
- Each control has one mapping, MIDI or OSC. Learning one replaces the other, and the MIDI LEARN line names what it replaced.
- Camera controls (the Performer's camera and OSC-1's 3D camera) glide to each new value. CAMERA SMOOTHING, under LEARNED MAPPINGS, sets how much; OFF jumps. The Performer also answers fixed
/beamtracer/viz/…addresses without learning — see Control BeamTracer from TouchDesigner.
See OSC Learn in OSC-1.
Laser tools — BLACKOUT and STOP only
In the laser tools, MIDI and OSC can turn the laser off and nothing else. Open the Laser Output panel's ADVANCED section and click START MIDI LEARN. The MIDI LEARN bar lists LASER BLACKOUT and LASER STOP; click one, then press a pad or send an OSC message. In OSC-1, the same two buttons appear in the bar when you start learn from Settings → MIDI. A blackout pad latches: letting go does not relight the laser, and RELEASE BLACKOUT and START on screen are always needed to resume. See MIDI blackout.
Saving mappings
On a paid plan, every app keeps your mappings in your browser and restore them on the next visit, and mapped knobs respond as soon as the page loads once you have allowed MIDI for the site; on the Free plan they last until you reload. In OSC-1, Export saves the MIDI and OSC mappings to a JSON file and Import loads one back — use them to back up a controller layout or move it to another machine. Both buttons are in Settings → MIDI.
The MIDI channel is captured automatically per mapping at learn time — there is no global Input Channel setting for mappings. Whatever channel your controller sent during learn is the channel that mapping listens on. Program Change is the one exception: it has its own Channel setting, described below.
Program Change — switch presets from your controller
Both apps switch presets when your controller or DAW sends a MIDI Program Change. Program 0 selects the first preset, program 1 the second, and so on. A program number past the last preset selects the last preset. Many controllers and DAWs count programs from 1, so their "Program 1" selects the first preset.
| App | Where the setting lives | What "first preset" means |
|---|---|---|
| OSC-1 | Settings → MIDI → Program Change | The first button in Scope Presets; the eight built-in presets come first, then My Presets in the order listed |
| Audio Visualizers | Performer Settings → MIDI → PROGRAM CHANGE → Channel | The first tile in the Performer PRESETS panel, in its current sort and filters |
The setting has three kinds of choice:
- All channels (the default) — a Program Change on any MIDI channel switches presets
- Channel 1 to Channel 16 — only that channel switches presets; use this when another device on your setup also sends Program Change
- Off — Program Change is ignored
Program Change only works after the app has connected to MIDI. Open the app's MIDI settings once after loading the page, or start MIDI Learn. Your choice is saved in your browser.
Akai APC Mini MK2
The APC Mini MK2 gets deeper integration in both apps and is detected automatically when connected:
- OSC-1: the Settings → MIDI panel shows APC Mini connection status and a Test LEDs button that plays the startup LED animation to verify the connection.
- Audio Visualizers: Performer Settings → MIDI includes an APC Mini MK2 section with an LED Display Mode selector —
spectrum,stereo-vu,spectrum-vu, orpreset-grid— controlling what the 8×8 pad LEDs show.
Troubleshooting MIDI
Device not detected:
- Connect device before opening the browser
- Try refreshing the page with the device already connected
- Unplug and replug the USB cable, then refresh
MIDI Learn not responding:
- Ensure MIDI permission was granted (lock icon in address bar → Site Settings)
- Make sure the correct MIDI device is selected in the app's MIDI settings