Scripts
In FreePiano, every action is a ‘command’, we call a sequence of commands as a ‘script’. the FreePiano script is different from a scripting language:
- It only contains commands, no operators or flow control, so It’s easy.
- Scripts are only for display, Freepiano store binray commands internally, so a mistake type in script will only curse that line invalid, the entire script still works.
- FreePiano will format script for you, so if something goes wrong, that line will be removed.
OK, let’s start scripting now.
New script editing method
Since FreePiano 1.7, Scripts can be modified directly on key setting window, so no need to deal with the entire .map file now.
Let’s take a look at script editing window again:
When scripting, we only care about the script area, with Auto Apply
checked, you don’t event need to click on Apply
button after modify.
If you typed something by mistake, you can click on Refresh
button, changes will be discard.
Binding a script to a key
You can trigger a command when a key is being pressed or released. there are 4 top level commands:
Command | Description |
Keydown | Scripts will be executed when the key is pressed. |
Keyup | Scripts will be executed when the key is released. |
Label | Text displays on the key. |
Color | Highlight color when the key is pressed. |
Sequence | Split key command to sequences, when that key is pressed, only one piece of commands is executed, then switch to next piece. |
The syntax of a bind:
command <keyname> <commands>
When writing scripts in freepiano, key names is force changed to current selecte key
To make copy and paste easier, key names is ignored in key bind window. so when you writing script in that window, you can just type any key name.
</div>
## Note commands
From here, we write script on bind `Keydown A`, so it works by copy commands directly to FreePiano key setting window.
Syntax of a note command:
Keydown A Note <channel> <note_name> <optional_velocity>
Keydown A Note In_0 C4
Keydown A Note In_0 E4
Keydown A Note In_0 G4
Keydown A Note In_0 C5
Keydown A Note In_0 C4
Sequence A
Keydown A Note In_0 E4
Sequence A
Keydown A Note In_0 G4
Sequence A
Keydown A Note In_0 C5
Keydown A <parameter_name> <operation> <value>
Keydown A <parameter_name> <channel> <operation> <value>
Name | Kind | Description |
KeySignature | Global | Current key signature, from -4 to 7 |
Group | Global | Current group |
Volume | Global | Master volume of freepiano. |
Velocity | Channel | Velocity of notes on channel |
FollowKey | Channel | Whether transpose notes by key signature |
Transpose | Channel | Transpose notes on currernt channel |
FollowKey | Channel | Transpose notes by octaves(12 seminotes) |
Channel | Channel | Output MIDI channel |
Pitch | Channel | Pitch on current channel, from -64 to 64, means -2 seminotes to 2 seminotes |
Program | Channel | Change voice on current output channel |
BankMSB | Channel | Bank select MSB (Controller 0) |
BankLSB | Channel | Bank select LSB (Controller 32) |
Sustain | Channel | Sustain pedal (Controller 64) |
Modulation | Channel | Modulation (Controller 1) |
Operation | Description |
Set | new_value = value |
Inc | new_value = current_value + value |
Dec | new_value = current_value - value |
Flip | new_value = value - current_value |
Press | new_value = value; wait 20ms; new_value = current_value |
Release | new_value = value; before any key is released, new_value = current_value |
Set10 | new_value[digit 10] = value[digit 10] |
Set1 | new_value[digit 1] = value[digit 1] |
SyncSet | Sync value will be changed AFTER next key is pressed |
SyncInc | Sync value will be changed AFTER next key is pressed |
SyncDec | Sync value will be changed AFTER next key is pressed |
SyncFlip | Sync value will be changed AFTER next key is pressed |
SyncPress | Sync value will be changed AFTER next key is pressed |
Keydown A Octave In_1 Flip 1
Label A RO
Keydown A Transpose In_1 Inc 1
Keyup A Transpose In_1 Dec 1
Label A #R
Keydown A Transpose In_1 Inc 1
Keydown A Transpose In_1 SyncDec 1
Label A #R
Command | Description |
Play | Starts playing |
Record | Starts recording |
Stop | Stops playing or recording |
MIDI | Send a raw MIDI message |
Menu | Popup main menu |
Keydown A MIDI 90 40 7f
Sequence A <Label>
Keydown A SequenceGoto <Label> <Key>