PIANO ROLL
Scripting Reference
Piano roll scripts allow you to manipulate the note data in the Piano roll under the control of Python code. For example, select all notes higher than C3 (MIDI note number 36).
Support forum
Visit the FL Studio Piano roll Scripting user forum to download Piano roll scripts, ask questions or discuss scripting and python in general.
Script File Locations and File Names
FL Studio will check the locations listed below and show any Scripts it finds in the Piano roll Scripts menu. If you make or edit scripts put them in the User data 'Piano roll scripts' sub-folder. The user interfaces you see associated with scripts are automatically created based on the variables and text entry fields in the script.
- Script file naming - Files must end with the .pyscript extension. E.g., Any text you like here.pyscript
- User editable scripts - When creating your own scripts or editing ours, put them in the User scripts folder:
- User scripts folder - ...Documents\Image-Line\FL Studio\Settings\Piano roll scripts. NOTE: You can use sub folders to create category folders in the Piano roll script menu.
- Default installation folders - We don't recommend editing these scripts or editing the contents of the folders. Rather copy any scripts you want to modify to your 'User scripts folder', add 'edited' to the name so you don't get confused. If you complain about bugs in factory scripts that you created because you didn't follow this advice, our support staff will chastise you many times!
- Browser Library Download - ...Documents\Image-Line\Downloads\Piano roll scripts. Scripts downloaded from the FL Studio Browser Library.
- Windows Installation - ... \FL Studio 2024\System\Config\Piano roll scripts. Default Scripts installed at installation.
- macOS Installation - ... /Applications/FL Studio 2024/Contents/Resources/FL/System/Config/Piano roll scripts. Default Scripts installed at installation.
NOTE: Check the factory script folder for the file 'Piano roll script reference.txt'. This may be more updated than this page in the manual.
Example scripts
You do not need to install Python, FL Studio will interpret scripts itself. The script files are simply plain text format with the extension .pyscript. For example 'Mute selected notes.pyscript' for the example below.
One of the best ways to learn scripting is to make a copy of a simple one, and make edits to it to learn how it works. For example, text messages on the script etc.
Mute selected notes:
from flpianoroll import *
# loop through existing notes and set the "muted" flag
for i in range(score.noteCount):
score.getNote(i).muted = True
Script using the 'preview' feature:
from flpianoroll import *
def createDialog():
form = ScriptDialog('Add One Note', '')
form.AddInputKnob('Note Number', 36, 24, 48)
return form
def apply(form):
notenr = round(form.GetInputValue('Note Number'))
# ... do something here
API Reference
| Object | Members | Notes |
|---|---|---|
| # | User comments | Start comment lines with # |
| Note | ||
| number | note number (MIDI standard) | |
| time | ticks | |
| length | ticks | |
| group | group number this note belongs to | |
| pan | 0.0 to 1.0, default 0.5 | |
| velocity | 0.0 to 1.0, default 0.8 | |
| release | 0.0 to 1.0 | |
| color | 0 to 15, default 0. Color group / MIDI channel. | |
| fcut | 0.0 to 1.0, default 0.5 | |
| fres | 0.0 to 1.0, default 0.5 | |
| pitchofs | -120 to 120 | |
| slide | True/False | |
| porta | True/False | |
| muted | True/False | |
| selected | True/False | |
| clone() | duplicate note/s | |
| Marker | ||
| time | ticks | |
| name | marker name | |
| mode | integer | |
| tsnum | when marker is a time signature | |
| tsden | when marker is a time signature | |
| scale_root (scale markers only) | note class of the scale's tonic, with C as 0 (int) | |
| scale_helper (scale markers only) | comma-separated string, representing note classes from C through to B, with '0' for in scale and '1' for out of scale. E.g. C# Major (Ionian) would have scale_helper '1,0,1,0,1,0,0,1,0,1,0,0' | |
| Score | ||
| Use the global variable 'score' to access these functions: | ||
| PPQ | ticks per quarter note (read-only) | |
| tsnum | current project time signature numerator (read-only) | |
| tsden | current project time signature denominator (read-only) | |
| clear([all]) | remove notes and markers. Specify "True" to clear all, instead of just selected. | |
| clearNotes([all]) | remove notes. Specify "True" to clear all, instead of just selected. | |
| clearMarkers([all]) | remove markers. Specify "True" to clear all, instead of just selected. | |
| noteCount | nr of notes (read-only) | |
| addNote(note) | add new note | |
| getNote(index) | get note | |
| deleteNote(index) | delete the indexed note | |
| markerCount | nr of markers (read-only) | |
| addMarker(marker) | add new marker | |
| getMarker(index) | get markers index | |
| deleteMarker(index) | delete the indexed marker | |
| ScriptDialog | ||
| ScriptDialog(Title, Description) | Initializes a new script dialog | |
| AddInput(aName,Value) | Adds a generic input control | |
| AddInputKnob(aName, Value, Min, Max) | Adds a knob input control with floating point value | |
| AddInputKnobInt(aName, Value, Min, Max) | Adds a knob input control with integer value | |
| AddInputCombo(aName, ValueList, Value) | Adds a combobox input control | |
| AddInputText(aName, Value) | Adds a text input control | |
| AddInputCheckbox(aName, Value) | Adds a checkbox input control with boolean value | |
| GetInputValue(aName) | Retrieve the current value of the input with the specified name | |
| Execute | how the dialog. Returns TRUE if the user pressed OK, FALSE if the dialog was cancelled | |
| TUtils | ||
| ProgressMsg(Msg,Pos,Total) | Shows a progress message | |
| ShowMessage(Msg) | Shows a message in a dialog box | |
| log(Msg) | Writes a string to the FL Studio debug log tab. | |
| Utility functions | ||
| Use global variable "Utils" to access these functions: | ||
| Utils.ShowMessage('Hello world') | Displays a message as entered. E,g, Hello world. |