hs.midi
ModuleA module for enumerating, watching, and communicating with MIDI devices. IMPORTANT NOTE: This module has not had very much real-world testing yet. Please report positive or negative feedback via GitHub Issues.
Types
This module provides the following types:
Properties
hs.midi.commandTypes
{[key: string]: number}
A table mapping each MIDI command type name to a stable numeric identifier.
Methods
hs.midi.devices() -> string[]
Returns the names of all currently connected (online) physical MIDI devices.
Declaration
hs.midi.devices() -> string[]Returns
string[]
An array of device name strings
Example
console.log(hs.midi.devices())hs.midi.virtualSources() -> string[]
Returns the names of all available virtual MIDI sources — endpoints published
by other apps/drivers (e.g. the IAC Driver, virtual instruments) rather than
belonging to a physical device.
Declaration
hs.midi.virtualSources() -> string[]Returns
string[]
An array of virtual source name strings
Example
console.log(hs.midi.virtualSources())hs.midi.deviceCallback(fn) -> None
Sets or removes a callback fired whenever the set of connected MIDI devices
or virtual sources changes.
The callback receives two arguments: the current result of `devices()` and the
current result of `virtualSources()`.
Declaration
hs.midi.deviceCallback(fn) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| fn | JSValue | The function to call on any MIDI setup change, or `null` to remove it |
Returns
None
Example
hs.midi.deviceCallback((devices, virtualSources) => {
console.log("MIDI devices changed: " + devices.join(", "))
})hs.midi.deviceNamed(deviceName) -> HSMIDIDevice
Creates an `hs.midi` object for a physical device.
`new`/`alloc`/`copy`-prefixed method names, which have special meaning under
Objective-C's ARC ownership conventions.
Declaration
hs.midi.deviceNamed(deviceName) -> HSMIDIDeviceParameters
| Name | Type | Description |
|---|---|---|
| deviceName | string | The name of the device, as returned by `devices()` |
Returns
HSMIDIDevice
An `HSMIDIDevice` object, or `nil` if no device has that name
Example
const kb = hs.midi.deviceNamed(hs.midi.devices()[0])hs.midi.virtualSourceNamed(virtualSourceName) -> HSMIDIDevice
Creates an `hs.midi` object for an existing virtual source (receive-only —
a "source" endpoint can only be read from).
the same ARC-related reason as `deviceNamed()`.
Declaration
hs.midi.virtualSourceNamed(virtualSourceName) -> HSMIDIDeviceParameters
| Name | Type | Description |
|---|---|---|
| virtualSourceName | string | The name of the virtual source, as returned by `virtualSources()` |
Returns
HSMIDIDevice
An `HSMIDIDevice` object, or `nil` if no virtual source has that name
Example
const iac = hs.midi.virtualSourceNamed(hs.midi.virtualSources()[0])