杰理AD14N_AD15N_MIDI应用说明文档

📎 原始文档：https://www.kdocs.cn/l/cuLhWpMMqIah

杰理AD14N AD15N MIDI应用介绍

珠海市杰理科技股份有限公司

Zhuhai Jieli Technologyco.,LTD

版权所有，未经许可，禁止外传
2022年7月7 日
目录
第一章 MIDI应用..............................................................................................................................5
1.1 MIDI功能介绍.......................................................................................................................... 5
1.2 MIDI乐谱解码.......................................................................................................................... 6
1.2.1 MIDI乐谱解码初始化与CMD 配置介绍.......................................................................... 6
1.2.1.1 MIDI乐谱解码运行步骤....................................................................................................................... 6
1.2.1.2 初始化的配置......................................................................................................................................... 7
1.2.1.3 MIDI乐谱解码的CMD配置................................................................................................................ 8
1.2.1.4 MIDI在运行中动态配置功能示例.......................................................................................................9
1.2.2 解码方式（CMD_MIDI_ CTRL_MODE）....................................................................... 10
1.2.3 ONE KEYONE NOTE模式............................................................................................... 11
1.2.3.1 打开OKON模式................................................................................................................................. 11
1.2.3.2 OKON 的工作模式（CMD_ MIDI_ OKON_ MODE）..................................................................... 11
1.2.3.3 设置主旋律........................................................................................................................................... 13
1.2.3.4 快速打断功能....................................................................................................................................... 13
1.2.3.5 中途切换OKON模式......................................................................................................................... 13
1.2.4 主旋律乐器的选择（CMD_MIDI_SET_ CHN_PROG）.................................................. 14
1.2.5 乐谱中添加标记(MARK)功能.......................................................................................... 15
1.2.5.1 MARK 回调函数................................................................................................................................... 15
1.2.5.2 两个MARK之间循环播放................................................................................................................ 15
1.2.6 其他回调功能...................................................................................................................16
1.2.6.1 主旋律的音符回调功能...................................................................................................................... 16
1.2.6.2 主旋律的音符结束回调功能.............................................................................................................. 16
1.2.6.3 节拍(BEAT)的回调.............................................................................................................................. 17
1.2.6.4 小节的回调........................................................................................................................................... 17
1.2.6.5 清狗的回调........................................................................................................................................... 17
1.2.7 外部音量功能（CMD_MIDI_SET_EX_ VOL）................................................................ 17
1.2.8 移半音功能（CMD_MIDI_SET_SEMITONE）............................................................... 18
1.2.9 更改节奏和衰减（CMD_MIDI_ CTRL_ TEMPO）.......................................................... 18
1.2.10 小节回退功能（CMD_MIDI_SEEK_BACK_N）...........................................................19
1.2.11 MIDI解码函数接口........................................................................................................ 20
1.2.11.1 函数v。id midi_ dec。de_ init(v。id) .....................................................................................................20
1.2.11.2 函数int music_midi_ ctrl_ c。nfig(music_play_。bj *hdl, u32 cmd, v。id *parm) ........................... 20
1.2.11.3 函数v。id midi_。k。n_m。de_ set(music_play_。bj *music_。bj, u8 m。de) ..................................... 21
1.2.11.4 函数v。id midi_。k。n_ g。。n(music_play_。bj *music_。bj) ..............................................................21
1.2.11.5 函数v。id midi_ init_ inf。(MIDI_ INIT _ STRUCT *init_ inf。) ..........................................................21
1.3 MIDI琴.................................................................................................................................... 22
1.3.1 MIDI琴初始化..................................................................................................................22
1.3.1.1 初始化过程........................................................................................................................................... 22
1.3.1.2 注意要点............................................................................................................................................... 22
1.3.2 MIDI琴音符回调功能...................................................................................................... 23
1.3.3 MIDI琴函数接口.............................................................................................................. 23
1.3.3.1 函数v。id midi_ ctrl_ dec。de_ init(v。id) ............................................................................................... 23
1.3.3.2 函数int music_midi_ ctrl_ set_pr。g(music_play_。bj *hdl, u8 pr。g, u8 chn) ................................... 23
1.3.3.3 函数int music_midi_ ctrl_pitch_bend(music_play_。bj *hdl, u16 pitch_val, u8 chn) .....................23
1.3.3.4 函数int music_midi_ ctrl_ c。nfig(music_play_。bj *hdl, u32 cmd, v。id *parm) ............................. 24
1.3.3.5 函数int music_midi_ ctrl_n。te_。n(music_play_。bj *hdl, u8 nkey, u8 nvel, u8 chn) .....................24
1.3.3.6 函数int music_midi_ ctrl_n。te_。ff(music_play_。bj *hdl, u8 nkey, u8 chn) ...................................25
1.3.3.7 函数int music_midi_ ctrl_vel_ vibrate(music_play_。bj *hdl, u8 nkey, u8 vel_ step, u8 vel_rate, u8
chn) ...................................................................................................................................................................... 25
1.3.3.8 函数int midi_ ctrl_play_ end_ deal(music_play_。bj *hdl) ................................................................. 25
1.3.3.9 函数v。id midi_ ctrl_ callback_ init(music_play_。bj *hdl, u32(*mel。dy_ callback)(v。id *, u8, u8), u32(*mel。dy_ st。p_ callback)(v。id *, u8)) ........................................................................................................ 26
第二章 MIDI工具............................................................................................................................27
2.1 MIDI工具主界面...................................................................................................................27
2. 1. 1 MIDI版本说明............................................................................................................... 27
2. 1.2 MIDI工具简介............................................................................................................... 27
2. 1.3 主界面-乐器种类............................................................................................................28
2. 1.4 主界面-选中乐器............................................................................................................28
2.2 MIDI转换.............................................................................................................................. 29
2.2. 1 选择需要转换的MIDI文件...........................................................................................29
2.2.2 输出目录........................................................................................................................ 30
2.2.3 转换................................................................................................................................ 30
2.2.4 导出库............................................................................................................................ 31
2.3 MIDI音色库压缩...................................................................................................................32
2.3. 1 压缩流程........................................................................................................................ 32
2.3.2 压缩信息查询.................................................................................................................34
2.3.3 还原压缩配置内容......................................................................................................... 36
2.4 MIDI导入SF2音色库...........................................................................................................37
2.4. 1 添加或删除SF2 文件.....................................................................................................37
2.4.2 SF2 音色库信息查询......................................................................................................38
2.4.3 还原SF2 音色库内容.....................................................................................................38
2.5 MIDI WAV编辑.................................................................................................................... 39
2.5. 1 WAV编辑界面简介........................................................................................................ 39
2.5.2 波形编辑........................................................................................................................ 40
2.5.3 参数配置........................................................................................................................ 41
2.5.4 包络编辑........................................................................................................................ 43
2.5.5 波形保存........................................................................................................................ 43
2.5.6 WAV编辑信息查询........................................................................................................ 44
2.5.7 还原WAV编辑内容....................................................................................................... 44
2.6 按键与乐器表.........................................................................................................................45
2.6. 1 按键表............................................................................................................................ 45
2.6.2 乐器表............................................................................................................................ 45

