Bitwig Studio Control Surface API  5.0.11
MidiIn Interface Reference

Public Member Functions

void setMidiCallback (ShortMidiDataReceivedCallback callback)
 
void setSysexCallback (SysexMidiDataReceivedCallback callback)
 
NoteInput createNoteInput (String name, String... masks)
 
AbsoluteHardwareValueMatcher createAbsoluteCCValueMatcher (int channel, int controlNumber)
 
AbsoluteHardwareValueMatcher createAbsoluteCCValueMatcher (int controlNumber)
 
AbsoluteHardwareValueMatcher createPolyAftertouchValueMatcher (int channel, int note)
 
RelativeHardwareValueMatcher createRelativeSignedBitCCValueMatcher (int channel, int controlNumber, int valueAmountForOneFullRotation)
 
RelativeHardwareValueMatcher createRelativeSignedBit2CCValueMatcher (int channel, int controlNumber, int valueAmountForOneFullRotation)
 
RelativeHardwareValueMatcher createRelativeBinOffsetCCValueMatcher (int channel, int controlNumber, int valueAmountForOneFullRotation)
 
RelativeHardwareValueMatcher createRelative2sComplementCCValueMatcher (int channel, int controlNumber, int valueAmountForOneFullRotation)
 
AbsoluteHardwareValueMatcher createAbsolutePitchBendValueMatcher (int channel)
 
AbsoluteHardwareValueMatcher createSequencedValueMatcher (AbsoluteHardwareValueMatcher firstValueMatcher, AbsoluteHardwareValueMatcher secondValueMatcher, boolean areMostSignificantBitsInSecondEvent)
 
AbsoluteHardwareValueMatcher createAbsoluteValueMatcher (String eventExpression, String valueExpression, int valueBitCount)
 
RelativeHardwareValueMatcher createRelativeValueMatcher (String eventExpression, double relativeAdjustment)
 
RelativeHardwareValueMatcher createRelativeSignedBitValueMatcher (String eventExpression, String valueExpression, int valueBitCount, int valueAmountForOneFullRotation)
 
RelativeHardwareValueMatcher createRelativeSignedBitValueMatcher (AbsoluteHardwareValueMatcher valueMatcher, int valueAmountForOneFullRotation)
 
RelativeHardwareValueMatcher createRelativeSignedBit2ValueMatcher (String eventExpression, String valueExpression, int valueBitCount, int valueAmountForOneFullRotation)
 
RelativeHardwareValueMatcher createRelativeSignedBit2ValueMatcher (AbsoluteHardwareValueMatcher valueMatcher, int valueAmountForOneFullRotation)
 
RelativeHardwareValueMatcher createRelativeBinOffsetValueMatcher (String eventExpression, String valueExpression, int valueBitCount, int valueAmountForOneFullRotation)
 
RelativeHardwareValueMatcher createRelativeBinOffsetValueMatcher (AbsoluteHardwareValueMatcher valueMatcher, int valueAmountForOneFullRotation)
 
RelativeHardwareValueMatcher createRelative2sComplementValueMatcher (String eventExpression, String valueExpression, int valueBitCount, int valueAmountForOneFullRotation)
 
RelativeHardwareValueMatcher createRelative2sComplementValueMatcher (AbsoluteHardwareValueMatcher valueMatcher, int valueAmountForOneFullRotation)
 
HardwareActionMatcher createCCActionMatcher (int channel, int controlNumber, int value)
 
HardwareActionMatcher createCCActionMatcher (int channel, int controlNumber)
 
HardwareActionMatcher createNoteOnActionMatcher (int channel, int note)
 
AbsoluteHardwareValueMatcher createNoteOnVelocityValueMatcher (int channel, int note)
 
AbsoluteHardwareValueMatcher createNoteOffVelocityValueMatcher (int channel, int note)
 
HardwareActionMatcher createNoteOffActionMatcher (int channel, int note)
 
HardwareActionMatcher createActionMatcher (String expression)
 

Detailed Description

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 MidiIn#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

Member Function Documentation

◆ createAbsoluteCCValueMatcher() [1/2]

AbsoluteHardwareValueMatcher createAbsoluteCCValueMatcher ( int  channel,
int  controlNumber 
)

Creates a matcher that matches the absolute value of a MIDI CC message.

Since
API version 10

◆ createAbsoluteCCValueMatcher() [2/2]

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

◆ createAbsolutePitchBendValueMatcher()

AbsoluteHardwareValueMatcher createAbsolutePitchBendValueMatcher ( int  channel)

Create a matcher that matches the absolute value of a MIDI pitch bend message.

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
eventExpressionExpression that must be true in order to extract the value.
valueExpressionExpression that determines the value once an event has been matched.
valueBitCountThe number of bits that are relevant from the value extracted by the valueExpression.
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
expressionExpression returns true if the event matches

◆ createCCActionMatcher() [1/2]

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

◆ createCCActionMatcher() [2/2]

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

◆ 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
namethe name of the note input as it appears in the track input choosers in Bitwig Studio
masksa 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 wont' be consumed.

Returns
the object representing the requested note input
Since
API version 1

◆ 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

◆ 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

◆ 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

◆ createPolyAftertouchValueMatcher()

AbsoluteHardwareValueMatcher createPolyAftertouchValueMatcher ( int  channel,
int  note 
)

Creates a matcher that matches the absolute value of a Poly AT message.

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
valueAmountForOneFullRotationThe 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() [1/2]

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
valueAmountForOneFullRotationThe 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() [2/2]

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
eventExpressionExpression that must be true in order to extract the value.
valueExpressionExpression that determines the value once an event has been matched.
valueBitCountThe number of bits that are relevant from the value extracted by the valueExpression.
valueAmountForOneFullRotationThe 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
valueAmountForOneFullRotationThe 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() [1/2]

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
valueAmountForOneFullRotationThe 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() [2/2]

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
eventExpressionExpression that must be true in order to extract the value.
valueExpressionExpression that determines the value once an event has been matched.
valueBitCountThe number of bits that are relevant from the value extracted by the valueExpression.
valueAmountForOneFullRotationThe 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
valueAmountForOneFullRotationThe 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() [1/2]

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
valueAmountForOneFullRotationThe 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() [2/2]

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
eventExpressionExpression that must be true in order to extract the value.
valueExpressionExpression that determines the value once an event has been matched.
valueBitCountThe number of bits that are relevant from the value extracted by the valueExpression.
valueAmountForOneFullRotationThe 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

◆ 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
valueAmountForOneFullRotationThe 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() [1/2]

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
valueMatcherValue matcher that matches the value that needs to be converted to a relative value
valueAmountForOneFullRotationThe 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() [2/2]

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
eventExpressionExpression that must be true in order to extract the value.
valueExpressionExpression that determines the value once an event has been matched.
valueBitCountThe number of bits that are relevant from the value extracted by the valueExpression.
valueAmountForOneFullRotationThe 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

◆ createRelativeValueMatcher()

RelativeHardwareValueMatcher createRelativeValueMatcher ( String  eventExpression,
double  relativeAdjustment 
)

Creates a matcher that applies a relative adjustment when a MIDI event occurs matching an expression.

Parameters
eventExpressionExpression that must be true in order to extract the value.
relativeAdjustmentThe amount of relative adjustment that should be applied
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

◆ setMidiCallback()

void setMidiCallback ( ShortMidiDataReceivedCallback  callback)

Registers a callback for receiving short (normal) MIDI messages on this MIDI input port.

Parameters
callbacka 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
callbacka callback function that takes a single string argument
Since
API version 1

The documentation for this interface was generated from the following file: