0
# WebMidi.js
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: webmidi
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install webmidi`
10
- **Optional Node.js dependency**: `npm install jzz` (for Node.js MIDI support)
11

12
## Core Imports
13

14
```javascript
15
import { WebMidi, Input, Output, Note } from "webmidi";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { WebMidi, Input, Output, Note } = require("webmidi");
22
```
23

24
All available exports:
25

26
```javascript
27
import { 
28
  WebMidi, 
29
  Enumerations, 
30
  Forwarder, 
31
  Input, 
32
  InputChannel, 
33
  Message, 
34
  Note, 
35
  Output, 
36
  OutputChannel, 
37
  Utilities 
38
} from "webmidi";
39
```
40

41
## Basic Usage
42

43
```javascript
44
import { WebMidi } from "webmidi";
45

46
// Enable WebMidi.js (required before using any functionality)
47
WebMidi.enable()
48
  .then(() => {
49
    console.log("WebMidi enabled!");
50
    
51
    // List available devices
52
    console.log("Inputs:", WebMidi.inputs);
53
    console.log("Outputs:", WebMidi.outputs);
54
    
55
    // Get first available output and play a note
56
    const output = WebMidi.outputs[0];
57
    if (output) {
58
      output.playNote("C4", 1, { duration: 1000 });
59
    }
60
    
61
    // Listen for input messages
62
    const input = WebMidi.inputs[0];
63
    if (input) {
64
      input.addListener("noteon", (e) => {
65
        console.log("Note played:", e.note.name + e.note.octave);
66
      });
67
    }
68
  })
69
  .catch(err => console.log("WebMidi could not be enabled:", err));
70
```
71

72
## Architecture
73

74
WebMidi.js is built around several key components:
75

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

84
## Capabilities
85

86
### WebMidi Main Interface
87

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

90
```javascript { .api }
91
class WebMidi {
92
  static enable(options?: {sysex?: boolean}, legacy?: boolean): Promise<WebMidi>;
93
  static get enabled(): boolean;
94
  static get supported(): boolean;
95
  static get inputs(): Input[];
96
  static get outputs(): Output[];
97
  static getInputById(id: string, options?: {disconnected?: boolean}): Input | false;
98
  static getInputByName(name: string, options?: {disconnected?: boolean}): Input | false;
99
  static getOutputById(id: string, options?: {disconnected?: boolean}): Output | false;
100
  static getOutputByName(name: string, options?: {disconnected?: boolean}): Output | false;
101
}
102
```
103

104
[WebMidi Interface](./webmidi-interface.md)
105

106
### MIDI Input Handling
107

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

110
```javascript { .api }
111
class Input extends EventEmitter {
112
  readonly channels: InputChannel[];
113
  readonly name: string;
114
  readonly id: string;
115
  readonly connection: string;
116
  readonly state: string;
117
  
118
  addListener(event: string, listener: Function, options?: object): Input;
119
  removeListener(event: string, listener: Function, options?: object): Input;
120
  addForwarder(output: Output, options?: object): void;
121
}
122

123
class InputChannel extends EventEmitter {
124
  readonly number: number;
125
  readonly input: Input;
126
  
127
  getNoteState(note: string | number): object;
128
}
129
```
130

131
[MIDI Input](./midi-input.md)
132

133
### MIDI Output Control
134

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

137
```javascript { .api }
138
class Output extends EventEmitter {
139
  readonly channels: OutputChannel[];
140
  readonly name: string;
141
  readonly id: string;
142
  readonly connection: string;
143
  readonly state: string;
144
  
145
  send(message: number[] | Uint8Array, options?: {time?: number}): Output;
146
  sendSysex(identification: number[], data?: number[], options?: object): Output;
147
  clear(): Output;
148
}
149

150
class OutputChannel extends EventEmitter {
151
  readonly number: number;
152
  readonly output: Output;
153
  
154
  playNote(note: string | number | Note[], options?: object): OutputChannel;
155
  stopNote(note: string | number | Note[], options?: object): OutputChannel;
156
  sendControlChange(controller: number | string, value: number, options?: object): OutputChannel;
157
  sendPitchBend(value: number, options?: object): OutputChannel;
158
  sendProgramChange(program: number, options?: object): OutputChannel;
159
}
160
```
161

162
[MIDI Output](./midi-output.md)
163

164
### Note Handling
165

166
Musical note representation and conversion utilities for MIDI note processing.
167

168
```javascript { .api }
169
class Note {
170
  constructor(value: string | number | Note, options?: object);
171
  
172
  readonly identifier: string;
173
  readonly name: string;
174
  readonly accidental?: string;
175
  readonly octave: number;
176
  readonly number: number;
177
  readonly duration?: number;
178
  readonly attack: number;
179
  readonly release: number;
180
  
181
  getOffsetNumber(octaveOffset?: number, semitoneOffset?: number): number;
182
}
183
```
184

185
[Note Processing](./note-processing.md)
186

187
### Message Parsing
188

189
MIDI message representation and parsing for understanding received MIDI data.
190

191
```javascript { .api }
192
class Message {
193
  constructor(data: Uint8Array);
194
  
195
  readonly rawData: Uint8Array;
196
  readonly data: number[];
197
  readonly statusByte: number;
198
  readonly dataBytes: number[];
199
  readonly isChannelMessage: boolean;
200
  readonly isSystemMessage: boolean;
201
  readonly command: number;
202
  readonly channel?: number;
203
  readonly type: string;
204
}
205
```
206

207
[Message Processing](./message-processing.md)
208

209
### Utility Functions
210

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

213
```javascript { .api }
214
class Utilities {
215
  static toNoteNumber(identifier: string, octaveOffset?: number): number;
216
  static toNoteIdentifier(number: number, octaveOffset?: number): string;
217
  static from7bitToFloat(value: number): number;
218
  static fromFloatTo7Bit(value: number): number;
219
  static fromMsbLsbToFloat(msb: number, lsb?: number): number;
220
  static fromFloatToMsbLsb(value: number): {msb: number, lsb: number};
221
  static sanitizeChannels(channel: number | string | number[]): number[];
222
  static toTimestamp(time?: number | string): number;
223
}
224
```
225

226
[Utilities](./utilities.md)
227

228
### Constants and Enumerations
229

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

232
```javascript { .api }
233
class Enumerations {
234
  static readonly CHANNEL_MESSAGES: object;
235
  static readonly CHANNEL_MODE_MESSAGES: object;
236
  static readonly CONTROL_CHANGE_MESSAGES: object;
237
  static readonly REGISTERED_PARAMETERS: object;
238
  static readonly SYSTEM_MESSAGES: object;
239
  static readonly CHANNEL_EVENTS: string[];
240
}
241
```
242

243
[Constants](./constants.md)
244

245
### Message Forwarding
246

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

249
```javascript { .api }
250
class Forwarder {
251
  constructor(destinations?: Output[], options?: object);
252
  
253
  readonly destinations: Output[];
254
  
255
  forward(message: Message): void;
256
}
257
```
258

259
[Message Forwarding](./message-forwarding.md)
260

261
## Common Use Cases
262

263
WebMidi.js is ideal for:
264

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

272
## Browser and Node.js Support
273

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