docs » hs.midi

A table containing the numeric value for the possible flags returned by the commandType parameter of the callback function.

A callback that's triggered when a physical or virtual MIDI device is added or removed from the system.

• callbackFn - the callback function to trigger.

• None

• 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)```
  

Returns a table of currently connected physical MIDI devices.

• None

• A table containing the names of any physically connected MIDI devices as strings.

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.

• None

• A table containing the names of any virtual MIDI sources as strings.

Creates a new hs.midi object.

• 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().

• An hs.midi object or nil if an error occurred.

• Example Usage: hs.midi.new(hs.midi.devices()[1])

Creates a new hs.midi object.

• 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().

• An hs.midi object or nil if an error occurred.

• Example Usage: hs.midi.new(hs.midi.virtualSources()[1])

Sets or removes a callback function for the hs.midi object.

• 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.

• The hs.midi object

• 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:

  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)```
  

Returns the display name of a hs.midi object.

• None

• The name as a string.

Sends an Identity Request message to the hs.midi device. You can use hs.midi:callback() to receive the systemExclusive response.

• None

• None

• 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()```

Returns the online status of a hs.midi object.

• None

• true if online, otherwise false

Returns true if an hs.midi object is virtual, otherwise false.

• None

• true if virtual, otherwise false

Returns the manufacturer name of a hs.midi object.

• None

• The manufacturer name as a string.

Returns the model name of a hs.midi object.

• None

• The model name as a string.

Returns the name of a hs.midi object.

• None

• The name as a string.

Sends a command to the hs.midi object.

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

• true if successful, otherwise false

• 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:

  midiDevice = hs.midi.new(hs.midi.devices()[1])
  midiDevice:sendCommand("noteOn", {
      ["note"] = 72,
      ["velocity"] = 50,
      ["channel"] = 0,
  })
  hs.timer.usleep(500000)
  midiDevice:sendCommand("noteOn", {
      ["note"] = 74,
      ["velocity"] = 50,
      ["channel"] = 0,
  })
  hs.timer.usleep(500000)
  midiDevice:sendCommand("noteOn", {
      ["note"] = 76,
      ["velocity"] = 50,
      ["channel"] = 0,
  })
  midiDevice:sendCommand("pitchWheelChange", {
      ["pitchChange"] = 1000,
      ["channel"] = 0,
  })
  hs.timer.usleep(100000)
  midiDevice:sendCommand("pitchWheelChange", {
      ["pitchChange"] = 2000,
      ["channel"] = 0,
  })
  hs.timer.usleep(100000)
  midiDevice:sendCommand("pitchWheelChange", {
      ["pitchChange"] = 3000,
      ["channel"] = 0,
  })```
  

Sends a System Exclusive Command to the hs.midi object.

• command - The system exclusive command you wish to send as a string. White spaces in the string will be ignored.

• None

• Example Usage:

  midiDevice:sendSysex("f07e7f06 01f7")```
  

Set or display whether or not the MIDI device should synthesize audio on your computer.

• [value] - true if you want to synthesize audio, otherwise false.

• true if enabled otherwise false