MIDI应用

http://www.zh.jieli.com /

第一章 MIDI应用

1.1 MIDI功能介绍

MIDI全称是乐器数字接口(Musical Instrument Digital Interface)，是20 世纪80 年代初为解决电声乐器之间的通信问题而提出的，编曲界最广泛的音乐标准格式。
MIDI用音符的数字控制信号来记录音乐。一首完整的MIDI音乐只有几十KB大，而
能包含数十条音乐轨道。其传输的不是声音信号，而是音符、控制参数等指令,它指示MIDI
设备要做什么，怎么做，如演奏哪个音符、多大音量等。
SH54 / 55支持MIDI乐谱解码以及MIDI琴两种应用。其中： MIDI乐谱解码有4种方式：
1 正常解码模式
2 OKON（ONE KEY ONE NOTE）模式
3 只推消息不出声模式
4 外部音源模式
MIDI琴有l种方式：

1 琴键解码模式

1.2 MIDI乐谱解码

MIDI乐谱解码的过程为，初始化后，打开MIDI乐谱文件获取到音符，再访问音色库找到对应的乐器音色进行解码，不断获取音符并重复该过程直到乐谱结束。本节讲介绍MIDI 解码的初始化、MIDI解码的功能配置以及注意点。

1.2. 1 MIDI乐谱解码初始化与CMD配置介绍

1.2.1.1 MIDI乐谱解码运行步骤

在系统初始化时会调用midi_decode_init(void)函数记录MIDI音色库文件的信息； midi乐谱解码MAX_DEC_PLAYER_CNT 同时发声的key数默认为8。
调用decoder_init(void)初始化解码器；
打开midi乐谱文件并调用函数decoder_io(void *pfile, u32 dec_ctl, dp_buff *dbuff, u8 loop)进行解码，该函数dec_ctl参数传入BIT_MIDI；
midi解码初始化中会调用函数void midi_decode_api(void *p_file, void **ppdec, void *p_dp_buf)，初始化MIDI解码信息，比其他解码格式多了配置参数这一步！
配置参数会调用函数midi_init_info(MIDI_INIT_STRUCT *init_info)，进行MIDI功能的初始化，包括主旋律选择、外部音量设置、所有回调函数的注册等，最后使能对应的控制使能位。
通过CMD_INIT_CONFIG命令将midi初始化的信息传入解码器中，到此midi功能初始化完成。
解码器启动，dac开始发声；

1.2.1.2 初始化的配置

MIDI解码功能的初始化在函数void midi_init_info(MIDI_INIT_STRUCT *init_info)中进行。该函数中会配置MIDI_INIT_STRUCT结构体内包含的成员。配置功能结构体后，还需要配置功能对应的控制使能参数，sdk 中默认的MIDI功能配置如图所示：
配置完成后，通过CMD_INIT_CONFIG命令将配置完成的MIDI_INIT_STRUCT 结构体传给解码器，如下图所示：

1.2.1.3 MIDI乐谱解码的CMD配置

1) CMD命令配置说明

MIDI乐谱解码可以通过CMD实时配置功能。首先配置CMD对应的功能结构体，再调用函数int music_midi_ctrl_config(music_play_obj *hdl, u32 cmd, void *parm)，函数参数分别传入midi解码句柄、CMD命令以及配置好的功能结构体指针即可实现，MIDI 的CMD

。

2) 控制使能参数说明（CMD_MIDI_SET_SWITCH命令）

部分功能配置结束后，还需要置上相应的使能位才能生效（初始化中已经置上的使能位不需要再次使能）。使能参数是一个u32变量，每一bit代表一个功能，该bit置1/置0会打开/关闭对应的功能。
MIDI功能使能的方式有两种，一种是在MIDI初始化中配置MIDI_INIT_STRUCT结构体的switch_info成员，并调用CMD_INIT_CONFIG命令配置初始化后生效。
另一种时通过调用上一节函数music_midi_ctrl_config()，分别传入MIDI解码句柄、 CMD_MIDI_SET_SWITCH命令以及配置好的使能参数。注意，该命令传入的使能参数是所
有功能的使能位，单独操作某一使能位时不能影响到其他bit，否则会影响到其他功能。可以沿用MIDI初始化的全局变量init_info->switch_info来管理使能位。

1.2.1.4 MIDI在运行中动态配置功能示例

本小节以在MIDI运行中配置主旋律乐器为例，其他功能配置可参照该例程；
l) 首先查看MIDI支持的CMD命令CMD_MIDI_SET_CHN_PROG，并找到它对应的结构体参数 MIDI_PROG_CTRL_STRUCT，以及对应的使能位 SET_PROG_ENABLE（无使能位则忽略）。
2) 根据需要配置结构体，并通过music_midi_dec_config()函数将CMD和配置好的结构体指针传给解码器；
3) 若该功能有使能位且MIDI初始化中未使能，则需要使能对应的功能。首先获取全局变量init_info->switch_info 的值得到所有使能配置，再置上对应的使能位，通过 CMD_MIDI_SET_SWITCH命令将使能参数传给解码器，该功能配置就会生效。

