Device

FL Studio built-in module.

Handles the way that devices connect to FL Studio's MIDI interface, and how scripts communicate with each other.

`baseTrackSelect(index, step)`

Base track selection (for control surfaces). Set step to MaxInt to reset.

HELP WANTED

What does this do?

Args:

index (int): ???
step (int): ???

Included since API version 1.

`createRefreshThread()`

Start a threaded refresh of the entire MIDI device.

HELP WANTED

What do refresh threads do?

Included since API version 1

`destroyRefreshThread()`

Stop a previously started threaded refresh.

HELP WANTED

What do refresh threads do?

Included since API version 1

`directFeedback(eventData)`

Send a received message to the linked output device.

Args

eventData (eventData): event to send.

Included since API version 1.

`dispatch(ctrlIndex, message, sysex=None)`

Dispatch a MIDI message (either via a standard MIDI Message or through a system exclusive (SysEx) message) that is sent to another controller script. This allows communication between different devices provided that they have a standardized communication method.

MIDI messages sent through this method are received in the same way as all other messages, so it should be ensured that they can be differentiated by the receiving controller.

In order to allow a device to receive MIDI messages via a dispatch command, it must have a receiveFrom pre-processor comment for FL Studio to detect when the script is loaded. This comment should be at the top of the device_MyController.py file along with the name and URL, for example:

# name=My Controller
# receiveFrom=My Other Controller

After this declaration, the script named "My Other Controller" will be able to dispatch MIDI messages to the script named "My Controller".

Args

ctrlIndex (int): index of the controller to dispatch to.
message (int): MIDI message to send (0xF0 for a SysEx message).
sysex (bytes, optional): SysEx data to send, if applicable.

Example Usage

# Send a standard MIDI event (middle C note on) to the device indexed 0.
device.dispatch(0, 0x90 + (0x3C << 8) + (0x7F << 16))

# Send a sysex MIDI event to the device indexed 0. Note that the full
# message is still contained within the bytes object, even though the
# `0xF0` is also given as `message`.
device.dispatch(0, 0xF0, bytes([0xF0, 0x7E, 0x7F, 0x06, 0x01, 0xF7]))

Included since API version 1.

`dispatchGetReceiverPortNumber(ctrlIndex)`

Returns the port of the receiver device specified by ctrlIndex.

Args

ctrlIndex (int): device script to check.

Returns

int: MIDI port associated with the receiver device.

Included since API version 5.

`dispatchReceiverCount()`

Returns the number of device scripts that this script can dispatch to.

Returns

int: number of available receiver devices.

Included since API version 1.

`findEventID(controlId, flags=0)`

Given a hardware control ID, returns the eventId of the software control that it is linked to or midi.REC_InvalidID if it is not linked.

Args

controlId (int): ID of control surface.
flags (int, optional): ???. Defaults to 0.

Returns

int: event ID.

Included since API version 1.

`forwardMIDICC(message, mode=1)`

Forwards a MIDI CC message to the currently focused plugin.

Args

message (int): MIDI message to forward.
mode (int, optional): Where to send the message:
- 0: Send the message to all plugins.
- 1 (default): Send the message to only the focused plugin.
- 2: Send the message to all selected channels.

Included since API version 7.

`fullRefresh()`

Trigger a previously started threaded refresh. If there is none, the refresh is triggered immediately.

HELP WANTED

What do refresh threads do?

Included since API version 1

`getDeviceID()`

Returns the unique device identifier of the connected device, as determined by FL Studio when connecting the device.

Note that this does not include the Sysex header, or ending byte.

For example, if the device responded to a universal device enquiry with:

bytes([
    0xF0, 0x7E, 0x01, 0x06, 0x02,
    0x00, 0x20, 0x29, 0x02, 0x01,
    0x00, 0x00, 0x00, 0x04, 0x02,
    0x05, 0xF7,
])

This function would only return:

bytes([0x00, 0x20, 0x29, 0x02, 0x01, 0x00, 0x00, 0x00, 0x04, 0x02, 0x05])

Returns

bytes: device ID.

Included since API Version 25.

`getIdleElapsed()`

???

WARNING:

This function is not officially documented

Returns

float: ???

Included since API Version ???

`getLinkedChannel(eventId)`

Returns the MIDI channel associated with a linked control.

This is the MIDI channel of the event that is mapped to the linked control. Result is -1 if there is no linked control.

Args

eventId (int): event ID to get channel for.

Returns

int: MIDI channel.

Included since API Version 27.

`getLinkedInfo(eventID)`

Returns information about a linked control via eventID.

Args

eventID (int): eventID (see the event mapping tutorial).

Returns

int: linked control info:
- -1: no linked control.
- Event_CantInterpolate (1): ???
- Event_Float (2): ???
- Event_Centered (4): ???

Included since API version 1.

`getLinkedParamName(eventID)`

Returns the parameter name of the REC event at eventID.

Args

eventID (int): eventID.

Returns

str: Parameter name.

Example usage

>>> channel_rec_id = channels.getRecEventId(0)
>>> device.getLinkedParamName(channel_rec_id + midi.REC_Chan_Vol)
'Channel volume'
>>> device.getLinkedParamName(channel_rec_id + midi.REC_Chan_Pan)
'Channel panning'

Included since API version 10.

`getLinkedValue(eventID)`

Returns value of the software control associated with eventID between 0.0 and 1.0, or -1 if there is no linked control.

Args

eventID (int): eventID.

Returns

float: Current value of the controller parameter.

Example usage

# Gets the volume and panning of channel 0
>>> channel_rec_id = channels.getRecEventId(0)
>>> device.getLinkedValue(channel_rec_id + midi.REC_Chan_Vol)
0.78125
>>> device.getLinkedValue(channel_rec_id + midi.REC_Chan_Pan)
0.5

