or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

constants.mdindex.mdmessage-forwarding.mdmessage-processing.mdmidi-input.mdmidi-output.mdnote-processing.mdutilities.mdwebmidi-interface.md
tile.json

tessl/npm-webmidi

JavaScript library for MIDI communication that simplifies sending and receiving MIDI messages between browsers/Node.js and MIDI instruments

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/webmidi@3.1.x

To install, run

npx @tessl/cli install tessl/npm-webmidi@3.1.0

index.mddocs/

WebMidi.js

WebMidi.js is a comprehensive JavaScript library that simplifies working with the Web MIDI API. It provides an easy-to-use interface for sending and receiving MIDI messages between browsers/Node.js and MIDI instruments, with support for both virtual and hardware devices.

Package Information

  • Package Name: webmidi
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install webmidi
  • Optional Node.js dependency: npm install jzz (for Node.js MIDI support)

Core Imports

import { WebMidi, Input, Output, Note } from "webmidi";

For CommonJS:

const { WebMidi, Input, Output, Note } = require("webmidi");

All available exports:

import { 
  WebMidi, 
  Enumerations, 
  Forwarder, 
  Input, 
  InputChannel, 
  Message, 
  Note, 
  Output, 
  OutputChannel, 
  Utilities 
} from "webmidi";

Basic Usage

import { WebMidi } from "webmidi";

// Enable WebMidi.js (required before using any functionality)
WebMidi.enable()
  .then(() => {
    console.log("WebMidi enabled!");
    
    // List available devices
    console.log("Inputs:", WebMidi.inputs);
    console.log("Outputs:", WebMidi.outputs);
    
    // Get first available output and play a note
    const output = WebMidi.outputs[0];
    if (output) {
      output.playNote("C4", 1, { duration: 1000 });
    }
    
    // Listen for input messages
    const input = WebMidi.inputs[0];
    if (input) {
      input.addListener("noteon", (e) => {
        console.log("Note played:", e.note.name + e.note.octave);
      });
    }
  })
  .catch(err => console.log("WebMidi could not be enabled:", err));

Architecture

WebMidi.js is built around several key components:

  • WebMidi Singleton: Main interface for enabling MIDI access and managing ports
  • Input/Output Ports: Represent physical or virtual MIDI devices for receiving/sending messages
  • Input/Output Channels: Channel-specific interfaces (1-16) for targeted MIDI communication
  • Message Objects: Parsed MIDI message representations with type-specific properties
  • Note Objects: Musical note representations with conversion utilities
  • Event System: Event-driven architecture for real-time MIDI message handling
  • Utilities: Static helper functions for MIDI data conversion and note processing

Capabilities

WebMidi Main Interface

Central singleton for MIDI access control, device management, and global utilities.

class WebMidi {
  static enable(options?: {sysex?: boolean}, legacy?: boolean): Promise<WebMidi>;
  static get enabled(): boolean;
  static get supported(): boolean;
  static get inputs(): Input[];
  static get outputs(): Output[];
  static getInputById(id: string, options?: {disconnected?: boolean}): Input | false;
  static getInputByName(name: string, options?: {disconnected?: boolean}): Input | false;
  static getOutputById(id: string, options?: {disconnected?: boolean}): Output | false;
  static getOutputByName(name: string, options?: {disconnected?: boolean}): Output | false;
}

WebMidi Interface

MIDI Input Handling

Comprehensive input handling for receiving and processing MIDI messages from devices.

class Input extends EventEmitter {
  readonly channels: InputChannel[];
  readonly name: string;
  readonly id: string;
  readonly connection: string;
  readonly state: string;
  
  addListener(event: string, listener: Function, options?: object): Input;
  removeListener(event: string, listener: Function, options?: object): Input;
  addForwarder(output: Output, options?: object): void;
}

class InputChannel extends EventEmitter {
  readonly number: number;
  readonly input: Input;
  
