useMidi

useMidi is a low-level custom React Hook to access the Web MIDI API. It provides access to incoming MIDIMessageEvents and helpers to request and observe the user's permission.

Installation

yarn add @mkaradeniz/use-midi

or

npm install @mkaradeniz/use-midi

Demo

• Demo
• Example

Usage

const [midiMessages, { isSupported, isRequested, isAllowed }, requestMidiAccess, midiAccess] = useMidi()

API

Input

| Type | Default | | --------- | ---------------------------------------------------------------------------------------------------- | | Options | { automaticallyRequestPermission: false, debug: false, suppressActiveSensing: true, sysex: false } |

MidiMessage

| Property | Type | Description | | ------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------- | | commandCode | number | Recieved command code. | | note | number | undefined | If recieved, the given note. | | timestamp | DOMHighResTimeStamp | High-resolution time of when the event was received. | | rawEvent | WebMidi.MIDIMessageEvent | The raw WebMidi.MIDIMessageEvent. | | velocity | number | undefined | If recieved, the given velocity. |

Options

| Option | Type | Description | Default | | -------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | automaticallyRequestPermission | boolean | If set to true, useMidi will automatically ask for the user's permission to access the MIDI devices, instead of waiting for the consumer to call requestAccess. | false | | callback | (midiMessage: MidiMessage) => void | If provided, the callback will be called on every received MidiMessage. | undefined | | messagesHistoryCount | number | midiMessages will always contain the last messagesHistoryCount elements. | 256 | | debug | boolean | If set to true, useMidi will log every event to the console. | false | | suppressActiveSensing | boolean | If set to true, useMidi will ignore the Active Sensing event. | true | | sysex | boolean | If set to true, useMidi use the sysex option when requesting MIDI access. | false |

Returns

| Index | Variable | Type | Description | Default | | ----- | --------------- | --------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | 0 | midiMessages | MidiMessage[] | An array of all MidiMessages, from oldest (index 0) to newest. | [] | | 1 | status | Status | Object with all statuses. | {isAllowed: false, isRequested: False, isSupported: false} | | 2 | requestAccess | () => void | Function to request the user's permission to access MIDI devices. | () => void | | 3 | midiAccess | MIDIAccess | The MIDIAccess interface. | undefined |

Status

| Status | Type | Description | Default | | ------------- | --------- | ------------------------------------------------------------------------------------------------- | ------- | | isAllowed | boolean | Whether the user gave permission to access MIDI devices. | false | | isRequested | boolean | Whether we requested the user to grant permission to access MIDI devices. | false | | isSupported | boolean | Whether the Web MIDI API is supported by the browser. | false |

Development

This project is written in TypeScript and setup as a monorepo managed by Yarn-Workspaces & Lerna.

⚠️ Only release through yarn release in root. Do not npm publish individual packages.