0
# WebMidi Interface
1

2
The WebMidi singleton provides the main interface for enabling MIDI access and managing MIDI ports. It must be enabled before any MIDI functionality can be used.
3

4
## Capabilities
5

6
### Enable WebMidi
7

8
Enable MIDI access with optional SysEx support.
9

10
```javascript { .api }
11
/**
12
 * Enable WebMidi access to MIDI devices
13
 * @param options - Configuration options
14
 * @param options.sysex - Whether to enable SysEx support (default: false)
15
 * @returns Promise that resolves with WebMidi instance
16
 */
17
static enable(options?: {sysex?: boolean}): Promise<WebMidi>;
18

19
/**
20
 * Disable WebMidi and close all ports
21
 * @returns Promise that resolves when WebMidi is disabled
22
 */
23
static disable(): Promise<WebMidi>;
24
```
25

26
**Usage Examples:**
27

28
```javascript
29
import { WebMidi } from "webmidi";
30

31
// Basic enable
32
await WebMidi.enable();
33

34
// Enable with SysEx support
35
await WebMidi.enable({ sysex: true });
36

37
// Handle errors
38
try {
39
  await WebMidi.enable();
40
  console.log("MIDI enabled successfully");
41
} catch (error) {
42
  console.error("Failed to enable MIDI:", error);
43
}
44

45
// Disable WebMidi
46
await WebMidi.disable();
47
console.log("MIDI disabled");
48
```
49

50
### Device Discovery
51

52
Access available MIDI input and output devices.
53

54
```javascript { .api }
55
/**
56
 * Get all available MIDI input ports
57
 * @returns Array of Input objects
58
 */
59
static get inputs(): Input[];
60

61
/**
62
 * Get all available MIDI output ports  
63
 * @returns Array of Output objects
64
 */
65
static get outputs(): Output[];
66

67
/**
68
 * Get input by unique identifier
69
 * @param id - The port's unique identifier
70
 * @param options - Search options
71
 * @param options.disconnected - Include disconnected ports (default: false)
72
 * @returns Input object or false if not found
73
 */
74
static getInputById(id: string, options?: {disconnected?: boolean}): Input | false;
75

76
/**
77
 * Get input by name
78
 * @param name - The port name to search for
79
 * @param options - Search options
80
 * @param options.disconnected - Include disconnected ports (default: false)
81
 * @returns Input object or false if not found
82
 */
83
static getInputByName(name: string, options?: {disconnected?: boolean}): Input | false;
84

85
/**
86
 * Get output by unique identifier
87
 * @param id - The port's unique identifier  
88
 * @param options - Search options
89
 * @param options.disconnected - Include disconnected ports (default: false)
90
 * @returns Output object or false if not found
91
 */
92
static getOutputById(id: string, options?: {disconnected?: boolean}): Output | false;
93

94
/**
95
 * Get output by name
96
 * @param name - The port name to search for
97
 * @param options - Search options
98
 * @param options.disconnected - Include disconnected ports (default: false)
99
 * @returns Output object or false if not found
100
 */
101
static getOutputByName(name: string, options?: {disconnected?: boolean}): Output | false;
102
```
103

104
**Usage Examples:**
105

106
```javascript
107
// List all devices
108
console.log("Inputs:", WebMidi.inputs.map(input => input.name));
109
console.log("Outputs:", WebMidi.outputs.map(output => output.name));
110

111
// Find specific devices
112
const myKeyboard = WebMidi.getInputByName("My MIDI Keyboard");
113
const mySynth = WebMidi.getOutputByName("My Synthesizer");
114

115
// Find by ID (more reliable than name)
116
const input = WebMidi.getInputById("input-1234567890");
117
```
118

119
### Status Properties
120

121
Check WebMidi status and capabilities.
122

123
```javascript { .api }
124
/**
125
 * Whether WebMidi has been enabled
126
 * @returns True if WebMidi is enabled
127
 */
128
static get enabled(): boolean;
129

130
/**
131
 * Whether the Web MIDI API is supported in this environment
132
 * @returns True if Web MIDI API is available
133
 */
134
static get supported(): boolean;
135

136
/**
137
 * Whether SysEx messages are enabled
138
 * @returns True if SysEx is enabled
139
 */
140
static get sysexEnabled(): boolean;
141

142
/**
143
 * Whether running in Node.js environment
144
 * @returns True if in Node.js
145
 */
146
static get isNode(): boolean;
147

148
/**
149
 * Whether running in browser environment
150
 * @returns True if in browser
151
 */
152
static get isBrowser(): boolean;
153

154
/**
155
 * Library version
156
 * @returns Version string
157
 */
158
static get version(): string;
159

160
/**
161
 * Current high-resolution timestamp
162
 * @returns Timestamp in milliseconds
163
 */
164
static get time(): number;
165

166
/**
167
 * Whether validation is enabled (for development/debugging)
168
 * @returns True if validation is enabled
169
 */
170
static get validation(): boolean;
171
static set validation(enabled: boolean);
172

173
/**
174
 * Native Web MIDI API interface object
175
 * @returns MIDIAccess object or null if not enabled
176
 */
177
static get interface(): MIDIAccess | null;
178
```
179

180
### Global Settings
181

182
Configure global WebMidi behavior.
183

184
```javascript { .api }
185
/**
186
 * Global octave offset applied to all note operations
187
 * @returns Current octave offset (-10 to 10)
188
 */
189
static get octaveOffset(): number;
190
static set octaveOffset(offset: number);
191
```
192

193
**Usage Examples:**
194

195
```javascript
196
// Check capabilities before use
197
if (!WebMidi.supported) {
198
  console.error("Web MIDI API not supported");
199
  return;
200
}
201

202
// Wait for enable
203
if (!WebMidi.enabled) {
204
  await WebMidi.enable();
205
}
206

207
// Set global octave offset (affects all note operations)
208
WebMidi.octaveOffset = -1; // All notes will be 1 octave lower
209

210
// Get current time for scheduling
211
const currentTime = WebMidi.time;
212
```
213

214
### Global Defaults
215

216
Configure default values for MIDI operations.
217

218
```javascript { .api }
219
/**
220
 * Global default values for note and other operations
221
 * @returns Object with default settings
222
 */
223
static get defaults(): {
224
  note: {
225
    attack: number;
226
    release: number;
227
    duration: number;
228
  };
229
};
230
```
231

232
### Event Handling
233

234
WebMidi fires events for device connection changes and errors.
235

236
```javascript { .api }
237
// Available events: "connected", "disconnected", "enabled", "disabled", "error", "portschanged"
238
static addListener(event: string, listener: Function): WebMidi;
239
static removeListener(event: string, listener: Function): WebMidi;
240
```
241

242
**Usage Examples:**
243

244
```javascript
245
// Listen for device connection changes
246
WebMidi.addListener("connected", (e) => {
247
  console.log("Device connected:", e.port.name);
248
});
249

250
WebMidi.addListener("disconnected", (e) => {
251
  console.log("Device disconnected:", e.port.name);
252
});
253

254
// Listen for port changes
255
WebMidi.addListener("portschanged", () => {
256
  console.log("Available ports changed");
257
  updateDeviceList();
258
});
259

260
// Handle errors
261
WebMidi.addListener("error", (e) => {
262
  console.error("WebMidi error:", e.error);
263
});
264
```
265

266
## Types
267

268
```javascript { .api }
269
interface WebMidiEnableOptions {
270
  sysex?: boolean;
271
}
272

273
interface DeviceSearchOptions {
274
  disconnected?: boolean;
275
}
276
```