按键脚本

在FreePiano内部，所有的操作都是以“命令”的形式存在的，而命令的组合是非常多变的。从1.8版开始，命令也支持多国语言了，这样命令就更容易被理解了。

提到脚本，大部分可能都会马上产生恐惧。确实，作为命令，只要写错一点，计算机就无法正确地执行。但是FreePiano的脚本与其他脚本不同：

FreePiano的脚本最多只能当成命令，它没有复杂的逻辑控制，也没有各种各样的公式和符号，所以是很容易学习的。
FreePiano的脚本只是用来输入的，在FreePiano内部并不保存脚本。如果您的某一行脚本输入错误了，那么这行将不能被识别，就跟没输入一样。其他的地方完全不受影响。
FreePiano会自动帮你转换脚本的格式，所以有没有写对很容易看出来。

所以不用害怕，让我们来学习FreePiano的高级配置命令吧！

新的命令编辑方式

从FreePiano 1.7开始，脚本可以在按键配置的界面上直接修改了，所以现在已经不建议再直接编辑FreePiano的map文件，除非你有大量的批处理操作，直接修改文件能方便一些。

之前在键盘布局的介绍中我们已经看到过命令的编辑界面了，下面我们再看一下这个界面：

按键定义对话框

手动编写命令时，我们只需要关心界面中间部分的脚本区域就可以了，如果自动应用这个选项被选中，那么编辑完成后您甚至不需要点应用按钮来让脚本生效。

如果不小新修改了脚本，你可以点刷新按钮，这样就会放弃当前的修改，恢复之前按键对应的脚本。

命令绑定方式

我们编写的脚本是绑定在按键上，在键盘按下或松开时执行。FreePiano中定义了以下绑定方式：

英文命令	中文命令	说明
Keydown	键盘按下	命令会在键盘按下时执行。
Keyup	键盘松开	后面跟随的命令将被在键盘松开时执行。
Label	标签	定义按键上显示的文字，如果没有定义标签，FreePiano会帮你根据内容自动生成一个。
Color	颜色	定义按键按下时的颜色，如果没有定义，将使用配置中的自动颜色值。
Sequence	序列	指定按键命令的序列分割，每次按键只会触发当前序列的命令，然后自动切换到下一个序列。

按键绑定命令的格式为：

方式  按键名称  脚本

在按键命令绑定界面上编写脚本时，FreePiano会自动帮你修改按键名称

为了方便脚本编写，在FreePiano的按键绑定窗口上修改脚本时，FreePiano会强制帮你把命令绑定到当前选中的按键上，所以在编写时，可以随便写一个按键名称就好。 </div> ## 音符命令下面的格式说明中，我们统一将命令绑定在`键盘按下 A`上，前面已经说过FreePiano会帮你自动修改名称，所以这些命令拷贝到任何按键上都可以直接使用。音符命令格式如下：

键盘按下  A   音符    <通道>    <音符名称>    <可选的力度>

通道可以是`输入_0`到`输入_15`, 您也可以直接写一个数字，FreePiano会帮你自动转换。音符的名称这里要用统一的音名表示。这里还可以填写一个力度，最小0，最大255。如果填写127或者不填，FreePiano会使用100%的力度。这个力度值成为“独立力度”，它和通道的力度是成比例关系的，换算公式为：

最终力度 = 独立力度 * 通道力度 / 127

换算过后，大于127的力度会认为是最大力度，而小于5的力度会被认为是按键抬起。示范：一键多音脚本

键盘按下  A   音符    输入_0    C4
键盘按下  A   音符    输入_0    E4
键盘按下  A   音符    输入_0    G4
键盘按下  A   音符    输入_0    C5

将上面的命令拷贝到任何一个按键的脚本里，然后按下这个按键就可以听到效果。示范：音符序列脚本

键盘按下  A   音符    输入_0    C4
序列      A
键盘按下  A   音符    输入_0    E4
序列      A
键盘按下  A   音符    输入_0    G4
序列      A
键盘按下  A   音符    输入_0    C5

## 参数修改命令参数修改有2种，一种是全局参数，比如曲调，另外一种是通道参数，比如力度。全局命令格式：

键盘按下  A   <参数名称>    <参数操作>    <值>

通道参数命令的格式是：

键盘按下  A   <参数名称>    <通道>   <参数操作>    <值>

可修改的参数有：

