Skip to content
This repository has been archived by the owner on Jun 9, 2023. It is now read-only.

Latest commit

 

History

History
195 lines (163 loc) · 18.9 KB

hs.midi.md

File metadata and controls

195 lines (163 loc) · 18.9 KB
Raw

docs » 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 ([email protected])

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

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.

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: hs.midi.deviceCallback(function(devices, virtualDevices) print(hs.inspect(devices)) print(hs.inspect(virtualDevices)) end)

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.

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.

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 occured.
Notes
  • Example Usage: hs.midi.new(hs.midi.devices()[1])

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 occured.
Notes
  • Example Usage: hs.midi.new(hs.midi.virtualSources()[1])

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 recieve 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).

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.

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: midiDevice = hs.midi.new(hs.midi.devices()[3]) midiDevice:callback(function(object, deviceName, commandType, description, metadata) print("object: " .. tostring(object)) print("deviceName: " .. deviceName) print("commandType: " .. commandType) print("description: " .. description) print("metadata: " .. hs.inspect(metadata)) end) midiDevice:identityRequest()

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

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

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.

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.

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.

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:

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: midiDevice:sendSysex("f07e7f06 01f7")

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