1.2.2 解码方式（CMD_MIDI_CTRL_MODE）

MIDI解码方式共有4种，分别是：

1 正常解码模式

该模式即正常解码MIDI乐谱文件。

2 OKON（ONE KEY ONE NOTE）模式

该模式即用户通过按键驱动MIDI文件解码，通过调用函数实现按一次按键播放一段音符。

3 只推消息不出声模式

该模式暂不支持。

4 外部音源替换模式

该消息主要应用为使用录音音源替换乐谱，录音文件需要经过处理。
其各自对应参数如下：
MIDI初始化中配置init_info->mode_info 即可选择默认的解码方式，如下图所示， sdk 默认选择了OKON模式。
初始化配置之后调用midi_okon_mode_set(music_play_obj *music_obj, u8 mode)函数，可以修改MIDI 的解码方式；详情请看《3 .3.3.函数void midi_okon_mode_set(music_play_obj *music_obj, u8 mode)》说明。

1.2.3 ONE KEY ONE NOTE模式

1.2.3.1 打开OKON模式

调用midi_okon_mode_set()，传入CMD_MIDI_CTRL_MODE_ 1即可切换到OKON模式。使用OKON模式需要置上MELODY_PLAY_ENABLE使能位。

1.2.3.2 OKON 的工作模式（CMD_MIDI_OKON_MODE）

OKON 的工作模式共有三种，分别是：

1 主旋律 OKON 副旋律正常播放；

2 主副旋律一起OKON；

3 只有主旋律OKON副旋律不发声；

其各自对应的参数如下：
其中，只有主旋律OKON副旋律不发声的工作模式，在解码过程中有可能长时间占用 CPU，所以需要在wdt_clear_trigger()函数中调用清狗函数，否则有可能会导致系统复位！
OKON按键按下后可以回调的音符，该功能需要置上MELODY_ENABLE使能位。回调的方式共有两种，分别是：

1 回调当前音符

2 回调下一个音符位

其各自对应参数如下：
MIDI初始化中配置init_info->okon_info即可选择默认的OKON工作模式，如下图所示， sdk默认选择了主旋律 OKON 副旋律正常播放和回调当前音符。

1.2.3.3 设置主旋律

OKON 模式需要确定主旋律来播放音符。初始化时，系统会判断 const 变量 MAINTRACK_USE_CHN 的值，值为0通过轨道(track)号选择主旋律，值为 1通过通道(channal)号选择主旋律。修改init_info->mainTrack_info.chn的值可以在初始化中确定主旋律，有效范围是0~ 15。若让系统自动选择第一个音符所在轨道或通道为主旋律，则选择 17。Sdk
中的默认配置如下：
注意，通过轨道(track)号选择主旋律时，mainTrack_info.chn 的值与乐谱制作软件的轨道号一致；通过通道(channal)号选择主旋律时，mainTrack_info.chn 的值需要比乐谱制作软件的通道号小 1，即mainTrack_info.chn 的值为0时，对应乐谱中的 1号通道作为主旋律；
MIDI乐谱制作时，一个轨道只能对应一个通道，但是一个通道可以对应多个轨道；例如音轨 1、音轨2对应通道 1，音轨3对应通道2，那么以轨道(track)号选择主旋律时， mainTrack_info.chn 设置为 1，则音轨 1 为主旋律；以通道(channal)号选择主旋律时， mainTrack_info.chn设置为0，则通道 1对应的音轨 1和音轨2一起成为主旋律。

1.2.3.4 快速打断功能

在只有主旋律OKON副旋律不发声的模式下，可以置上MAIN_INTERRUPT_ENABLE 使能位开启快速打断功能。上一个音符未结束而下一个音符到来时，未开启快速打断，两个音符会叠加在一起直至上一个音符结束；开启快速打断后，会加快上一个音符的衰减，使其迅速消失减少叠加时间。

1.2.3.5 中途切换OKON模式

中途切换MIDI模式可以调用函数midi_okon_mode_set()，并将mode设置为OKON模式(CMD_MIDI_CTRL_MODE_ 1)。 OKON模式下需要调用midi_okon_goon()函数启动下一个音符。sdk 中应用示如图所示：

1.2.4 主旋律乐器的选择（CMD_MIDI_SET_CHN_PROG）

MIDI可以强制指定主旋律的乐器，可以做到实时变更主旋律的乐器以及相关音量配置，使用该功能需要置上SET_PROG_ENABLE使能位，没有使能则使用MIDI乐谱上默认的乐器。其功能结构体MIDI_PROG_CTRL_STRUCT包括：
1
prog
乐器号，与我司midi制作工具中的乐器号对应；
2
replace_mode
替换模式，选0是只更变主旋律的乐器，选 1是更变所有旋律的乐器。暂不支持单独更变
副旋律的乐器；
3
ex_vol
音量配置，该值会将音量改变为原来的(ex_vol / 1024)倍；值为 1024则不改变音量；
Sdk 中的默认配置如下：
该功能可以在 MIDI 运行中动态设置，调用函数music_midi_ctrl_config()，并将 CMD_MIDI_SET_CHN_PROG命令和配置好的结构体参数传入；置上SET_PROG_ENABLE 使能位即可。详情请看《2 .1.3MIDI乐谱解码的CMD配置》说明。

1.2.5 乐谱中添加标记(MARK)功能

MIDI解码能够识别到MIDI乐谱文件上标准的MARK标记。遇到MARK标记时支持

回调函数，而且支持两个MARK之间进行循环播放。

1.2.5.1 MARK 回调函数

初始化中MARK 回调功能，并置上MARK_ENABLE使能位，解码中读取到乐谱中的 MARK标记后会发生回调。回调函数u32 midi_mark_trigger(void *priv, u8 *val, u8 len)的参数 val是指向MARK名称的指针，len是名称的长度。Sdk默认配置如下：

1.2.5.2 两个MARK之间循环播放