  getNoteState(note: string | number): object;
}

MIDI Input

MIDI Output Control

Complete output functionality for sending MIDI messages to instruments and devices.

class Output extends EventEmitter {
  readonly channels: OutputChannel[];
  readonly name: string;
  readonly id: string;
  readonly connection: string;
  readonly state: string;
  
  send(message: number[] | Uint8Array, options?: {time?: number}): Output;
  sendSysex(identification: number[], data?: number[], options?: object): Output;
  clear(): Output;
}

class OutputChannel extends EventEmitter {
  readonly number: number;
  readonly output: Output;
  
  playNote(note: string | number | Note[], options?: object): OutputChannel;
  stopNote(note: string | number | Note[], options?: object): OutputChannel;
  sendControlChange(controller: number | string, value: number, options?: object): OutputChannel;
  sendPitchBend(value: number, options?: object): OutputChannel;
  sendProgramChange(program: number, options?: object): OutputChannel;
}

MIDI Output

Note Handling

Musical note representation and conversion utilities for MIDI note processing.

class Note {
  constructor(value: string | number | Note, options?: object);
  
  readonly identifier: string;
  readonly name: string;
  readonly accidental?: string;
  readonly octave: number;
  readonly number: number;
  readonly duration?: number;
  readonly attack: number;
  readonly release: number;
  
  getOffsetNumber(octaveOffset?: number, semitoneOffset?: number): number;
}

Note Processing

Message Parsing

MIDI message representation and parsing for understanding received MIDI data.

class Message {
  constructor(data: Uint8Array);
  
  readonly rawData: Uint8Array;
  readonly data: number[];
  readonly statusByte: number;
  readonly dataBytes: number[];
  readonly isChannelMessage: boolean;
  readonly isSystemMessage: boolean;
  readonly command: number;
  readonly channel?: number;
  readonly type: string;
}

Message Processing

Utility Functions

Static utility methods for MIDI data conversion, note processing, and value transformations.

class Utilities {
  static toNoteNumber(identifier: string, octaveOffset?: number): number;
  static toNoteIdentifier(number: number, octaveOffset?: number): string;
  static from7bitToFloat(value: number): number;
  static fromFloatTo7Bit(value: number): number;
  static fromMsbLsbToFloat(msb: number, lsb?: number): number;
  static fromFloatToMsbLsb(value: number): {msb: number, lsb: number};
  static sanitizeChannels(channel: number | string | number[]): number[];
  static toTimestamp(time?: number | string): number;
}

Utilities

Constants and Enumerations

MIDI specification constants and enumerations for all message types and values.

class Enumerations {
  static readonly CHANNEL_MESSAGES: object;
  static readonly CHANNEL_MODE_MESSAGES: object;
  static readonly CONTROL_CHANGE_MESSAGES: object;
  static readonly REGISTERED_PARAMETERS: object;
  static readonly SYSTEM_MESSAGES: object;
  static readonly CHANNEL_EVENTS: string[];
}

Constants

Message Forwarding

Forward MIDI messages between inputs and outputs for routing and processing.

class Forwarder {
  constructor(destinations?: Output[], options?: object);
  
  readonly destinations: Output[];
  
  forward(message: Message): void;
}

Message Forwarding

Common Use Cases

WebMidi.js is ideal for:

  • Web-based music applications: Virtual instruments, DAWs, sequencers
  • MIDI controllers: Building custom control surfaces and interfaces
  • Music education tools: Interactive learning applications with MIDI feedback
  • Live performance software: Real-time MIDI processing and routing
  • Hardware integration: Connecting web apps to MIDI hardware
  • Cross-platform MIDI apps: Browser and Node.js MIDI communication

Browser and Node.js Support

  • Browser: Uses native Web MIDI API (Chrome, Edge, Opera)
  • Node.js: Requires optional jzz dependency for MIDI support
  • Cross-platform: Same API works in both environments
  • TypeScript: Full type definitions included