midiwire   !npm version 

A modern, declarative JavaScript library for creating browser-based MIDI controllers. Build synth patch editors, hardware controllers, and MIDI utilities with simple HTML data attributes or a powerful programmatic API.

> WARNING: This library is pre-1.0 and the API may change at any time without notice.

Features

- 🎛️ Declarative HTML binding - Use data-midi-cc attributes for instant MIDI control
- 🎹 Full Web MIDI API - Native browser MIDI support (Chrome, Firefox, Opera)
- 🔌 Bidirectional MIDI - Send and receive MIDI messages
- 🎼 SysEx support - Send/receive System Exclusive messages for device control
- 🎛️ 14-bit CC support - High-resolution MIDI (0-16383) with automatic MSB/LSB handling
- ⏱️ Debouncing - Prevent MIDI device overload with configurable debouncing
- 🔌 Hotplug support - Detect and handle device connections/disconnections
- 💾 Patch management - Save/load patches with automatic element sync and versioning
- 🎹 DX7 support - Load and create Yamaha DX7 voice (patch) banks (.syx files)
- 📦 Zero dependencies - Lightweight and fast
- 🔧 Flexible API - Works with data attributes or programmatically
- 🎨 Framework agnostic - Use with vanilla JS, React, Vue, or anything else
- 📝 Fully documented - Comprehensive API documentation with examples

Installation

``bash
npm install midiwire
`

Or use directly in the browser from a CDN like jsDelivr:

`html





`

Quick Start

midiwire provides three API levels to match your needs. Choose the one that fits your project:

$3

For complete web UI integration with automatic device selectors and status management.

`javascript
import { MIDIDeviceManager } from "midiwire";

const manager = new MIDIDeviceManager({
onStatusUpdate: (msg, state) => console.log(msg),
onConnectionUpdate: (output, input) => console.log("Connected!"),
});

// Setup all selectors at once (returns MIDIController)
const midi = await manager.setupSelectors(
{
output: "#output-select",
input: "#input-select",
channel: "#channel-select"
},
{
onConnect: ({ device, type }) => console.log(${type}: ${device.name})
}
);

// Use the MIDI controller directly
midi.channel.sendCC(1, 100);
`

Best for: Complete web applications with device selection UI

$3

The main programmatic API for device management, MIDI messaging, and patch handling.

`javascript
import { MIDIController, CONTROLLER_EVENTS } from "midiwire";

const midi = new MIDIController({ outputChannel: 1 });
await midi.init();

// Send MIDI messages
midi.channel.sendCC(74, 64);
midi.channel.sendNoteOn(60, 100);

// Device management
await midi.device.connect("My Synth");
const devices = midi.device.getOutputs();

// Patch management
midi.patch.save("My Settings");
`

Best for: Programmatic MIDI control, synth editors, and controllers

$3

Direct Web MIDI API wrapper for raw MIDI access and custom implementations.

`javascript
import { MIDIConnection } from "midiwire";

const connection = new MIDIConnection({ sysex: true });
await connection.requestAccess();
await connection.connect("My Device");

// Send raw MIDI
connection.send([0x90, 60, 100]); // Note on
connection.sendSysEx([0x41, 0x10, 0x42]); // SysEx
`

Best for: Custom MIDI implementations and direct protocol control

$3

For complete API documentation with examples, see API Documentation.

Use Cases

- 🎹 Synth patch editors - Control hardware synths from your browser
- 🎚️ MIDI controllers - Build custom web-based MIDI controllers
- 📊 Parameter automation - Record and playback MIDI CC changes
- 🔧 Device configuration - Use SysEx to configure MIDI hardware
- 🎵 Educational tools - Teach MIDI concepts with interactive demos
- 🎛️ DAW integration - Control DAW parameters from web interfaces

Examples

Check out the examples/ folder for working demos:
- template.html - Quick-start template for rapid prototyping (start here!)
- basic.html - Simple CC control with data attributes
- advanced.html - All features showcase (ranges, inversion, 14-bit, debouncing)
- programmatic.html - Manual binding and custom SVG/canvas controls
- patches.html - Complete patch management system with localStorage
- sysex.html - SysEx communication and device inquiry
- dx7.html - Load and create Yamaha DX7 voice banks

Development

`bash


Install dependencies

npm install

Start dev server with examples

npm run dev

Build for production

npm run build

Run tests

npm test

Generate API docs

npm run docs

Lint

npm run lint
``

Browser Support

Requires browsers with Web MIDI API support:
- ✅ Chrome/Edge 43+
- ✅ Firefox 108+
- ✅ Opera 30+
- ❌ Safari (not supported)

Note: SysEx requires explicit user permission in Chrome.

License

MIT

Credits

- Inspired by synthmata/ccynthmata.
- DX7 implementation based on the work of asb2m10/dexed