1）MARK 标记还可以实现两个 MARK 之间循环解码功能，置上 MARK_LOOP_ENABLE使能位后，遇到两个MARK后会在它们之间循环播放，如下图：
2）在循环播放中取消MARK_LOOP_ENABLE使能会跳出循环，同时丢失两个MARK 信息，如下图：
3）MARK_A和MARK_B 中间循环时取消使能后，在解码到MARK_B之前再次置上 MARK_LOOP_ENABLE使能位后，会重复（1）的过程，遇到两个MARK后又会开始循环，取消使能到再次使能之间需要让解码器run至少2~ 3次，在主循环中调用一个 10ms延时即可，如下图：

1.2.6 其他回调功能

1.2.6.1 主旋律的音符回调功能

置上MELODY_ENABLE使能位，解码到音符会回调：
u32 midi_melody_trigger(void *priv, u8 key, u8 vel)函数，其参数priv是私有参数，key是音符，key为255表示是静音回调，vel是力度。

1.2.6.2 主旋律的音符结束回调功能

置上MELODY_STOP_ENABLE使能位，音符解码结束后会回调：
u32 midi_melody_stop_trigger(void *priv, u8 key)函数，其参数priv是私有参数，key是音符。

1.2.6.3 节拍(BEAT)的回调

置上BEAT_TRIG_ENABLE使能位，节拍来时会回调：
u32 midi_beat_trigger(void *priv, u8 val1, u8 val2)函数，其中参数priv是私有参数，val1 是一节多少拍，vel是每拍多少分音符。

1.2.6.4 小节的回调

置上TIM_DIV_ENABLE使能位，小节开始会回调函数： u32 midi_timeDiv_trigger(void *priv)函数，priv是私有参数。

1.2.6.5 清狗的回调

清狗回调在初始化中注册即可，只有主旋OKON副旋不发声的OKON工作模式会使用该回调，详情请看《2 .3.2OKON 的工作模式》说明。

1.2.7 外部音量功能（CMD_MIDI_SET_EX_VOL）

MIDI 解码能够实现每个通道/轨道单独调节音量的功能，该功能需要置上 EX_VOL_ENABLE使能位。其结构体参数EX_CH_VOL_PARM包括：

1 cc_vol [CTRL_CHANNEL_NUM]

16个通道或者轨道的音量大小，默认值4096表示原始音量；修改的是通道或者轨道音量由ex_vol_use_chn决定；

2 ex_vol_use_chn

音量通道选择， 0表示cc_vol修改的是轨道音量， 1表示cc_vol修改的是通道音量；
Sdk默认配置如下：
该功能可以在MIDI运行中动态设置，运行中想要单独关闭某一通道/轨道的声音，可以将该通道 / 轨道音量设为 0。调用函数 music_midi_ctrl_config()，并将 CMD_MIDI_SET_EX_VOL命令和配置好的结构体参数传入；置上EX_CH_VOL_PARM使能位即可。详情请看《2 .1.3MIDI乐谱解码的CMD配置》说明。

1.2.8 移半音功能（CMD_MIDI_SET_SEMITONE）

MIDI解码能够实现每个通道单独偏移n个半音，该功能需要置上SEMITONE_ENABLE 使能位。其结构体参数MIDI_SEMITONE_CTRL_STRUCT如下：

1 Key_diff[CTRL_CHANNEL_NUM]

每个通道移动多少半音的配置；
SDK 中默认没有对该功能进行初始化，用户可自行添加。
该功能可以在 MIDI 运行中动态设置。调用函数music_midi_ctrl_config()，并将 CMD_MIDI_SET_SEMITONE命令和配置好的结构体参数传入；置上SEMITONE_ENABLE 使能位即可。详情请看《2 .1.3MIDI乐谱解码的CMD配置》说明。

1.2.9 更改节奏和衰减（CMD_MIDI_CTRL_TEMPO）

MIDI解码能够强制改变节奏、每个通道的衰减程度以及mute 阈值水平，其结构体参数 MIDI_PROG_CTRL_STRUCT如下：

1 tempo_val

节奏速度，默认值为 1042；数值越大，节奏越慢；

2 decay_val [CTRL_CHANNEL_NUM]

衰减参数，低 11bit有效，每个通道单独配置；数值越小，余音衰减越快；

3 mute_threshold

mute 阈值，数值越高，主旋的静音音符回调会越多，需要置上MELODY_ENABLE使能位。
Sdk 中的默认配置如下：
该功能可以在 MIDI 运行中动态设置。调用函数music_midi_ctrl_config()，并将 CMD_MIDI_CTRL_TEMPO命令和配置好的结构体参数传入即可。详情请看《2 .1.3MIDI乐谱解码的CMD配置》说明。

1.2. 10 小节回退功能（CMD_MIDI_SEEK_BACK_N）

MIDI运行中可以实现回退到之前的小节，需要在初始化中置上SAVE_DIV_ENBALE 使能位。该功能不支持连续回退小节，例如回退了8个小节后，需要再次经过8个小节才能进行下一次回退，否则可能会导致小节混乱。其结构体参数MIDI_SEEK_BACK_STRUCT 如下：

1 seek_back_n

回退的小节数，范围为 1~ 8，即最大可回退8个小节；值为 1时回退到当前小节起始位置；
该功能只能在MIDI运行时才能实现。初始化中置上SAVE_DIV_ENBALE使能位，调用函数music_midi_ctrl_config()，并将CMD_MIDI_SEEK_BACK_N命令和配置好的结构体参数传入即可。详情请看《2 .1.3MIDI乐谱解码的CMD配置》说明。

1.2. 11 MIDI解码函数接口

1.2.11.1 函数void midi_decode_init(void)

该函数实现查找midi解码的音色库并记录音色库信息，在系统初始化中调用；

1.2.11.2 函数int music_midi_ctrl_config(music_play_obj hdl, u32 cmd, void parm)

该函数实现配置midi解码的功能参数，cmd 的具体介绍请看第2节MIDI乐谱解码介绍，其中参数：

