humidi

Simple and lightweight MIDI library for humans. Zero dependencies, less than 5kB gzipped.

Provides a simple event-driven interface for working with MIDI input devices, including automatic device management, note tracking for stuck note prevention, and per-device enable/disable functionality.

🎹 Live Demo

Try HuMIDI with your MIDI keyboard: https://d-buckner.github.io/humidi/

📖 Documentation

Full API documentation is available at: https://d-buckner.github.io/humidi/docs/

Installation

npm install humidi

Basic Usage

import HuMIDI, {
  type NoteOnEvent,
  type NoteOffEvent,
  type PitchBendEvent,
} from 'humidi';

// Request MIDI access
await HuMIDI.requestAccess();

// Listen for note events
HuMIDI.on('noteon', (event: NoteOnEvent) => {
  console.log(`Note ${event.note} pressed with velocity ${event.velocity}`);
});

HuMIDI.on('noteoff', (event: NoteOffEvent) => {
  console.log(`Note ${event.note} released`);
});

// Listen for note presses only on channel 1
HuMIDI.on('noteon', console.log, 0);

// Unsubscribe to all listeners on channel 1
HuMIDI.unsubscribeToChannel(0);

// Listen for pitch bends
HuMIDI.on('pitchbend', (event: PitchBendEvent) => {
  console.log(`${(event.value * 100)}% pitch bend`);
});

Device Management

// Check permissions without requesting access
const hasPermissions = await HuMIDI.hasPermissions();

// Get all available input devices
const inputs = HuMIDI.getInputs();

// Disable a specific device
const piano = inputs.find(input => input.name.includes('Piano'));
piano?.disable();

// Listen for device connections
HuMIDI.on('inputconnected', (event) => {
  console.log(`Device connected: ${event.input.name}`);
});

HuMIDI.on('inputdisconnected', (event) => {
  console.log(`Device disconnected: ${event.input.name}`);
});

API Reference

Core Methods

• HuMIDI.requestAccess() - Request MIDI access from browser
• HuMIDI.hasPermissions() - Check if MIDI permissions are granted
• HuMIDI.getAccessStatus() - Get current access status
• HuMIDI.getInputs() - Get all available MIDI input devices
• HuMIDI.setEnabled(enabled) - Enable/disable all MIDI processing
• HuMIDI.isEnabled() - Check if MIDI processing is enabled

Event System

• HuMIDI.on(event, handler, channel?) - Register event handler
• HuMIDI.off(event, handler, channel?) - Remove event handler
• HuMIDI.unsubscribeToChannel(channel) - Remove all handlers for channel

Events

• 'noteon' - MIDI note pressed (NoteOnEvent)
• 'noteoff' - MIDI note released (NoteOffEvent)
• 'pitchbend' - Pitch bend wheel moved (PitchBendEvent)
• 'sustainon'/'sustainoff' - Sustain pedal (SustainEvent)
• 'inputconnected'/'inputdisconnected' - Device connections (InputEvent)

Device Objects

Each MIDIInput device has:

• Properties: id, name, manufacturer, state
• Methods: enable(), disable(), isEnabled()

Features

• Per-device note tracking - Prevents stuck notes when devices disconnect
• Channel support - Listen to specific channels or all channels
• Hot-plug support - Automatic handling of device connections
• Zero dependencies - Lightweight and self-contained
• TypeScript support - Full type definitions included

Links

• 🎹 Live Demo - Interactive MIDI demo
• 📖 Full API Documentation - Complete TypeScript API reference
• 🐛 Issues - Bug reports and feature requests

License

MIT License - see LICENSE file for details.