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 21\System\Config\Piano roll scripts. Default Scripts installed at installation.
    • macOS Installation - ... /Applications/FL Studio 21/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.