hdl：midi解码句柄；
cmd：命令，可用命令以及相应的参数结构体如下；
1 CMD_MIDI_SEEK_BACK_N，参数结构体MIDI_SEEK_BACK_STRUCT；
2 CMD_MIDI_SET_CHN_PROG，参数结构体MIDI_PROG_CTRL_STRUCT；
3 CMD_MIDI_CTRL_TEMPO，参数结构体MIDI_PLAY_CTRL_TEMPO；
4 CMD_MIDI_GOON，无参数，传NULL 即可；
5 CMD_MIDI_CTRL_MODE，参数结构体MIDI_PLAY_CTRL_MODE；
6 CMD_MIDI_SET_SWITCH，参数为所有使能位；
7 CMD_MIDI_SET_EX_VOL，参数结构体EX_CH_VOL_PARM；
8 CMD_INIT_CONFIG，参数结构体MIDI_INIT_STRUCT；
9 CMD_INIT_CONFIGS，参数结构体MIDI_CONFIG_PARM；
10 CMD_MIDI_OKON_MODE，参数结构体MIDI_OKON_MODE；
11 CMD_MIDI_SET_SEMITONE，结构体MIDI_SEMITONE_CTRL_STRUCT
parm：命令对应的参数结构体，请看cmd参数说明；
返回值：成功 0；
失败其他值；

1.2.11.3 函数void midi_okon_mode_set(music_play_obj *music_obj, u8 mode)

该函数实现配置midi解码的模式，其中参数：

music_obj：midi解码句柄；
mode：midi解码模式，可用mode如下：
1 CMD_MIDI_CTRL_MODE_0，正常解码模式；
2 CMD_MIDI_CTRL_MODE_ 1， one key one note模式；
3 CMD_MIDI_CTRL_MODE_2，只推消息不出声模式；
4 CMD_MIDI_CTRL_MODE_W2S，外部音源模式；

1.2.11.4 函数void midi_okon_goon(music_play_obj *music_obj)

该函数实现midi解码okon模式启动下一个音符，其中参数：

1. music_obj：midi解码句柄；

1.2.11.5 函数void midi_init_info(MIDI_INIT_STRUCT *init_info)

该函数实现midi解码配置初始化，会给midi解码器主动调用，其中参数：

1. init_info：midi解码初始化配置结构体，具体请参照代码中的配置信息；

1.3 MIDI琴

MIDI琴功能支持通过函数驱动midi解码。该应用依赖我司自定义的mid音色库，用户可通过我司mid工具进行转换，详情请看《JLmidi工具使用说明》。本节将介绍midi琴初始化过程和相关的接口函数。

1.3. 1 MIDI琴初始化

1.3.1.1 初始化过程

在系统初始化时会调用void midi_ctrl_decode_init(void)函数记录MIDI音色库文件的信息；midi琴MAX_CTR_PLAYER_CNT 同时发声的key数默认为 15。
调用decoder_init(void)初始化解码器；
调用decoder_io(void *pfile, u32 dec_ctl, dp_buff *dbuff, u8 loop)进行解码，该函数 dec_ctl参数传入BIT_MIDI_CTRL；
配置各通道乐器，弹奏解码。

1.3.1.2 注意要点

同时发声的最大通道数MAX_PLAYER_CNT可以在midi_ctrl_api.c 中根据需要进行设置，范围是 1~ 32，该值的大小会影响到解码buf的大小，sdk默认配置如下：

2) SDK 中MIDI琴中的通道号chn符合mid标准，一共有16个通道（0~ 15）。

其中0~ 8、10~ 15号通道可以使用0~ 127号乐器，9号通道用于 128号以上的打击乐器。如选择00-01高亮大钢琴，那么通道号可以选择0~ 8或10~ 15，乐器号写0 8+1 = 1；
如选择 16-00standard，乐器号为 168+0= 128，大于127，所以通道号只能选9，乐器号写： 16*8+0-128 = 0；

1.3.2 MIDI琴音符回调功能

midi琴运行时，弹奏音符后可回调响应函数；该功能与midi解码的主旋律音符回调一致；区别在于midi 琴中的回调配置只能在运行中通过动态配置的方式使能，可参考《l.2. l.4MIDI在运行中动态配置功能示例》以及SDK 中的说明，配置顺序如下：
l）CMD_MIDI_MELODY_TRIGGER配置音符开始的回调；
2）CMD_MIDI_STOP_MELODY_TRIGGER配置音符结束的回调；
3） CMD_MIDI_SET_SWITCH 配置回调使能， switch_enable 使能参数需要置上 MELODY_ENABLE和MELODY_STOP_ENABLE使能位；

1.3.3 MIDI琴函数接口

1.3.3.1 函数void midi_ctrl_decode_init(void)

该函数实现查找midi琴的音色库并记录音色库信息，在系统初始化中调用；

1.3.3.2 函数int music_midi_ctrl_set_prog(music_play_obj *hdl, u8 prog, u8 chn)

该函数实现查找设置midi琴的乐器，0其中参数：
l. hdl：midi琴解码句柄；
2. prog：乐器号，与midi音色库制作工具中的乐器号一致。详情请看《l.3. l.2注意事项》说明；
3. chn：发声通道，该值范围在0~ l5；
4. 返回值：成功 0；
失败其他值；

1.3.3.3 函数int music_midi_ctrl_pitch_bend(music_play_obj *hdl, u16 pitch_val, u8 chn)

该函数实现配置midi琴弯音轮参数，其中参数：
l. hdl：midi琴解码句柄；
2. pitch_val：弯音值，默认值是256，可根据该值调整；
3. chn：发声通道，该值范围在0~ l5；
4. 返回值：成功 0；
失败其他值；

1.3.3.4 函数int music_midi_ctrl_config(music_play_obj hdl, u32 cmd, void parm)

该函数实现配置midi琴的其他功能，其功能参数和midi解码中的一致，其中参数：
l. hdl：midi琴解码句柄；
2. cmd：命令，可用命令如下；
1 CMD_MIDI_CTRL_TEMPO；
2 CMD_MIDI_SET_EX_VOL；
3 CMD_INIT_CONFIGS；
4 CMD_MIDI_SET_SEMITONE；
5 CMD_MIDI_SET_SWITCH；
3. parm：命令参数，可查看midi解码中的介绍；
4. 返回值：成功 0；
失败其他值；

