Package com.bitwig.extension.controller.api

Interface MidiIn

public interface MidiIn
Instances of this interface are used to setup handler functions for incoming MIDI messages from a specific MIDI hardware.

Expressions can be used to generate matchers for various MIDI events that can then be used to update hardware control states (see createActionMatcher(String) and HardwareControl).

The expression language supports these operators in the same way that C, Java, C++ do: +, -, *, /, %, <<, >>, &&, ||, &, |, ^, <, <=, >, >=, ==, !=

The following variables are also defined for matching parts of the event:
  • status - Value of the status byte
  • data1 - Value of the first data byte
  • data2 - Value of the second data byte
  • event - Integer value of the whole MIDI event with data2 byte in the least significant bits

Integers can be represented in hex using same syntax as C. 'true' and 'false' keywords are also defined.

Since:
API version 1

  • Method Details

    • setMidiCallback

      void setMidiCallback(ShortMidiDataReceivedCallback callback)
      Registers a callback for receiving short (normal) MIDI messages on this MIDI input port.
      Parameters:
      callback - a callback function that receives three integer parameters: 1. the status byte 2. the data1 value 2. the data2 value
      Since:
      API version 1

    • setSysexCallback

      void setSysexCallback(SysexMidiDataReceivedCallback callback)
      Registers a callback for receiving sysex MIDI messages on this MIDI input port.
      Parameters:
      callback - a callback function that takes a single string argument
      Since:
      API version 1

    • createNoteInput

      NoteInput createNoteInput(String name, String... masks)
      Creates a note input that appears in the track input choosers in Bitwig Studio. This method must be called within the `init()` function of the script. The messages matching the given mask parameter will be fed directly to the application, and are not processed by the script.
      Parameters:
      name - the name of the note input as it appears in the track input choosers in Bitwig Studio
      masks - a filter string formatted as hexadecimal value with `?` as wildcard. For example `80????` would match note-off on channel 1 (0). When this parameter is null, a standard filter will be used to forward note-related messages on channel 1 (0). If multiple note input match the same MIDI event then they'll all receive the MIDI event, and if one of them does not consume events then the events won't be consumed.
      Returns:
      the object representing the requested note input
      Since:
      API version 1

    • createAbsoluteCCValueMatcher

      AbsoluteHardwareValueMatcher createAbsoluteCCValueMatcher(int channel, int controlNumber)
      Creates a matcher that matches the absolute value of a MIDI CC message.
      Since:
      API version 10

    • createAbsoluteCCValueMatcher

      AbsoluteHardwareValueMatcher createAbsoluteCCValueMatcher(int controlNumber)
      Creates a matcher that matches the absolute value of a MIDI CC message regardless of its channel.
      Since:
      API version 11

    • createPolyAftertouchValueMatcher

      AbsoluteHardwareValueMatcher createPolyAftertouchValueMatcher(int channel, int note)
      Creates a matcher that matches the absolute value of a Poly AT message.
      Since:
      API version 10

    • createRelativeSignedBitCCValueMatcher

      RelativeHardwareValueMatcher createRelativeSignedBitCCValueMatcher(int channel, int controlNumber, int valueAmountForOneFullRotation)
      Creates a matcher that matches the relative value of a MIDI CC message encoded using signed bit.
      Parameters:
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createRelativeSignedBit2CCValueMatcher

      RelativeHardwareValueMatcher createRelativeSignedBit2CCValueMatcher(int channel, int controlNumber, int valueAmountForOneFullRotation)
      Creates a matcher that matches the relative value of a MIDI CC message encoded using signed bit 2.
      Parameters:
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createRelativeBinOffsetCCValueMatcher

      RelativeHardwareValueMatcher createRelativeBinOffsetCCValueMatcher(int channel, int controlNumber, int valueAmountForOneFullRotation)
      Creates a matcher that matches the relative value of a MIDI CC message encoded using bin offset.
      Parameters:
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createRelative2sComplementCCValueMatcher

      RelativeHardwareValueMatcher createRelative2sComplementCCValueMatcher(int channel, int controlNumber, int valueAmountForOneFullRotation)
      Creates a matcher that matches the relative value of a MIDI CC message encoded using 2s complement.
      Parameters:
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createAbsolutePitchBendValueMatcher

      AbsoluteHardwareValueMatcher createAbsolutePitchBendValueMatcher(int channel)
      Create a matcher that matches the absolute value of a MIDI pitch bend message.
      Since:
      API version 10

    • createSequencedValueMatcher

      AbsoluteHardwareValueMatcher createSequencedValueMatcher(AbsoluteHardwareValueMatcher firstValueMatcher, AbsoluteHardwareValueMatcher secondValueMatcher, boolean areMostSignificantBitsInSecondEvent)
      Creates an absolute value matcher that is defined by 2 separate MIDI events that have to occur in sequence. This can be used to get a much higher precision value that a single MIDI event would allow. Some controllers for example will send 2 CC events for a single value.
      Since:
      API version 10

    • createAbsoluteValueMatcher

      AbsoluteHardwareValueMatcher createAbsoluteValueMatcher(String eventExpression, String valueExpression, int valueBitCount)
      Creates a matcher that matches the absolute value of a MIDI CC message by using expressions to filter and extract a value out of the MIDI event.
      Parameters:
      eventExpression - Expression that must be true in order to extract the value.
      valueExpression - Expression that determines the value once an event has been matched.
      valueBitCount - The number of bits that are relevant from the value extracted by the valueExpression.
      Since:
      API version 10

    • createRelativeValueMatcher

      RelativeHardwareValueMatcher createRelativeValueMatcher(String eventExpression, double relativeAdjustment)
      Creates a matcher that applies a relative adjustment when a MIDI event occurs matching an expression.
      Parameters:
      eventExpression - Expression that must be true in order to extract the value.
      relativeAdjustment - The amount of relative adjustment that should be applied
      Since:
      API version 10

    • createRelativeSignedBitValueMatcher

      RelativeHardwareValueMatcher createRelativeSignedBitValueMatcher(String eventExpression, String valueExpression, int valueBitCount, int valueAmountForOneFullRotation)
      Creates a matcher that matches the relative value (encoded as signed bit) of a MIDI CC message by using expressions to filter and extract a value out of the MIDI event.
      Parameters:
      eventExpression - Expression that must be true in order to extract the value.
      valueExpression - Expression that determines the value once an event has been matched.
      valueBitCount - The number of bits that are relevant from the value extracted by the valueExpression.
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createRelativeSignedBitValueMatcher

      RelativeHardwareValueMatcher createRelativeSignedBitValueMatcher(AbsoluteHardwareValueMatcher valueMatcher, int valueAmountForOneFullRotation)
      Creates a matcher that converts a value matched by an AbsoluteHardwareValueMatcher to a relative value using signed bit.
      Parameters:
      valueMatcher - Value matcher that matches the value that needs to be converted to a relative value
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createRelativeSignedBit2ValueMatcher

      RelativeHardwareValueMatcher createRelativeSignedBit2ValueMatcher(String eventExpression, String valueExpression, int valueBitCount, int valueAmountForOneFullRotation)
      Creates a matcher that matches the relative value (encoded as signed bit 2) of a MIDI CC message by using expressions to filter and extract a value out of the MIDI event.
      Parameters:
      eventExpression - Expression that must be true in order to extract the value.
      valueExpression - Expression that determines the value once an event has been matched.
      valueBitCount - The number of bits that are relevant from the value extracted by the valueExpression.
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createRelativeSignedBit2ValueMatcher

      RelativeHardwareValueMatcher createRelativeSignedBit2ValueMatcher(AbsoluteHardwareValueMatcher valueMatcher, int valueAmountForOneFullRotation)
      Creates a matcher that converts a value matched by an AbsoluteHardwareValueMatcher to a relative value using signed bit 2.
      Parameters:
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createRelativeBinOffsetValueMatcher

      RelativeHardwareValueMatcher createRelativeBinOffsetValueMatcher(String eventExpression, String valueExpression, int valueBitCount, int valueAmountForOneFullRotation)
      Creates a matcher that matches the relative value (encoded as bin offset) of a MIDI CC message by using expressions to filter and extract a value out of the MIDI event.
      Parameters:
      eventExpression - Expression that must be true in order to extract the value.
      valueExpression - Expression that determines the value once an event has been matched.
      valueBitCount - The number of bits that are relevant from the value extracted by the valueExpression.
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createRelativeBinOffsetValueMatcher

      RelativeHardwareValueMatcher createRelativeBinOffsetValueMatcher(AbsoluteHardwareValueMatcher valueMatcher, int valueAmountForOneFullRotation)
      Creates a matcher that converts a value matched by an AbsoluteHardwareValueMatcher to a relative value using bin offset.
      Parameters:
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createRelative2sComplementValueMatcher

      RelativeHardwareValueMatcher createRelative2sComplementValueMatcher(String eventExpression, String valueExpression, int valueBitCount, int valueAmountForOneFullRotation)
      Creates a matcher that matches the relative value (encoded as 2s complement) of a MIDI CC message by using expressions to filter and extract a value out of the MIDI event.
      Parameters:
      eventExpression - Expression that must be true in order to extract the value.
      valueExpression - Expression that determines the value once an event has been matched.
      valueBitCount - The number of bits that are relevant from the value extracted by the valueExpression.
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createRelative2sComplementValueMatcher

      RelativeHardwareValueMatcher createRelative2sComplementValueMatcher(AbsoluteHardwareValueMatcher valueMatcher, int valueAmountForOneFullRotation)
      Creates a matcher that converts a value matched by an AbsoluteHardwareValueMatcher to a relative value using 2s complement.
      Parameters:
      valueAmountForOneFullRotation - The value that would represent one full rotation to the right (should be very similar to the amount of rotation needed to take an absolute knob from 0 to 1). For example, if a value of 127 meant it had been rotated to the right by a full rotation then you would pass 127 here. This ensures that RelativeHardwareControls have similar sensitivity to each other and can be mapped and behave in a very similar way to AbsoluteHardwareControls.
      Since:
      API version 10

    • createCCActionMatcher

      HardwareActionMatcher createCCActionMatcher(int channel, int controlNumber, int value)
      Creates a matcher that recognizes an action when getting a MIDI CC event with a specific value.
      Since:
      API version 10

    • createCCActionMatcher

      HardwareActionMatcher createCCActionMatcher(int channel, int controlNumber)
      Creates a matcher that recognizes an action when getting a MIDI CC event regardless of the value.
      Since:
      API version 10

    • createNoteOnActionMatcher

      HardwareActionMatcher createNoteOnActionMatcher(int channel, int note)
      Creates a matcher that recognizes an action when a MIDI note on event occurs.
      Since:
      API version 10

    • createNoteOnVelocityValueMatcher

      AbsoluteHardwareValueMatcher createNoteOnVelocityValueMatcher(int channel, int note)
      Creates a matcher that recognizes a note's on velocity when a MIDI note on event occurs.
      Since:
      API version 10

    • createNoteOffVelocityValueMatcher

      AbsoluteHardwareValueMatcher createNoteOffVelocityValueMatcher(int channel, int note)
      Creates a matcher that recognizes a note's off velocity when a MIDI note off event occurs.
      Since:
      API version 10

    • createNoteOffActionMatcher

      HardwareActionMatcher createNoteOffActionMatcher(int channel, int note)
      Creates a matcher that recognizes an action when a MIDI note off event occurs.
      Since:
      API version 10

    • createActionMatcher

      HardwareActionMatcher createActionMatcher(String expression)
      Creates a matcher that can match an action from a MIDI event. For example, pressing a button based on input of a MIDI CC event.
      Parameters:
      expression - Expression returns true if the event matches

    • hardwareAddress

      String hardwareAddress()
      Returns:
      The address of the hardware device this port belongs to. If two ports belong to the same physical device, they have the same address.
      Since:
      API version 21