use-midi

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`
timestamp	DOMHighResTimeStamp	High-resolution time of when the event was received.
rawEvent	WebMidi.MIDIMessageEvent	The raw WebMidi.MIDIMessageEvent.
velocity	`number	undefined`

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.