1.3.3.5 函数int music_midi_ctrl_note_on(music_play_obj *hdl, u8 nkey, u8 nvel, u8 chn)

该函数实现弹奏指定通道的音符，其中参数：
l. hdl：midi琴解码句柄；
2. nkey：音符，与midi音色库制作工具中的音符号一致，范围在0~ l27；
3. nvel：琴键按下力度，范围在0~ l27；部分乐器（如钢琴）有效，不同力度会使按下后的余音长短不同；
4. chn：发声通道，该值范围在0~ l5；
5. 返回值：成功 0；
失败其他值；

1.3.3.6 函数int music_midi_ctrl_note_off(music_play_obj *hdl, u8 nkey, u8 chn)

该函数实现查找设置midi琴的乐器。对于声音不会衰弱的乐器（如笛子），调用Note_on 函数后需要调用该函数以结束音符，对于声音会衰弱的乐器（如钢琴）可不用。其中参数：

hdl：midi琴解码句柄；
nkey：音符，与midi音色库制作工具中的音符号一致，范围在0~ 127；
chn：发声通道，该值范围在0~ 15；
返回值：成功 0；

失败其他值；

1.3.3.7 函数 int music_midi_ctrl_vel_vibrate(music_play_obj *hdl, u8 nkey, u8 vel_step, u8

vel_rate, u8 chn)

该函数实现配置音符的颤音效果，其中参数：

hdl：midi琴解码句柄；
nkey：音符，与midi音色库制作工具中的音符号一致，范围在0~ 127；
vel_step：抖动步长，该值范围在0~7；
vel_rate：抖动幅度，该值范围在0~ 15；
返回值：成功 0；
失败其他值；

1.3.3.8 函数int midi_ctrl_play_end_deal(music_play_obj *hdl)

该函数实现停止midi琴解码，在所有音符停止后会被调用，其中参数：

hdl：midi琴解码句柄；
返回值：无；

1.3.3.9 函数void midi_ctrl_callback_init(music_play_obj hdl, u32(melody_callback)(void

*, u8, u8), u32(*melody_stop_callback)(void *, u8))
该函数实现配置音符开始与结束的回调函数，其中参数：

hdl：midi琴解码句柄；
melody_callback：音符开始回调函数，回调函数的原型参照《1.2.6.1主旋律的音符回调功能》中的说明；
melody_stop_callback：音符结束回调函数，回调函数的原型参照《1.2.6.2主旋律的音符结束回调功能》中的说明；
返回值：无；

MIDI工具

http://www.zh-jieli.com /

第二章 MIDI工具

2. 1 MIDI工具主界面

2.1.1 MIDI版本说明

带有“压缩编辑”选项和“导入SF2音色库”选项的为新版工具（JLmidi_new_ 0706），
只支持AD14和AD15在SDK版本大于等于V1 .3.0的SDK上运行，旧版本工具（JLmidi_ 60）
支持所有版本SDK。
新版和旧版工具均可在gitee上下载。

2.1.2 MIDI工具简介

MIDI文件是一种事件文件，不含音源，它记录的是一系列的事件。
MIDI文件解码，是从MIDI音源库中查找（或者根据一定的算法计算）得到事件对应的音频，因此对于不同的音源库而言，相同的MIDI文件解码出来的声音不同。
我司MIDI音源文件不会记录每个按键的声音，解码时再依次查找叠加，这种做法会导致音源库很大。我司的做法是：假设0号乐器的第n 到m号按键是可以通过N号按键计算的（m<=(N+12)），那么库中只需要记录N号按键。比方说，0-20号key都用 10号key 的声音根据频率关系去计算，21-47号key都用48号key去计算…那么只需记下0号乐器的第 10、48…号按键。
本工具的作用：可以查看，某个乐器某个按键的音源及其信息。也可以进行编辑修改成自己想要的声音。
点击“pWM.exe”，打开midi工具。

2.1.3 主界面-乐器种类

图中的红色框为乐器大类，共32项；蓝色框为乐器细分种类，共8项。对应的乐器号计算方法：假设乐器种类为0-31，乐器细分为0-7。乐器号为（乐器种类*8+乐器细分）。
在“打击乐器”中，有很多的乐器是没有的，用户可以自主添加乐器声。
鼠标点击“乐器细分种类”后，可点击按键试听音色。

2.1.4 主界面-选中乐器

在midi文件转换的时候，工具会自动把文件中所使用的乐器加载到库中。同时，用户也可以手动添加一些乐器（用于midi琴等），在midi转换的时候把这些库也加载到库中。选择乐器时会提示选择乐器的哪些key，未选择的key在SDK弹奏的结果不可预测。
SDK程序中midi琴有 16个通道，其中0~ 8和9~ 15号通道可以使用0-127号乐器，9 号通道只能使用 128-255号乐器。
如选择00-01高亮大钢琴，那么通道号可以选择0~ 8或10~ 15，乐器号写0 8+1 = 1；
如选择 16-00 standard，乐器号为 168+0= 128，大于 127，所以通道号只能选9，乐器号写：16*8+0-128 = 0；

2.2 MIDI转换

midi转换过程包括选择输出目录、转换和导出库三个步骤。
原始的midi文件需要通过我司的MIDI转换工具“转换”后才能正常使用； “导出库”会将midi文件中用到的乐器制作成音色库。
若是只用到midi琴的应用，在主界面选择自己所需要的乐器后，直接点击“导出库”选项即可生成相应的音色库。

2.2.1 选择需要转换的MIDI文件

在MIDI工具主界面中点击“MID转换”弹出MIDI文件转换工具，点击“添加文件”按钮，在弹出的文件选择框中选中要转换的一个或多个midi文件。

2.2.2 输出目录

点击 “输出目录”，选择转换后midi文件存放的文件夹。默认路径为 “工具根目录\OutMID”文件夹中。

2.2.3 转换

点击 “开始转换”，即可在设置的输出目录下生成我司自定义的mid文件，右下角显示转换进度。此时按键灰掉不能使用，等待转换完成才恢复。

