NFX Template for FL Studio

Overview

This is a template for creating FL Studio MIDI scripts based on the FL Scripting API. It provides a structured approach to handling MIDI events and interactions with FL Studio.

The FL Studio MIDI API is documented here: FL Studio MIDI Scripting Manual

There is a support forum for the MIDI API here: FL Studio MIDI Scripting Forum

This template is designed for FL Studio version 25.0 or greater.

Architecture

The template uses a two-file architecture to separate concerns:

There is a "device_" file that is seen by FL Studio and sets up the link, and there is a "main.py" file that implements the actual code.

This two-file architecture is designed to:

1. Keep code organization clean
2. Provide exception handling via the CallEx() method in the "device_" file
3. Allow you to modify implementation without changing the FL Studio interface

Note: You should rename the "device_" file to match your hardware. Throughout this documentation, it will be referred to as device_XXXX for examples.

1. device_NFX_Template.py:

   • Acts as the entry point that gets called directly by FL Studio
   • Receives callbacks from FL Studio (OnInit, OnMidiIn, OnRefresh, etc.)
   • Passes these calls to the implementation contained in main.py
   • Provides error handling through the CallEx function

2. main.py:

   • Contains the actual implementation in the mainScript class
   • Implements methods corresponding to the FL Studio callbacks
   • Handles MIDI events, user interface updates, and other functionality
   • Can be modified without changing the interface with FL Studio

Installation

Place these template files in the following location:

[Your FL Studio User Data Folder]\FL Studio\Settings\Hardware\[YourControllerName]

Typical user data folder locations:

• Windows: C:\Users\[YourUsername]\Documents\Image-Line
• Mac: /Users/[YourUsername]/Documents/Image-Line

Usage

To create your own MIDI controller script:

1. Copy these template files to a new folder as described in the Installation section
2. Edit the first line in device_NFX_Template.py to indicate your device name (e.g., # name=Your Device Name)
3. Rename device_NFX_Template.py to indicate your device. For example: device_AKAI_FL_Fire.py
4. Modify the mainScript class in main.py to implement your desired functionality
5. The device_XXXX file has many methods commented out. If and when you need them, uncomment them and implement the corresponding method in main.py

Tip: Review the comments in both files to understand the purpose of each method.

Editing the script

I use a free editor called Visual Studio Code (VSCode) to do my editing and I highly recommend it for you. It offers features like syntax highlighting, code completion, and debugging capabilities that make Python scripting much easier.

Using the script

To start using your script in FL Studio:

1. Go to Options → MIDI Settings
2. Click the Refresh Device List button and give it a moment to complete the refresh
3. In the Input section, select your MIDI device
4. In the Controller Type dropdown, find and select the device name you used in your script

Tip: You can see script output in FL Studio by selecting View → Script Output and then selecting the tab with your device name. This is extremely helpful for debugging.

Script code flow

The way the script code flows is as follows:

FL Studio → device_XXXX.py → main.py

It may seem redundant to have a device_XXXX.py and main.py file, but this method makes it easy to handle exceptions and implement higher-level functions. This architecture is modeled after the original Akai Fire script from Image-Line.

FL API code flow

The FL API makes calls to the OnXXXX functions inside device_XXXX.py

The basic flow for most MIDI input goes like this:

OnMidiIn() → OnMidiMsg() → OnNoteOn() or OnNoteOff()

This is a simplified example as there are other OnXXX() methods for various purposes. Check the FL Studio MIDI Scripting documentation for details.

Important: Any method that receives an "event" parameter (such as OnMidiIn() or OnMidiMsg()) can set event.handled = True to stop event propagation. For example, if you set event.handled = True in OnMidiIn(), the OnMidiMsg() event would not be called.

Starter code

This template is minimal but fully functional for development. The code currently implements:

• OnMidiIn() - Captures raw MIDI input and prints it to the script output
• OnMidiMsg() - Processes MIDI messages and provides a foundation for your implementation
• Error handling - The CallEx() function in device_NFX_Template.py catches exceptions and provides detailed error information

The sample starter code allows you to see which control on your device is being pressed/tweaked, making it easier to identify button/knob IDs for your implementation.

The 'event' parameter will have the control ID of the input as event.data1 and the velocity or value as event.data2.

I suggest you implement the actual code to do something in OnMidiMsg().

For example, if you want to implement the transport controls of your hardware:

1. Run the script and press the Stop button on your device
2. Check the script output and see that it returns event.data1 as a value of 6 (the actual value will be different for all devices)
3. Note that event.data2 is greater than 0 when pressed and 0 when released
4. To handle the Stop button when pressed, add this code inside OnMidiMsg():

if event.data1 == 6 and event.data2 > 0:
    transport.stop()

Troubleshooting

If your script isn't working as expected:

1. Check the script output window for any error messages or debugging information
2. Verify that your device is properly connected and recognized by FL Studio
3. Ensure you're receiving MIDI data from your device (visible in the script output)
4. Check for syntax errors or logical bugs in your implementation

Common issues:

• Script not showing up in Controller Type dropdown: Make sure the # name=Your Device Name line is correct and that you've placed the files in the proper folder
• No MIDI data appearing: Check device connections and ensure the correct input is selected
• Errors in script output: The CallEx function will display detailed error information including file, line number, and exception type

Conclusion

I hope this template serves you well and makes coding your own script easier. With the two-file architecture, you can:

• Focus on implementing your device's functionality without worrying about FL Studio's interface
• Take advantage of built-in error handling
• Build complex functionality by extending the template

Feel free to share your creations or improvements to this template with the FL Studio community!

Resources

• FL Studio MIDI Scripting Manual
• FL Studio MIDI Scripting Forum

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Nelson F. Fernandez Jr. [email protected]

Version History

• 2.2025.1116: Initial template release