WEBMIDI.js

WEBMIDI.js provides a set of pre-instantiated core classes to manage MIDI interactions. Most developers will interact with these singleton instances rather than instantiating them manually.

Core Classes

• WebMidi: The main entry point for the library.
• Input: Represents a MIDI input device.
• InputChannel: Represents a specific MIDI input channel.
• Output: Represents a MIDI output device.
• OutputChannel: Represents a specific MIDI output channel.
• Message: Represents a MIDI message.

Manual Instantiation

Unlike the core classes, the following classes must be instantiated by the developer:

• Note: Used to store and represent a musical note.
• Forwarder: Used to forward messages from an Input to an Output automatically.

The examples/electron directory contains a collection of examples demonstrating how to integrate WEBMIDI.js into an Electron environment.

• Basic Electron Example: A foundational implementation for getting started with Electron and WEBMIDI.js.

* [**Basic Electron Example**](basic-example)

The Enumerations class provides static properties containing arrays and enumerations used throughout the library. Because these properties are static, you should access them directly using the class name without instantiating it.

Example: Enumerations.CHANNEL_MESSAGES.

There are two primary patterns for using WEBMIDI.js within p5.js:

1. Event-driven drawing: Trigger drawing actions (like drawing circles on a canvas) immediately when a note on MIDI event is received.
2. State-driven visualization: Query the current state of MIDI notes to draw representations of a keyboard, where colors change based on whether keys are currently pressed.

The InputChannel class represents a single MIDI input channel (1-16) from a single MIDI input device.

Key Concepts:

• Not for direct instantiation: You should not call new InputChannel() yourself. Instead, these objects are automatically created and provided by the host's MIDI subsystem.
• Accessing channels: To access the 16 InputChannel objects for a specific device, use the .channels property on the Input object.
• Event-driven: It extends EventEmitter, meaning you can listen for specific MIDI events (like noteon, noteoff, pitchbend, etc.) occurring on that specific channel.

By default, WEBMIDI.js follows the MIDI Tuning Standard and scientific pitch notation, treating middle C (261.626 Hz) as C4.

Because different MIDI manufacturers may assign middle C to different octaves (e.g., C3, C4, or C5), you can use the octaveOffset property to adjust how note names and octaves are reported. This allows you to align WEBMIDI.js's naming convention with your specific hardware without changing the underlying MIDI note numbers.

The Forwarder class is used to route MIDI messages to specific outputs. When you call the .forward(message) method, the class checks if the provided Message matches the configured .channels and .types. If it matches, the message is sent to all Output objects listed in the .destinations property.

While you can instantiate a Forwarder manually, it is most commonly obtained as the return value of the Input.addForwarder() method.

WEBMIDI.js is available in three distribution flavours to suit different environments:

• Immediately Invoked Function Expression (IIFE): Adds objects directly to the global namespace. This is a legacy approach often easier for beginners.
• ES6 Module (ESM): The modern approach for newer browsers and Node.js, allowing you to use import statements. This is the favoured approach going forward.
• CommonJS Module (CJS): The traditional approach for Node.js and bundling tools like WebPack.

All flavours are available in both full and minified versions with sourcemaps.

The Utilities class contains various static helper methods for MIDI-related data transformations and environment detection. Because all methods are static, you should call them directly on the class name without instantiating it.

Example: Utilities.someMethod().