2.2.4 导出库

转换完成后，点击“导出库”，工具根据“输出目录”中的文件生成一个我司自定义的 mid音色库文件，保存在“输出目录”的 “MID_RES”文件夹中，默认为路径为“工具根目录\OutMID\MID_RES”文件夹中。
如果在主界面中有选中乐器， “导出库”会将midi文件需要的乐器和主界面选中的乐
器一起打包制作成音色库文件。若是只用到midi琴的应用，在主界面选择自己所需要的乐
器后，直接点击“导出库”选项即可生成相应的音色库。
注：新的SDK支持新版工具生成的“.mda”后缀音色库，且兼容旧版工具生成的“.mid”后缀音色库；旧的SDK 只支持旧版工具生成的 “.mid”后缀音色库。可通过SDK 中midi 初始化的代码判断是否支持新版工具制作的音色库。

2.3 MIDI音色库压缩

MIDI一个乐器的相邻的一连串音符（key），并非都是单独的音频文件，可能是由同一个音源文件经过音频算法偏移得到的。
MIDI音色库压缩就是压缩这类音源文件，因此压缩一个音源文件会影响到一连串音符（key）的音质，甚至会影响到同一个大类下的其他乐器的一连串音符的音质。

2.3.1 压缩流程

鼠标点击蓝色框乐器细分种类和琴键后，可以通过点击右边“编辑压缩”选项，选择是否压缩对应的音色文件。
选中相应的乐器，勾选并点击“编辑压缩”选项，会打开如下编辑界面，选择需要的压缩方式并保存；如果全部音源都是不压缩的，建议不要勾选该选项，因为压缩会带来额外开销。
编辑界面会显示所选乐器的key 的音源文件号，以及该音源文件会影响到的所有乐器及该乐器的key范围。改了压缩选项后，返回主界面弹奏对应的琴键，即可试听压缩后的效果。
进入编辑界面算好压缩方式后，点击“压缩乐器”，会将所选乐器的所有音符对应的音源文件，全部按照所选压缩方式进行压缩。

5) 将该乐器压缩后的音色库导出，导出后可以查看更多乐器的压缩信息。

2.3.2 压缩信息查询

导出库后，midi工具根目录下会更新midiinfo.html、progaudio.html、progaudio_all.html、 proginfo.html四个文件，这些文件能显示更加详细的音色和压缩信息。

1) midiinfo.html

该文件可以查看转换的midi乐谱文件用到哪些乐器的哪些key，可根据这里的信息再去压缩对应的音源文件。

2) progaudio.html

该文件可以查看导出的音色库中的音源文件，是否哪种压缩算法，音源文件影响的乐器的key范围以及压缩前后的大小。其中：
● 工具默认的乐器所依赖的音源从0开始编号
● 用户自行导入的SF2音色库从32768开始编号
● 用户使用”WAV编辑”生成的音色从65536开始编号

3) progaudio_all.html

该文件与progaudio.html类似，区别在可以查看所有的音源文件，以及音源文件影响的乐器的key范围。

4) proginfo.html

该文件可以查看导出库中包含的乐器信息，包括key 映射的范围。

2.3.3 还原压缩配置内容

配置完压缩后，若需要重置压缩选项，可以删除工具根目录下的“config.txt”文件，再重启软件；

2.4 MIDI导入SF2音色库

midi工具除了可以使用我司默认的音色库外，还可以导入SF2音色库。

2.4.1 添加或删除SF2文件

主界面中点击“导入SF2音色库”选项，点击“添加SF2文件”选择SF2文件；单个 SF2文件大小不可超过65535字节，否则会报错；
导入后点击“替换到音色库”。 “替换到音色库”会删掉之前替换生成的bin文件，重新生成新的bin文件；如果列表中保留了上次添加的SF2记录，但SF2源文件已不存在了，
则需要选择“追加替换到音色库”。替换完成后即可在主界面试听效果。
删除SF2库之后，需要重启软件才会生效。

2.4.2 SF2音色库信息查询

SF2音色替换完成并将MIDI音色库导出后，可以在工具根目录下查看progaudio.html 文件；所替换乐器的音源号大于32768小于65535 即表示导出的音色库中 SF2音色替换成功。

2.4.3 还原SF2音色库内容

导入SF2音色库后，若需要重置SF2音色库选项，可以删除工具根目录GP文件夹下的“sf2_config.bin”文件，再重启软件；

2.5 MIDI WAV编辑

2.5.1 WAV编辑界面简介

在主界面中点击“WAV编辑”进入MIDI音源编辑界面，编辑音源时记得要把乐器跟 key都选好。
● 文件界面：当前选中的音频文件，可以点击“打开文件”添加自己的文件
● 波形界面：选中文件的wav波形显示与编辑
● 正常/松手衰减：音频的衰减情况
● 包络编辑界面：勾选左侧“包络”选项，可编辑当前文件wav波形的包络效果

2.5.2 波形编辑

在波形图界面中点击右键弹出波形编辑框，点击“选择->边界标记”，再点击“选择->区间选择”选中一段区域，那么就可以对这一段音频进行复制\剪切之类的编辑了。
选择右击菜单的最后一项“当前WAV文件另存为…”，可以将编辑结果另存为自己的 wav文件。否则编辑无效，就算是打开的默认音色的wav文件，也是生成的一个临时文件而已。如果不另存，下一次编辑也是会被改写的。
另外，提示打不开tmp.wav，可能是库里面不包含该按键的声音。也可能没有选择key，导致没有文件生成。具体检查方法，可以看下“.\GP”中tmp.wav 的Wav文件存在，但是
长度为0，则该声音不存在。

2.5.3 参数配置

