FreePiano

Advanced virtual MIDI keyboard.

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:

  1. It only contains commands, no operators or flow control, so It’s easy.
  2. 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.
  3. 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:

Key settings dialog

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>
Channels are from `In_0` to `In_15`, you can also just write a number. Note names is from C0 to C10. Velocity here is optional, default value is 127. this velocity is scaled by channel velocity. Demo: play 4 notes when hit a key:
Keydown  A   Note    In_0    C4
Keydown  A   Note    In_0    E4
Keydown  A   Note    In_0    G4
Keydown  A   Note    In_0    C5
Demo: play different note everytime when this key is pressed:
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
Copy scripts above and paste it into a key setting window, hit that key and you will hear the result. ## Parameter set commands There are two different kinds of parameter, Global and Channel. Syntax of setting a global parameter:
Keydown  A   <parameter_name>    <operation>    <value>
Syntax of setting a channel parameter:
Keydown  A   <parameter_name>    <channel>    <operation>    <value>
List of parameters:
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)

When setting parameter, you can change value in different ways:
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

### Learn by examples: Sometimes, we have not enough octaves, so we want to change octave during play. but ether increase or decrease value will cycle through value -1, 0, 1, how can we just change between 0 and 1? try script below:
Keydown  A   Octave    In_1    Flip    1
Label    A   RO
Setting octave of input channel 1 to 0 or 1, and try previous binding. I want increase the transpose by a semitone:
Keydown   A   Transpose   In_1  Inc   1
Keyup     A   Transpose   In_1  Dec   1
Label     A   #R
What if I just want to 'transpose next note'? check this out:
Keydown   A   Transpose   In_1  Inc       1
Keydown   A   Transpose   In_1  SyncDec   1
Label     A   #R
How it works? When the key is pressed, transpose of input channel 1 is increased by 1, at the same time, the second line is executed, but in sync state. A sync command will eb executed `after` next key pressed. So the transpose will decrease by 1 after next note. ## Other commands
Command Description
Play

Starts playing

Record

Starts recording

Stop

Stops playing or recording

MIDI

Send a raw MIDI message

Menu

Popup main menu

The MIDI command can output a raw MIDI event, at most 4 bytes can be send now, for example:
Keydown  A   MIDI    90 40 7f
## Sequence and SequenceGoto command. Sience Freepiano 2.2, a new Sequence mode is implemented. when a key first presses, commands before a 'Sequence' command is executed, when that key pressed again, other commands until next 'Sequence' command is executed. Syntax of 'Sequence' command:
Sequence  A   <Label>
A 'Label' is a number greater than 0, 0 means the very beginning of this sequence. Syntax of 'SequenceGoto' command:
Keydown  A   SequenceGoto <Label>  <Key>
This command can control a key's current sequence position, by jumping to a matched label. If no label is matched, this command does nothing. If the label is 0, Jumping to the beginning. When the key parameter is missing, controlling current pressed key. A Key can be 'AllKeys', means control all keys at the same time, most frequently used is reset all key sequences to the beginning.