# Module `midi`

midi contains MIDI-related classes and functions.

Example of receiving MIDI input : sine-organ.lua.

Example of producing MIDI output : midi-chordify.lua.

The midi global is available to every protoplug script after including the main protoplug header :

    require "include/protoplug"

## Functions

midi.noteToFreq (note) | Convert a MIDI note number to frequency.

## Class midi.Buffer

midi.Buffer:eachEvent () | Iterate over each midi.Event in the buffer.
midi.Buffer:clear () | Remove all MIDI events from the buffer.
midi.Buffer:addEvent (event) | Add a MIDI event.

## Class midi.Event

midi.Event (other) | Constructor : copy another event.
midi.Event (time, dataSize[, data]) | Constructor : create a custom event.
midi.Event.noteOn (channel, note, vel[, pos=0]) | Constructor : note on.
midi.Event.noteOff (channel, note[, vel=0[, pos=0]]) | Constructor : note off.
midi.Event.pitchBend (channel, pitch[, pos=0]) | Constructor : pitch bend.
midi.Event.control (channel, number, value[, pos=0]) | Constructor : Control change.
midi.Event:getChannel () | Get channel.
midi.Event:setChannel (channel) | Set channel.
midi.Event:isNoteOn () | Is a note on event.
midi.Event:isNoteOff () | Is a note off event.
midi.Event:getNote () | Get note.
midi.Event:setNote (note) | Set note.
midi.Event:getVel () | Get velocity.
midi.Event:setVel (vel) | Set velocity.
midi.Event:isPitchBend () | Is a pitch bend event.
midi.Event:getPitchBendValue () | Get pitch bend value.
midi.Event:isControl () | Is a Control Change event.
midi.Event:getControlNumber () | Get control number.
midi.Event:getControlValue () | Get control value.
midi.Event.time | Sample position relatively to the start of the block.
midi.Event.dataSize | Size of the MIDI message in bytes
midi.Event.data | The raw MIDI message (`const uint8_t*` cdata)

## Functions

midi.noteToFreq (note)
  Convert a MIDI note number to frequency. Call this function to get a note's frequency.

  ### Parameters:

  - note the MIDI note (0-127)

  ### Returns:

  the frequency in samples^-1

## Class midi.Buffer

A buffer containing midi events, as received by plugin.processBlock

midi.Buffer:eachEvent ()
  Iterate over each midi.Event in the buffer.

  ### Usage:

      for ev in myBuffer:eachEvent() do print(ev:getNote()) end

midi.Buffer:clear ()
  Remove all MIDI events from the buffer.
midi.Buffer:addEvent (event)
  Add a MIDI event.

  ### Parameters:

  - event midi.Event

## Class midi.Event

A single midi event as returned by Buffer:eachEvent

midi.Event (other)
  Constructor : copy another event.

  ### Parameters:

  - other midi.Event
midi.Event (time, dataSize[, data])
  Constructor : create a custom event. Create an event from given bytes (or zeros if not supplied)

  ### Parameters:

  - time
  - dataSize
  - data

  ### Usage:

      myEv = midi.Event(0, 3, {0x90, 0x30, 0x7f}) -- note on

midi.Event.noteOn (channel, note, vel[, pos=0])
  Constructor : note on.

  ### Parameters:

  - channel (1-16)
  - note (0-127)
  - vel (1-127)
  - pos sample offset (default 0)

  ### Returns:

  midi.Event
midi.Event.noteOff (channel, note[, vel=0[, pos=0]])
  Constructor : note off.

  ### Parameters:

  - channel (1-16)
  - note (0-127)
  - vel (0-127) (default 0)
  - pos sample offset (default 0)

  ### Returns:

  midi.Event
midi.Event.pitchBend (channel, pitch[, pos=0])
  Constructor : pitch bend.

  ### Parameters:

  - channel (1-16)
  - pitch bend value (0-16383)
  - pos sample offset (default 0)

  ### Returns:

  midi.Event
midi.Event.control (channel, number, value[, pos=0])
  Constructor : Control change.

  ### Parameters:

  - channel (1-16)
  - number control number (0-247)
  - value control value (0-127)
  - pos sample offset (default 0)

  ### Returns:

  midi.Event
midi.Event:getChannel ()
  Get channel.

  ### Returns:

  the MIDI channel (1-16)
midi.Event:setChannel (channel)
  Set channel.

  ### Parameters:

  - channel the MIDI channel (1-16)
midi.Event:isNoteOn ()
  Is a note on event.

  ### Returns:

  boolean whether event is a note on.
midi.Event:isNoteOff ()
  Is a note off event.

  ### Returns:

  boolean whether event is a note off.
midi.Event:getNote ()
  Get note.

  ### Returns:

  the MIDI note number (0-127)
midi.Event:setNote (note)
  Set note.

  ### Parameters:

  - note the MIDI note number (0-127)
midi.Event:getVel ()
  Get velocity.

  ### Returns:

  the MIDI velocity (1-127)
midi.Event:setVel (vel)
  Set velocity.

  ### Parameters:

  - vel the MIDI velocity (1-127)
midi.Event:isPitchBend ()
  Is a pitch bend event.

  ### Returns:

  boolean whether event is a pitch bend on.
midi.Event:getPitchBendValue ()
  Get pitch bend value.

  ### Returns:

  pitch bend value (0-16383).
midi.Event:isControl ()
  Is a Control Change event.

  ### Returns:

  boolean whether event is a control change.
midi.Event:getControlNumber ()
  Get control number.

  ### Returns:

  control number (0-247).
midi.Event:getControlValue ()
  Get control value.

  ### Returns:

  control value (0-127).
midi.Event.time
  Sample position relatively to the start of the block. This value is often 0 because most hosts call plugin.processBlock at the beginning of beats and beat divisions. It is never higher than the current plugin.processBlock's `smax` and any events created by the script should respect this rule.
midi.Event.dataSize
  Size of the MIDI message in bytes
midi.Event.data
  The raw MIDI message (`const uint8_t*` cdata)

generated by LDoc 1.4.2