在“WAV编辑”界面中点击“参数”进入参数编辑界面。如下图，图中是一个音色文件的单元信息，也就是该乐器的key码对应wav波形。音量、上升速度、正常衰减、松手衰减、衰减限制都是0-1，但是工具中，以65535量化。所以，65535对应1，其中参数：
● Key码：
当前编辑的为乐器的 115号按键
● KEY范围：
当前乐器的 115-126号按键通过映射而来，映射范围在0~ 127之间，如果设置了非
法值，则本次编辑无效
● 音量：
默认音量的大小。可以调节该值，改变该乐器的默认音量
● 上升速度：
改变的是一个按键发声的时候，它的淡入速度
● 正常衰减与松手衰减：
该按键音的衰减速度。一般松手之后，声音会更快地衰减。右图曲线窗显示的只有前面32ms 的衰减形状

● 衰减限制：

按键长按时，声音会hold住的一个阈值。只有在松手后，声音才会低于该阈值继续衰减

● 循环起始位置：

只对应循环有效的音源信息文件有效，即后面的小框是勾起的。简单的来说，如果不是循环的，那先忽略音量，就是一个音源文件有多长，那发声最长也就那样了。一个声音发完了就是发完了。但是，如果一个循环的音源文件，就是一个无穷长的文件，从循环位置开始一直到波形文件最后的这段波形视为一个周期，这个周期一直在现有的波形文件后面做周期性扩展。所以编辑的时候请注意，波形前后扩展时的过度，例如波形为[ 1,2,3,4,5,6,7]， 3为循环起始，那波形实则为[1,2,3,4,5,6,7,3,4,5,6,7,3,4...]。这时候，请保证，周期扩展连接处，即7,3之间。 [1,2,3,4,5,6,7,3,4,5,6,7,3,4...]这个才是最后的波形，如果，这个声音在连接处不平滑，有啪一声，那就会一直啪啪响的了。例如波形是
[ 1,2,3,4,5,6,5,4,3,2],则为[1,2,3,4,5,6,5,4,3,2, 3,4,5,6,5,4,3,2, 3,4,…]，要保证这个声音听起来好听。

● 包络曲线：

选择是否需要编辑包络效果，与主界面“包络”勾选项一致。
另外需要确认的是，该窗口最上面的wav文件路径。请选择自己之前保存的wav文件路径，不要用临时路径。就是默认打开的音色编辑的wav。该wav文件，是从库里剔出来生成的临时文件而已。下次是会被重写的。每次修改完保存的都只是路径而已。如果该wav 无效了，或者被修改了。那都是按最后wav文件的内容进行库编辑的。

2.5.4 包络编辑

勾选主界面左侧的“包络”选项，或者在参数配置中勾选“包络曲线”，即可在主界面编辑wav音频的包络效果。
包络界面说明：

纵轴代表幅值，范围为0~ 100%；
横轴代表时间，默认范围为0~ 1500ms；可修改默认的 1500ms 时间长度，超过wav 文件时间范围的话，表示会保持包络最后一点的能力；
包络编辑方法：
双击增加包络点；
长按可以拖动包络点；
鼠标挪到包络点位置，点击右键即可删除节点；
注意：使用包络模式，参数配置中的上升速度跟松手衰减这2个值依旧有效！

	C	C#	D	D#	E	F	F#	G	G#	A	A#	B
0	0	1	2	3	4	5	6	7	8	9	10	11
1	12	13	14	15	16	17	18	19	20	21	22	23
2	24	25	26	27	28	29	30	31	32	33	34	35
3	36	37	38	39	40	41	42	43	44	45	46	47
4	48	49	50	51	52	53	54	55	56	57	58	59
5	60	61	62	63	64	65	66	67	68	69	70	71
6	72	73	74	75	76	77	78	79	80	81	82	83
7	84	85	86	87	88	89	90	91	92	93	94	95
8	96	97	98	99	100	101	102	103	104	105	106	107
9	108	109	110	111	112	113	114	115	116	117	118	119
10	120	121	122	123	124	125	126	127

2.6.2 乐器表

乐器表可参考SDK 中的app\src\app_mg\midi\midi_prog.h文件。

	C	C#	D	D#	E	F	F#	G	G#	A	A#	B
0	0	1	2	3	4	5	6	7	8	9	10	11
1	12	13	14	15	16	17	18	19	20	21	22	23
2	24	25	26	27	28	29	30	31	32	33	34	35
3	36	37	38	39	40	41	42	43	44	45	46	47
4	48	49	50	51	52	53	54	55	56	57	58	59
5	60	61	62	63	64	65	66	67	68	69	70	71
6	72	73	74	75	76	77	78	79	80	81	82	83
7	84	85	86	87	88	89	90	91	92	93	94	95
8	96	97	98	99	100	101	102	103	104	105	106	107
9	108	109	110	111	112	113	114	115	116	117	118	119
10	120	121	122	123	124	125	126	127

	C	C#	D	D#	E	F	F#	G	G#	A	A#	B
0	0	1	2	3	4	5	6	7	8	9	10	11
1	12	13	14	15	16	17	18	19	20	21	22	23
2	24	25	26	27	28	29	30	31	32	33	34	35
3	36	37	38	39	40	41	42	43	44	45	46	47
4	48	49	50	51	52	53	54	55	56	57	58	59
5	60	61	62	63	64	65	66	67	68	69	70	71
6	72	73	74	75	76	77	78	79	80	81	82	83
7	84	85	86	87	88	89	90	91	92	93	94	95
8	96	97	98	99	100	101	102	103	104	105	106	107
9	108	109	110	111	112	113	114	115	116	117	118	119
10	120	121	122	123	124	125	126	127

	C	C#	D	D#	E	F	F#	G	G#	A	A#	B
0	0	1	2	3	4	5	6	7	8	9	10	11
1	12	13	14	15	16	17	18	19	20	21	22	23
2	24	25	26	27	28	29	30	31	32	33	34	35
3	36	37	38	39	40	41	42	43	44	45	46	47
4	48	49	50	51	52	53	54	55	56	57	58	59
5	60	61	62	63	64	65	66	67	68	69	70	71
6	72	73	74	75	76	77	78	79	80	81	82	83
7	84	85	86	87	88	89	90	91	92	93	94	95
8	96	97	98	99	100	101	102	103	104	105	106	107
9	108	109	110	111	112	113	114	115	116	117	118	119
10	120	121	122	123	124	125	126	127