MIDI scripting allows native support for any MIDI controller. Scripts are a piece of Python code, stored in a plain text file, that FL Studio uses to translate commands between the controller and FL Studio. This communication can go in both directions. The controller can access features in the FL Studio code (as listed below), and FL Studio can send data back to the controller (such as lighting pads or showing track names).
FL Studio MIDI scripts are based on Python. You do not need to install anything, FL Studio will handle scripts directly. When scripts are created in the folders shown below, the scripted device will display in the Controller type menu under the MIDI Settings tab. From there, select the controller and use it as normal.
Script hierarchy - As FL Studio natively handles many MIDI functions and messages, this allows you to write simple scripts to handle specific cases or inputs and leave the rest to FL Studio's generic MIDI support. For example, you do not need to tell FL Studio what to do with MIDI notes. If the script doesn't specifically make changes to default behaviour, FL Studio will use them as normal.
Scripts are complex - With flexibility and power comes complexity. MIDI scripting is intended for hardware manufacturers and advanced users to create custom support for MIDI controllers. If you are new to programming, MIDI scripting will be confronting and confusing. This is normal, but patience and persistence will be rewarded! There are some simple examples to get started on our user forum listed below.
FL Studio will check the following locations for MIDI Scripts and related files:
Script files - Scripted device files are located in the User data folder under ... Documents\Image-Line\FL Studio\Settings\Hardware\devicename\device_devicename.py.
Script folder naming - The sub folder 'devicename' is arbitrary and can be anything you like. Normally you would use the name of the MIDI hardware you are scripting for.
Script file naming - The 'device_devicename' (bold part) can be anything you like to identify the MIDI script file. NOTE: 'device_devicename.py' is mandatory for the device to be processed by FL Studio. You can use spaces and capitals for devicename e.g. 'device_My PHAT Controller.py'.
The controller name - Shown in the MIDI Settings > Controller type menu is defined on first line of 'device_devicename.py' script file, e.g. #name=AKAI FL Studio Fire. This will appear in the device list as 'AKAI FL Studio Fire (user)'. The (user) suffix is to distinguish your device scripts vs installed factory scripts.
Editing .py script files - Use any text editor. If you are editing existing scripts, make a backup of the original files.
Device (launchmap) pages (optional) - Files are located in ... Documents\Image-Line\FL Studio\Settings\Hardware\devicename\Page(number).scr
Launchmap files - Launchmaps are custom files that provide diffent behaviour for a controller depending on what mode it is launched in. See the MIDI Controller reference post Custom controller layouts. See also the launchMapPages module.
Custom modules - You can include custom or external modules by placing them in the FL Studio installation, shared libary folder:
Windows - ... /Program Files (x86)/Image-Line/Shared/Python/Lib
NOTE: You do not need to install the Python compiler to edit and maintain these scripts, you can simply open and edit them with any text editor. FL Studio MIDI scripting is based on events (Script events) fired by FL Studio and responses (Callbacks) to these events.
Getting Started Tutorials
The basics of working with Script Files:
Starting from scratch, you need to create a script file, in the correct location in the FL Studio User data folder. This section and video shows you how to do that, step-by-step.
Create a folder - Using the file browser in your Operating System of choice, browse to your FL Studio User data folder, usually '...Documents\Image-Line\FL Studio\Settings\Hardware\YourScriptSubFolder', where 'YourScriptSubFolder' is a sub folder you created for your script.
Create a script file - In the 'YourScriptSubFolder' folder, create a plain text file 'device_YourScriptName.txt'. Open the text file and add the following line of text, which will be the script name that appears in the MIDI Settings > Controller type list:
# name=My First Script
Change the file extension type to .py - Change the file extension type from .txt to .py. To do this you must have file-type extensions activated in the browser on your computer. After that, just rename a plain text file 'device_ThisIsMyFistScript.txt' to 'device_ThisIsMyFistScript.py', for example. You can also use the operating system options to open files of type .py in the text editor of your choice.
Select your script in the MIDI Settings - You will now see your script in the MIDI Settings > Controller type list as My First Script (user).
Edit the script - Open this script in FL Studio from the VIEW (menu) > Script output > Edit script (button)
The following video shows steps 4 and 5 above.
This video shows how to find MIDI data coming from a controller, to use in a script:
After creating a script. You will probably want to identify data coming from your controller you want to link to a function in FL Studio, this video shows such an example.
NOTE: For the Interpreter tab to work you must select a script from the MIDI Settings > Controller type option.
The script used in this tutorial is available here.
Script functions (callbacks) are the instructions FL Studio will recognize and act upon in the Python code. Callbacks are organized in modules according to FL Studio target features (Playlist, Patterns, Device etc.). To use callbacks in script, you must load the callback module by including it at the top of the script with 'import':
import module (e.g. import playlist) - NOTE: Module names use Lower Camel Case. Available modules:
Callbacks are functions that execute features or act on components in FL Studio. You can for example, use a callback function to name an instrument Channel, move one up or down or delete it. Or, more simply remap the transport buttons in FL Studio to your controller. In other words, callbacks give you deep control over FL Studio and how it operates. To use function in script use following syntax:
module.functionName(arguments) - Where 'module' is module name. NOTE: Function names use Lower Camel Case.
Script events are functions called by FL Studio, if script needs to respond to the event, add event function to script:
def eventName(arguments) - Write response code inside this function. NOTE: Event names use Camel Case
Interpreter - This Tab allows you to enter and test Script commands to check they work as expected.
Script - When a MIDI Script is selected in the MIDI Settings the second tab will show with the name of the device (in this case FL STUDIO FIRE). When there are unhandled MIDI events, the data will be displayed here. NOTE: The Debugging log tab also shows ALL incoming MIDI data.
Clear output - Clears the tabs data.
Edit script - Open the current script in the system text editor to make changes.
Reload - Apply the edited script so you don't need to restart FL Studio to test it.
Called first when a MIDI message is received. Set the event's handled property to
True if you don't want further processing.
(only raw data is included here: handled, timestamp, status, data1, data2, port,
use this event for filtering, use OnMidiMsg event for actual processing ...
Called when something changed that the script might want to respond to.
Same as OnRefresh, but everything should be updated.
Called when the beat indicator has changes.
"value" can be off = 0, bar = 1 (on), beat = 2 (on)
Called when playlist zone changed
Called when something about performance mode has changed.
Called on mixer track(s) change, 'index' indicates track index of track that changed or -1 when all tracks changed
collect info about 'dirty' tracks here but do not handle track(s) refresh, wait for OnRefresh event with HW_Dirty_Mixer_Controls flag
Start Continuous move.
This function do same as rewind and fastforward but you can control speed.
Set speed (> 0) to move forward and (< 0) to move backward (speed
= (1) is normal speed forward)
Each call to this function with startStop = SS_Start, must be stopped with startStop = SS_Stop
long speed, long startStop
Start Continuous move.
Set speed (> 0) to move forward and (< 0) to move
backward (speed = (1) is normal speed forward).
Set startStop to (2) to start and to
(0) to stop
Set a playback speed multiplier.
Set speedMultiplier = (1) is normal speed, set to
value between (1/4 ... 1) for slower and between (1 ... 4) faster movement
Device module will handle MIDI devices connected to the FL Studio MIDI interface.
You send messages to output interface, retrieve linked control values... etc). MIDI
scripts, assigned to an input interface, can be mapped (linked) to an Output interface via
the Port Number. With mapped (linked) output interfaces, scripts can send midi messages to
output interfaces by using one of the midiOut*** messages.
Returns True if (linked) output interface is assigned.
Returns the interface port number. (or -1 when port number is not assigned)
this is same number as interface port number set in FL Studio Midi settings
Send a MIDI message to the (linked) output interface.
"message" holds the value to be sent, with the channel and command in the lower byte
and the first and second data values in the next two bytes.
long midiId, long channel, long data1, long data2
Send a MIDI message to the (linked) output interface (alternative version with separate parameters)
long slotIndex, long message
Send a MIDI message to the (linked) output interface, but only if the value has
"slotIndex" is a value chosen by the caller, it should be the same as it was for the
previous message that should be compared with.
"message" holds the value to be sent.
Send a SYSEX message to the (linked) output interface.
Send a text string as a SYSEX message to the (linked) output interface.
"id" holds the first 6 bytes of the message (starting with 0xF0). The end value 0xF7 is
"message" is the text to send
"lastMsg" is the string returned by the previous call to this function.
function returns updated lastMsg
Start repeatedly sending out the previously sent message.
It will be sent first after "delay" milliseconds, and afterwards every "rate"
Stop repeating the message sent with repeatMidiEvent.
long controlId, (long flags = )
Returns eventID for controlId.
"flags" can be one of the: FEID_Flags_Skip_Unsafe = 1 (skip unsafe (using formula)
Returns normalized value of the linked control via eventID
(to get control eventId, use findEventID function).
Result is -1 if there is no linked control.
Returns information about the linked control via eventID
(to get control eventId, use findEventID function).
Result is -1 if there is no linked control, otherwise result is one or more of the
Start a threaded refresh of the entire MIDI device.
Stop a previously started threaded refresh.
Trigger a previously started threaded refresh.
If there is none, the refresh is triggered immediately.
Returns True if the function was called with the same index shortly before,
indicating a double click.
use this in OnInit event to tell FL Studio device use peak meters
long index, long step
Base track selection (for control surfaces). Set step to MaxInt for reset.
Hardware refresh mixer track at "index", use -1 to refresh all
Dispatching between devices:
long ctrlIndex, long message, (bytes sysex)
Dispatch midi message (or sysex) to controller specified by ctrlIndex.
receiver (script) must define sender(s) inside script: # receiveFrom="Sender name"