英文名称	中文名称	类型	说明
KeySignature	曲调	全局	当前的曲调，值的范围时-4到7
Group	分组	全局	当前的键盘分组
Volume	总音量	全局	FreePiano的输出音量
Velocity	力度	通道	通道的力度
FollowKey	跟随曲调	通道	当前通道是否跟随曲调
Transpose	移位	通道	以一个半音为单位的音符移位
FollowKey	八度	通道	以1个八度（12个半音）为单位的移位
Channel	通道	通道	定义一个输入通道所对应的输出通道
Pitch	弯音	通道	类似弯音轮的效果，值可以从-64到64，代表降低2个半音到升高2个半音
Program	乐器	通道	选择通道所使用的乐器
BankMSB	乐器组1	通道	选择乐器组
BankLSB	乐器组2	通道	选择乐器组
Sustain	延音	通道	延音踏板
Modulation	颤音	通道	颤音轮
ChannelVolume	通道音量	通道	单独控制每个通道的音量，需要音源支持
ChannelPan	通道声像	通道	单独控制每个通道的声像，需要音源支持

用脚本修改参数时，可以指定对于参数的操作，这是FreePiano的命令有点像脚本的地方，因为使用参数操作，可以实现很多复杂的效果。 FreePiano提供了以下的参数操作： </tbody> </table> ### 下面我们以一些实例来说明参数设置命令的用法：在演奏歌曲时，八度会不够用，所以我们想修改右手八度，但是默认的增加或减少都是在 -1， 0， 1 这三个值之间变换，如果只想要在2个值之间切换是否有方法呢？我们来一下下面的脚本：

键盘按下  A   八度    输入_1    反转    1
标签      A   RO

将当前右手八度设置成0或者1，然后按下刚才设置的键，看看有没有效果？在演奏时，会经常遇到需要弹奏黑键（半音）的情况，如果您不弹和弦，那么可以用一个键来搞定所有的半音，我们需要的临时升高或者降低右手的音高：

键盘按下  A   移位    输入_1    增加    1
键盘松开  A   移位    输入_1    减少    1
标签      A   #R

试一下？如果觉得操作还不是很方便，我想`升高下一个音符`该这么办？试试这样写：

键盘按下  A   移位    输入_1    增加      1
键盘按下  A   移位    输入_1    同步减少  1
标签      A   #R

是不是觉得上面的脚本需要解释一下了？它时这么工作的呢？首先，在按键按下了以后，输入_1（也就是右手）的移位被增加了1，这样所有的音符都是原先音符的升半音，然后，同样是在键盘按下A时，右手的移位在同步减少1，由于同步操作要等待下一个按键按下`之后`才会执行，所以在下一个音符弹奏时还维持这升半音的状态，在演奏了以后才会再降回来。 ## 其他命令除了上面的2大类命令以外， FreePiano还有几个独立的命令：

英文	中文	说明
Set	设置为	新值 = 值
Inc	增加	新值 = 当前值 + 值
Dec	减少	新值 = 当前值 - 值
Flip	反转	新值 = 值 - 当前值
Press	脉冲	新值 = 值; 20毫秒以后，新值 = 当前值
Release	释放	新值 = 值; 任意一个按键抬起前，新值 = 当前值
Set10	设置十位	新值的十位 = 值的十位
Set1	设置个位	新值的个位 = 值的个位
SyncSet	同步设置	同步设置会再下一次按键之后才生效
SyncInc	同步增加	同步设置会再下一次按键之后才生效
SyncDec	同步减少	同步设置会再下一次按键之后才生效
SyncFlip	同步反转	同步设置会再下一次按键之后才生效
SyncPress	同步脉冲	同步设置会再下一次按键之后才生效

英文命令	中文命令	说明
Play	播放	播放乐曲
Record	录制	开始录音
Stop	停止	停止播放或录音
MIDI	MIDI	发送原始的MIDI消息。
Menu	菜单	可以用按键弹出主菜单。

上面的命令中，需要讲解下的是MIDI指令，它可以控制FreePiano发送原始的，不经过任何修改的MIDI消息。目前一次只能最多发送4个字节，MIDI消息是用16进制表示的，比如：

键盘按下  A   MIDI    90 40 7f

## 序列和序列跳转命令 Freepiano 2.2 引入了按键序列的功能，用于完成更为复杂功能。序列的基本概念就是在一个按键绑定时，将命令分成若干个“序列”，每次按键按下，执行一个序列，然后自动切换到下一个，完成后循环。序列命令格式：

序列  A   <标签>

在序列命令上，可以指定一个标签，这个标签是一个非0的数字，标签0表示的是序列开始。序列跳转命令格式：

键盘按下  A   序列跳转  <标签>  <按键>

这条命令可以控制某个按键的序列跳转到一个匹配的标签上，如果没有匹配的标签，则没有任何影响。如果标签是0，则会跳转到序列的开始。如果没有填写按键，则会控制当前按下的键的序列跳转。按键可以是“全部按键”，表示控制同时控制所有按键的序列跳转。常用的序列重置命令其实就是控制所有按键跳转到0序列。

Back