# hs.midi

MIDI Extension for Hammerspoon.

This extension supports listening, transmitting and synthesizing MIDI commands.

This extension was thrown together by Chris Hocking for CommandPost.

This extension uses MIKMIDI, an easy-to-use Objective-C MIDI library created by Andrew Madsen and developed by him and Chris Flesner of Mixed In Key.

MIKMIDI LICENSE: Copyright (c) 2013 Mixed In Key, LLC. Original author: Andrew R. Madsen (andrew@mixedinkey.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

# API Overview

Constants - Useful values which cannot be changed

  • commandTypes

Functions - API calls offered directly by the extension

  • deviceCallback
  • devices
  • virtualSources

Constructors - API calls which return an object, typically one that offers API methods

  • new
  • newVirtualSource

Methods - API calls which can only be made on an object returned by a constructor

  • callback
  • displayName
  • identityRequest
  • isOnline
  • isVirtual
  • manufacturer
  • model
  • name
  • sendCommand
  • sendSysex
  • synthesize

# API Documentation

# Constants

# commandTypes

Signature hs.midi.commandTypes[]
Type Constant
Description A table containing the numeric value for the possible flags returned by the commandType parameter of the callback function.
Notes None
Source extensions/midi/libmidi.m line 1511

# Functions

# deviceCallback

Signature hs.midi.deviceCallback(callbackFn) -> none
Type Function
Description A callback that's triggered when a physical or virtual MIDI device is added or removed from the system.
Parameters
  • callbackFn - the callback function to trigger.
Returns
  • None
Notes
  • The callback function should expect 2 argument and should not return anything:
  • devices - A table containing the names of any physically connected MIDI devices as strings.
  • virtualDevices - A table containing the names of any virtual MIDI devices as strings.
  • Example Usage:
  • lua</li><li> hs.midi.deviceCallback(function(devices, virtualDevices)</li><li> print(hs.inspect(devices))</li><li> print(hs.inspect(virtualDevices))</li><li> end)
Examples None
Source extensions/midi/libmidi.m line 341

# devices

Signature hs.midi.devices() -> table
Type Function
Description Returns a table of currently connected physical MIDI devices.
Parameters
  • None
Returns
  • A table containing the names of any physically connected MIDI devices as strings.
Notes None
Examples None
Source extensions/midi/libmidi.m line 299

# virtualSources

Signature hs.midi.virtualSources() -> table
Type Function
Description Returns a table of currently available Virtual MIDI sources. This includes devices, such as Native Instruments controllers which present as virtual endpoints rather than physical devices.
Parameters
  • None
Returns
  • A table containing the names of any virtual MIDI sources as strings.
Notes None
Examples None
Source extensions/midi/libmidi.m line 320

# Constructors

# new

Signature hs.midi.new(deviceName) -> hs.midi object
Type Constructor
Description Creates a new hs.midi object.
Parameters
  • deviceName - A string containing the device name of the MIDI device. A valid device name can be found by checking hs.midi.devices() and/or hs.midi.virtualSources().
Returns
  • An hs.midi object or nil if an error occurred.
Notes
  • Example Usage:
  • hs.midi.new(hs.midi.devices()[1])
Examples None
Source extensions/midi/libmidi.m line 390

# newVirtualSource

Signature hs.midi.newVirtualSource(virtualSource) -> hs.midi object
Type Constructor
Description Creates a new hs.midi object.
Parameters
  • virtualSource - A string containing the virtual source name of the MIDI device. A valid virtual source name can be found by checking hs.midi.virtualSources().
Returns
  • An hs.midi object or nil if an error occurred.
Notes
  • Example Usage:
  • hs.midi.newVirtualSource(hs.midi.virtualSources()[1])
Examples None
Source extensions/midi/libmidi.m line 417

# Methods

# callback

Signature hs.midi:callback(callbackFn)
Type Method
Description Sets or removes a callback function for the hs.midi object.
Parameters
  • callbackFn - a function to set as the callback for this hs.midi object. If the value provided is nil, any currently existing callback function is removed.
Returns
  • The hs.midi object
Notes
  • Most MIDI keyboards produce a noteOn when you press a key, then noteOff when you release. However, some MIDI keyboards will return a noteOn with 0 velocity instead of noteOff, so you will receive two noteOn commands for every key press/release.
  • The callback function should expect 5 arguments and should not return anything:
  • object - The hs.midi object.
  • deviceName - The device name as a string.
  • commandType - Type of MIDI message as defined as a string. See hs.midi.commandTypes[] for a list of possibilities.
  • description - Description of the event as a string. This is only really useful for debugging.
  • metadata - A table of data for the MIDI command (see below).
  • The metadata table will return the following, depending on the commandType for the callback:
  • noteOff - Note off command:
  • note - The note number for the command. Must be between 0 and 127.
  • velocity - The velocity for the command. Must be between 0 and 127.
  • channel - The channel for the command. Must be a number between 15.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • noteOn - Note on command:
  • note - The note number for the command. Must be between 0 and 127.
  • velocity - The velocity for the command. Must be between 0 and 127.
  • channel - The channel for the command. Must be a number between 15.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • polyphonicKeyPressure - Polyphonic key pressure command:
  • note - The note number for the command. Must be between 0 and 127.
  • pressure - Key pressure of the polyphonic key pressure message. In the range 0-127.
  • channel - The channel for the command. Must be a number between 15.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • controlChange - Control change command. This is the most common command sent by MIDI controllers:
  • controllerNumber - The MIDI control number for the command.
  • controllerValue - The controllerValue of the command. Only the lower 7-bits of this are used.
  • channel - The channel for the command. Must be a number between 15.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • fourteenBitValue - The 14-bit value of the command.
  • fourteenBitCommand - true if the command contains 14-bit value data otherwise, false.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • programChange - Program change command:
  • programNumber - The program (aka patch) number. From 0-127.
  • channel - The channel for the command. Must be a number between 15.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • channelPressure - Channel pressure command:
  • pressure - Key pressure of the channel pressure message. In the range 0-127.
  • channel - The channel for the command. Must be a number between 15.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • pitchWheelChange - Pitch wheel change command:
  • pitchChange - A 14-bit value indicating the pitch bend. Center is 0x2000 (8192). Valid range is from 0-16383.
  • channel - The channel for the command. Must be a number between 15.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • systemMessage - System message command:
  • dataByte1 - Data Byte 1 as integer.
  • dataByte2 - Data Byte 2 as integer.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • systemExclusive - System message command:
  • manufacturerID - The manufacturer ID for the command. This is used by devices to determine if the message is one they support.
  • sysexChannel - The channel of the message. Only valid for universal exclusive messages, will always be 0 for non-universal messages.
  • sysexData - The system exclusive data for the message. For universal messages subID's are included in sysexData, for non-universal messages, any device specific information (such as modelID, versionID or whatever manufactures decide to include) will be included in sysexData.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • systemTimecodeQuarterFrame - System exclusive (SysEx) command:
  • dataByte1 - Data Byte 1 as integer.
  • dataByte2 - Data Byte 2 as integer.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • systemSongPositionPointer - System song position pointer command:
  • dataByte1 - Data Byte 1 as integer.
  • dataByte2 - Data Byte 2 as integer.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • systemSongSelect - System song select command:
  • dataByte1 - Data Byte 1 as integer.
  • dataByte2 - Data Byte 2 as integer.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • systemTuneRequest - System tune request command:
  • dataByte1 - Data Byte 1 as integer.
  • dataByte2 - Data Byte 2 as integer.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • systemTimingClock - System timing clock command:
  • dataByte1 - Data Byte 1 as integer.
  • dataByte2 - Data Byte 2 as integer.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • systemStartSequence - System timing clock command:
  • dataByte1 - Data Byte 1 as integer.
  • dataByte2 - Data Byte 2 as integer.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • systemContinueSequence - System start sequence command:
  • dataByte1 - Data Byte 1 as integer.
  • dataByte2 - Data Byte 2 as integer.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • systemStopSequence - System continue sequence command:
  • dataByte1 - Data Byte 1 as integer.
  • dataByte2 - Data Byte 2 as integer.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • systemKeepAlive - System keep alive message:
  • dataByte1 - Data Byte 1 as integer.
  • dataByte2 - Data Byte 2 as integer.
  • timestamp - The timestamp for the command as a string.
  • data - Raw MIDI Data as Hex String.
  • isVirtual - true if Virtual MIDI Source otherwise false.
  • Example Usage:
  • lua</li><li> midiDevice = hs.midi.new(hs.midi.devices()[3])</li><li> midiDevice:callback(function(object, deviceName, commandType, description, metadata)</li><li> print("object: " .. tostring(object))</li><li> print("deviceName: " .. deviceName)</li><li> print("commandType: " .. commandType)</li><li> print("description: " .. description)</li><li> print("metadata: " .. hs.inspect(metadata))</li><li> end)
Examples None
Source extensions/midi/libmidi.m line 446

# displayName

Signature hs.midi:displayName() -> string
Type Method
Description Returns the display name of a hs.midi object.
Parameters
  • None
Returns
  • The name as a string.
Notes None
Examples None
Source extensions/midi/libmidi.m line 1421

# identityRequest

Signature hs.midi:identityRequest() -> none
Type Method
Description Sends an Identity Request message to the hs.midi device. You can use hs.midi:callback() to receive the systemExclusive response.
Parameters
  • None
Returns
  • None
Notes
  • Example Usage:
  • lua</li><li> midiDevice = hs.midi.new(hs.midi.devices()[3])</li><li> midiDevice:callback(function(object, deviceName, commandType, description, metadata)</li><li> print("object: " .. tostring(object))</li><li> print("deviceName: " .. deviceName)</li><li> print("commandType: " .. commandType)</li><li> print("description: " .. description)</li><li> print("metadata: " .. hs.inspect(metadata))</li><li> end)</li><li> midiDevice:identityRequest()
Examples None
Source extensions/midi/libmidi.m line 1341

# isOnline

Signature hs.midi:isOnline() -> boolean
Type Method
Description Returns the online status of a hs.midi object.
Parameters
  • None
Returns
  • true if online, otherwise false
Notes None
Examples None
Source extensions/midi/libmidi.m line 1475

# isVirtual

Signature hs.midi:isVirtual() -> boolean
Type Method
Description Returns true if an hs.midi object is virtual, otherwise false.
Parameters
  • None
Returns
  • true if virtual, otherwise false
Notes None
Examples None
Source extensions/midi/libmidi.m line 1492

# manufacturer

Signature hs.midi:manufacturer() -> string
Type Method
Description Returns the manufacturer name of a hs.midi object.
Parameters
  • None
Returns
  • The manufacturer name as a string.
Notes None
Examples None
Source extensions/midi/libmidi.m line 1457

# model

Signature hs.midi:model() -> string
Type Method
Description Returns the model name of a hs.midi object.
Parameters
  • None
Returns
  • The model name as a string.
Notes None
Examples None
Source extensions/midi/libmidi.m line 1439

# name

Signature hs.midi:name() -> string
Type Method
Description Returns the name of a hs.midi object.
Parameters
  • None
Returns
  • The name as a string.
Notes None
Examples None
Source extensions/midi/libmidi.m line 1403

# sendCommand

Signature hs.midi:sendCommand(commandType, metadata) -> boolean
Type Method
Description Sends a command to the hs.midi object.
Parameters
  • commandType - The type of command you want to send as a string. See hs.midi.commandTypes[].
  • metadata - A table of data for the MIDI command (see notes below).
Returns
  • true if successful, otherwise false
Notes
  • The metadata table can accept following, depending on the commandType supplied:
  • noteOff - Note off command:
  • note - The note number for the command. Must be between 0 and 127. Defaults to 0.
  • velocity - The velocity for the command. Must be between 0 and 127. Defaults to 0.
  • channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends the command to All Channels.
  • noteOn - Note on command:
  • note - The note number for the command. Must be between 0 and 127. Defaults to 0.
  • velocity - The velocity for the command. Must be between 0 and 127. Defaults to 0.
  • channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends the command to All Channels.
  • polyphonicKeyPressure - Polyphonic key pressure command:
  • note - The note number for the command. Must be between 0 and 127. Defaults to 0.
  • pressure - Key pressure of the polyphonic key pressure message. In the range 0-127. Defaults to 0.
  • channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends the command to All Channels.
  • controlChange - Control change command. This is the most common command sent by MIDI controllers:
  • controllerNumber - The MIDI control number for the command. Defaults to 0.
  • controllerValue - The controllerValue of the command. Only the lower 7-bits of this are used. Defaults to 0.
  • channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends the command to All Channels.
  • fourteenBitValue - The 14-bit value of the command. Must be between 0 and 16383. Defaults to 0. fourteenBitCommand must be true.
  • fourteenBitCommand - true if the command contains 14-bit value data otherwise, false. controllerValue will be ignored if this is set to true.
  • programChange - Program change command:
  • programNumber - The program (aka patch) number. From 0-127. Defaults to 0.
  • channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends the command to All Channels.
  • channelPressure - Channel pressure command:
  • pressure - Key pressure of the channel pressure message. In the range 0-127. Defaults to 0.
  • channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends the command to All Channels.
  • pitchWheelChange - Pitch wheel change command:
  • pitchChange - A 14-bit value indicating the pitch bend. Center is 0x2000 (8192). Valid range is from 0-16383. Defaults to 0.
  • channel - The channel for the command. Must be a number between 0 and 16. Defaults to 0, which sends the command to All Channels.
  • Example Usage:
  • lua</li><li> midiDevice = hs.midi.new(hs.midi.devices()[1])</li><li> midiDevice:sendCommand("noteOn", {</li><li> ["note"] = 72,</li><li> ["velocity"] = 50,</li><li> ["channel"] = 0,</li><li> })</li><li> hs.timer.usleep(500000)</li><li> midiDevice:sendCommand("noteOn", {</li><li> ["note"] = 74,</li><li> ["velocity"] = 50,</li><li> ["channel"] = 0,</li><li> })</li><li> hs.timer.usleep(500000)</li><li> midiDevice:sendCommand("noteOn", {</li><li> ["note"] = 76,</li><li> ["velocity"] = 50,</li><li> ["channel"] = 0,</li><li> })</li><li> midiDevice:sendCommand("pitchWheelChange", {</li><li> ["pitchChange"] = 1000,</li><li> ["channel"] = 0,</li><li> })</li><li> hs.timer.usleep(100000)</li><li> midiDevice:sendCommand("pitchWheelChange", {</li><li> ["pitchChange"] = 2000,</li><li> ["channel"] = 0,</li><li> })</li><li> hs.timer.usleep(100000)</li><li> midiDevice:sendCommand("pitchWheelChange", {</li><li> ["pitchChange"] = 3000,</li><li> ["channel"] = 0,</li><li> })
Examples None
Source extensions/midi/libmidi.m line 1031

# sendSysex

Signature hs.midi:sendSysex(command) -> none
Type Method
Description Sends a System Exclusive Command to the hs.midi object.
Parameters
  • command - The system exclusive command you wish to send as a string. White spaces in the string will be ignored.
Returns
  • None
Notes
  • Example Usage:
  • lua</li><li> midiDevice:sendSysex("f07e7f06 01f7")
Examples None
Source extensions/midi/libmidi.m line 1009

# synthesize

Signature hs.midi:synthesize([value]) -> boolean
Type Method
Description Set or display whether or not the MIDI device should synthesize audio on your computer.
Parameters
  • [value] - true if you want to synthesize audio, otherwise false.
Returns
  • true if enabled otherwise false
Notes None
Examples None
Source extensions/midi/libmidi.m line 1375

© Copyright 2024 LateNite Films Pty Ltd. All rights reserved.