@oliego/Wavr-midi-controller

A MIDI controller plugin for WAVR PRO. Connect any hardware MIDI device and route notes, CC, and transport messages to the DAW. Works standalone in any browser or as a registered plugin.

Browser support: Web MIDI API requires Chrome or Edge. Firefox and Safari do not support it natively. A user HTTPS context is required.

SPONSOR: → Oliego.Space - Create without limits!

Install

npm install @oliego/wavr-midi-controller

Zero dependencies. Web MIDI API only.

Quickstart

Standalone

import MidiController from '@oliego/wavr-midi-controller';

const mc = new MidiController({
  onNote: ({ note, velocity, channel, type }) => {
    console.log(`${type}: note ${note}, vel ${velocity}, ch ${channel}`);
  },
  onCC: ({ cc, value, channel }) => {
    console.log(`CC ${cc} = ${value} on ch ${channel}`);
  },
  onTransport: ({ command }) => {
    // command: "start" | "stop" | "continue"
    console.log(`Transport: ${command}`);
  },
});

mc.mount(document.getElementById('midi-panel'));

As a WAVR PRO plugin

import MidiController from '@oliego/wavr-midi-controller';

// Inside WavrPro — register once
pluginManager.register(MidiController);

// Opens as a drawer from the topbar.
// CC 1 (mod wheel) → BPM by default.
// CC 7 → master volume.
// CC 64 (sustain) → transport toggle.

React

import { useEffect, useRef } from 'react';
import MidiController from '@oliego/wavr-midi-controller';

export default function MidiPanel() {
  const ref = useRef(null);

  useEffect(() => {
    const mc = new MidiController({
      onNote: (e) => console.log(e),
    });
    mc.mount(ref.current);
    return () => mc.destroy();
  }, []);

  return <div ref={ref} />;
}

What it does

| Feature | Detail | | --------------- | ------------------------------------------------------------ | | Device picker | Dropdown lists all connected Web MIDI inputs | | Auto-connect | First device connects automatically; reconnects on plug-in | | Channel filter | Listen to all channels or a specific one | | Note display | Piano keyboard (2 octaves) lights up on incoming notes | | CC bars | Live bar graph for 6 common CC numbers | | CC mappings | Map any CC to BPM, master volume, or transport toggle | | Custom mappings | Add/remove CC→target pairs in the UI or via setState() | | Transport | MIDI clock Start/Stop/Continue fires onTransport | | MIDI log | Scrolling live log of every incoming message with timestamps |

API

Constructor

new MidiController({
  onNote,       // ({ note, velocity, channel, type }) => void
  onCC,         // ({ cc, value, channel }) => void
  onTransport,  // ({ command }) => void  — "start" | "stop" | "continue"
  onConnect,    // (MIDIPort) => void
  onDisconnect, // (MIDIPort) => void
})

All options are optional. In plugin-framework mode, pass the hostAPI object instead.

Methods

mc.mount(el)        // Render UI into el, request MIDI access
mc.destroy()        // Detach MIDI listeners, remove UI
mc.getState()       // Returns serialisable state (selected device, CC map, channel)
mc.setState(state)  // Restore from getState() snapshot
mc.onBpmChange(bpm) // Called by host when BPM changes

State format

{
  selectedInputId: "port-id-string",  // Web MIDI input port id
  channel: 0,                          // 0 = all channels, 1–16 = specific
  ccMap: {
    1:  "bpm",              // mod wheel → BPM
    7:  "master_volume",    // channel volume → master vol
    64: "transport_toggle", // sustain → play/pause
  },
  noteThrough: true,    // forward note events to onNote callback
  logSize: 60,          // max log entries kept
}

Default CC mappings

| CC | Default target | Notes | | --- | ------------------ | -------------------------------------------------- | | 1 | bpm | Mod wheel. Maps 0–127 → BPM 60–180. | | 7 | master_volume | Channel volume. Maps 0–127 → 0–100%. | | 64 | transport_toggle | Sustain pedal (127 = pressed). Toggles play/pause. |

Custom targets can be any string. Handle them in your onCC callback.

Browser support

| Browser | Web MIDI API | | ---------- | ------------------------------------------- | | Chrome 43+ | ✅ Supported | | Edge 79+ | ✅ Supported | | Firefox | ❌ Not supported (no native implementation) | | Safari | ❌ Not supported |

In unsupported browsers the plugin renders with a warning message and all callbacks receive no events.

HTTPS is required — navigator.requestMIDIAccess is blocked on http://.

Licence

MIT