.. _midi功能章节:  

MIDI
=========================================

    + MIDI全称是乐器数字接口(Musical Instrument Digital Interface)，是20 世纪80 年代初为解决电声乐器之间的通信问题而提出的，编曲界最广泛的音乐标准格式。
    
    + 默认SDK提供的midi功能分为 midi解码 和 midi琴。

      **midi解码** 用户可参考midi_decode_app模式。

      **midi琴** 用户可参考midi_keyboard_app模式。

    + 详细midi功能及说明请看SDK包里的《杰理AD1x-45678_MIDI应用说明文档.pdf》文档。

      *（注：该文档实际函数以AD16N_flash_v1.4.0工程为准，其余芯片SDK实际函数名会有出入，但实现原理不变）*

    + AD16N从V1.4.0版本开始开源2byte和4byte地址版本的midi中间层代码。


.. _midi驱动版本选择说明: 

midi驱动版本选择说明
---------------------------------------------

    AD16N从V1.4.0版本开始开源2byte和4byte地址版本的midi中间层代码。

    用户可运行位于SDK根目录的批处理来选择编译链接2byte或4byte版本的中间层代码、头文件以及算法库。批处理会更改：

    1、文件AD16N_mbox_flash.cbp的配置
    2、apps\app\src\mbox_flash\uc03\app_modules.h的MIDI_VER_SELECT宏定义
    
    **注：该工具是通过修改cbp文件信息来选择编译对应的驱动的版本，不会对makefile做出任何改动，因此只能用于codeblocks等依赖cbp文件信息来编译的开发平台.**

    .. image:: midi_bat.png
        :alt: "midi批处理“
        :align: center
    .. centered:: midi批处理

    midi 2byte和4byte版本的基本差异如下表：

    ===========    =============    =============   ======================  =======================   ===================   =====================
    midi版本        乐谱后缀名      音色库后缀名    算法库名(已开源的库名)  音色库支持的PCM样点数     音色库支持的声道数    算法输出支持的声道数
    ===========    =============    =============   ======================  =======================   ===================   =====================
    2byte          .mfa             .mda            lib_midi_synth.a        <=65535个点               单声道                 单声道 
    4byte          .mfa             .mdb            lib_midi_synth_pro.a    <=1900000                 单声道、双声道         单声道、双声道
    ===========    =============    =============   ======================  =======================   ===================   =====================

midi驱动版本选择步骤
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    公版SDK默认使用2byte版本的midi驱动，执行midi_4byte.bat会替换成4byte版本，下面详细介绍：

step1:选择编译midi版本驱动
""""""""""""""""""""""""""""""""""""""""""

    .. image:: midi_ver_select_tool.png
        :alt: "midi驱动版本选择工具“
        :align: center
    .. centered:: midi驱动版本选择工具

    在上述工具中，双击midi_4byte.bat就是选择编译4byte版本的midi驱动，双击midi_2byte.bat则选择编译2byte版本的midi驱动.

    双击后4byte的工具成功后会有以下打印，然后用文本编辑器点开AD16N_mbox_flash.cbp检查2byte的目录是否被替换成4byte，2byte算法库是否有被替换成4byte的算法库

    .. image:: midi_ver_4byte_succ.png
        :alt: "midi驱动版本选择4byte版本“
        :align: center
    .. centered:: midi驱动版本选择4byte版本

step2:检查cbp文件
""""""""""""""""""""""""""""""""""""""""""

在成功运行批处理后，cbp文件的配置会有下面的这些修改，客户也可以如下图手动修改：

    .. image:: midi_ver_compile_4byte.png
        :alt: "midi编译4byte版本驱动“
        :align: center
    .. centered:: midi编译4byte版本驱动

    .. image:: midi_hfile_4byte.png
        :alt: "midi头文件依赖选择4byte版本“
        :align: center
    .. centered:: midi头文件依赖选择4byte版本

    .. image:: midi_lib_select_4byte.png
        :alt: "链接4byte版本的midi算法库“
        :align: center
    .. centered:: 链接4byte版本的midi算法库