Included since API version 1.

`getLinkedValueString(eventID)`

Returns text value of the REC event at eventID.

The text representation is formatted appropriately based on the REC parameter.

Args

eventID (int): eventID.

Returns

str: Parameter value string.

Example usage

>>> channel_rec_id = channels.getRecEventId(0)
>>> device.getLinkedValueString(channel_rec_id + midi.REC_Chan_Vol)
'-5.2 dB'
>>> device.getLinkedValueString(channel_rec_id + midi.REC_Chan_Pan)
'Centered'

Included since API version 10.

`getMasterSync()`

Returns the value of the "send master sync" option in FL Studio's MIDI settings for this device.

This option returns whether stop, pause and play transport notifications are sent to the MIDI device, and shouldn't be enabled unless the device explicitly requires it, as it can lead to unpredictable and sometimes broken behavior.

Returns

bool: Whether master sync is enabled.

Included since API Version 19.

`getName()`

Returns the name of the device.

Returns

str: device name.

Included since API version 7.

`getPortNumber()`

Returns the port number for the input device that the script is attached to.

If the device requires two-way communication, the output port (where functions like device.midiOutMsg() send their data to) should be set to the value of the input port, which is returned by this function.

Returns

int: port number of the input device.

Included since API version 1.

`hardwareRefreshMixerTrack(index)`

Hardware refresh mixer track at index.

HELP WANTED

What does this mean?

Args

index (int): track index. -1 refreshes all tracks.

Included since API version 1.

`isAssigned()`

Returns True if an output interface is linked to the script, meaning that the script can send MIDI messages to that device.

Returns

bool: whether the device is assigned.

Included since API version 1.

`isDoubleClick(index)`

Returns whether the function was called with the same index shortly before, indicating a double click.

Args

index (int): a unique value representing the current control.

Returns

bool: whether the event was a double click.

Included since API version 1.

`isMidiOutAssigned()`

???

WARNING

This function is not officially documented.
Calling this function in an interpreter not associated with a device causes FL Studio to crash.

Returns

bool: ???

Included since API Version ???

`linkToLastTweaked(controlIndex, channel, global_link=False, eventId=midi.REC_None)`

Links the control with the given index to the last tweaked parameter.

WARNING

This function is subject to change before the release of FL Studio 21.

Args

controlIndex (int): the control ID to link.
channel (int): ???
global_link (bool, optional): Whether to make a global link (applies to all projects, True), or a standard link (only for this project, False). Defaults to False.
eventId (int, optional): ID of the event to link to. If this is unset, the link will be created with the most recently tweaked parameter. Defaults to midi.REC_None.

Returns

0: successfully created link.
1: no parameters recently tweaked.
2: control with this controlId is already assigned.

Included since API Version 21.

`midiOutMsg(message, channel=-1, data1=-1, data2=-1)`

Sends a MIDI message to the linked output device.

This can be done either through a single combined message, or in its distinct components.

Args

message (int):
- the MIDI message to send (if sending a complete message):
  - Lowest byte: status.
  - Middle byte: data 1.
  - Upper byte: data 2.
- OR the message type (if sending a partial MIDI message, eg 0xB for a CC message).
channel (int, optional): the channel to send the message to (if sending a partial MIDI message).
data1 (int, optional): the note data value for the message (if sending a partial MIDI message).
data2 (int, optional): the velocity data value for the message (if sending a partial MIDI message).

Included since API version 1, with the component options added in API version 2.

`midiOutNewMsg(slotIndex, message)`

Sends a MIDI message to the linked output device, but only if the message being sent has changed compared to the last message sent with the same slotIndex.

Args

slotIndex (int): index for MIDI message comparison.
message (int): message to potentially send.

Included since API version 1.

`midiOutSysex(message)`

Send a sysex message to the (linked) output device.

The sysex data must include the sysex start 0xF0 and sysex end 0xF7 bytes, or FL Studio will ignore the function call entirely.

Args

message (str): Sysex message to send.

Included since API version 1.

`processMIDICC(eventData)`

Let FL Studio process a MIDI CC message.

Args

eventData (FlMidiMsg): FL MIDI Event to process.

Included since API version 1.

`repeatMidiEvent(eventData, delay=300, rate=300)`

Start repeatedly sending out the message in eventData every rate ms after delay ms.

Args

eventData (eventData): event to repeat.
delay (int, optional): initial delay before sending in ms. Defaults to 300.
rate (int, optional): time between each send in ms. Defaults to 300.

Included since API version 1.

`sendMsgGeneric(id, message, lastMsg, offset=0)`

Send a text string as a sysex message to the linked output device.

WARNING:

This function is deprecated.

Args

id (int): the first 6 bytes of the message (the end value 0xF7 is added automatically).
message (str): the text to send.
lastMsg (str): the string returned by the previous call to this function.
offset (int, optional): ???. Defaults to 0.

Returns

str: value to use in the next call of this function.

Included since API version 1.

Deprecated since API version 9.

`setHasMeters()`

Registers the controller as having peak meters, meaning that the OnUpdateMeters() function will be called. This function should be called within OnInit().

Included since API version 1.

`setMasterSync(value)`

Control the value of the "send master sync" option in FL Studio's MIDI settings for this device.

This option controls whether stop, pause and play transport notifications are sent to the MIDI device. This shouldn't be enabled unless the device explicitly requires it, as it can lead to unpredictable and sometimes broken behavior.

Args

value (bool): Whether to enable (or disable) the "send master sync" option.

Included since API Version 18.

`stopRepeatMidiEvent()`

Stop sending a currently repeating MIDI event.

Refer to device.repeatMidiEvent().

Included since API version 1.