Contents

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:

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.

Back