step3:检查app_modules.h文件的宏定义
""""""""""""""""""""""""""""""""""""""""""

    在成功运行批处理后，app_modules.h的宏定义“#define MIDI_VER_SELECT”会被修改，客户也可以如下图手动修改：
    （该处修改会影响midi的初始化流程、运算buf大小、音频数据流对midi算法适配的声道数）
    
    .. image:: midi_config_4byte.png
        :alt: "SDK配置midi使用4byte版本驱动“
        :align: center
    .. centered:: SDK配置midi使用4byte版本驱动
    

step4:检查SDK音色库是否应用成功
"""""""""""""""""""""""""""""""""""""""""""""""""""""

    在v1.4.0的SDK中,4字节midi和2字节，midi音色库是不一样的，音色库位于目录apps/app/post_build/uc03中，下表为音色库文件名信息：

    =======    ===================
     type        name
    =======    ===================
     2byte      midi_cfg
     4byte      midi_cfg_ster1
    =======    ===================


    在编译成功后，目录apps/app/post_build/uc03中会生成download.bat文件，此文件会下载如下如所示不同的midi音色库：

    .. image:: download_midi_cfg.png
        :alt: "不同midi音色库文件下载“
        :align: center
    .. centered:: 2字节与4字节midi音色库文件下载区别

    *注1：download.bat是由apps/app/post_build/uc03/mbox_flash/download_bat.c在工程编译时自动生成*

    *注2：download_bat.c中的宏定义HAS_midi_4byte_USED控制最终生成download_bat.c下载何种音色库*


    编译下载并启动SDK之后，midi初始化会打开此文件。

    .. image:: midi_open_mdb.png
        :alt: "midi解码初始化打开音色库文件“
        :align: center
    .. centered:: midi解码初始化打开音色库文件

step5:按照自己的需求，选择输出的声道数
""""""""""""""""""""""""""""""""""""""""""""""

    声道配置注意：midi算法输出数据的声道数需要和音频数据流的配置适配，否则会出现播放声音异常的问题

    .. image:: midi_chn_num.png
        :alt: "midi声道数配置“
        :align: center
    .. centered:: midi声道数配置



MIDI基本功能配置
---------------------------------------------

MIDI解码基本功能以及对应的命令如下：
  #. 配置midi使用模式（CMD_MIDI_CTRL_MODE）
  #. 配置OKON模式发声（CMD_MIDI_GOON / CMD_MIDI_OKON_MODE）
  #. 切换主旋律乐器（CMD_MIDI_SET_PROG）
  #. 配置主通道乐器或者所以通道的乐器（CMD_MIDI_SET_CHN_PROG）
  #. mark回调播放功能（CMD_MIDI_SET_MARK）
  #. 小节回调（CMD_MIDI_SEEK_BACK_N）
  #. 调节midi外部音量功能（CMD_MIDI_SET_EX_VOL）
  #. 移半音功能（CMD_MIDI_SET_SEMITONE）
  #. 更改节奏和衰减功能（CMD_MIDI_CTRL_TEMPO）
  #. 配置限幅器（CMD_MIDI_LIMITER_TRIGGER）

MIDI琴基本功能与对应的命令如下：
  #. 动态修改音色相关参数
  #. 更改节奏和衰减功能（CMD_MIDI_CTRL_TEMPO）
  #. 调节midi外部音量功能（CMD_MIDI_SET_EX_VOL）
  #. 移半音功能（CMD_MIDI_SET_SEMITONE）
  #. 配置限幅器（CMD_MIDI_LIMITER_TRIGGER）
  #. 琴键颤音功能
  #. 弯音轮功能
  #. 动态修改当前播放的乐器通道

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    详细更多说明，请看 SDK包里 doc文件夹里的 《 **杰理AD1x-45678_MIDI应用说明文档.pdf** 》

    .. image:: midi_doc.png
        :alt: "midi文档位置"
        :align: center
    .. centered:: midi文档位置