变音音效（vo_pitch）
=========================================

    AD16N 和 AW30N SDK均提供变音音效（vo_pitch）音效，该功能由 app_modules_h.c 里的 VO_PITCH_EN 宏控制开关。

    本节主要介绍变音音效，其包含一下几种音效: 

        * ①	两种机器人声；
        * ②	两种变速变调；
        * ③	两种rap；
        * ④	卡通音效；
        * ⑤	混响音效;

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

变音音效参数配置
################################
    
    .. image:: 18-4-1-1-vopitch_config.png
        :alt: "图1 变音音效参数配置"
        :align: center
    .. centered:: 图1 变音音效参数配置

    变音音效的参数配置如图1 变音音效参数配置
    
    但是在选择不同的变声效果时，在某些效果下有些参数无效，如图2所示
    
    其他音效模式具体参照SDK中的文件apps/app/bsp/common/sound_effect/vo_pitch_api.c中各个音效参数配置函数的注释说明。

    .. image:: 18-4-1-2-vopitch_config_example.png
        :alt: "图2 变调模式参数配置"
        :align: center
    .. centered:: 图2 变调模式参数配置

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

.. _变音音效算法链路链接函数:

变音音效算法链路链接函数
################################

    SDK提供下面的函数，传递不同的CMD参数可以实现不同的音效。

函数sound_out_obj \*link_voice_pitch_sound(sound_out_obj \*p_curr_sound, void \*p_dac_cbuf, void \**pp_effect, u32 cmd)
****************************************************************************************************************************************
    | 此函数实现主要实现变音算法的启动，将变音算法链接到音频链路中；
    | ①	返回值：启动之后最新的音频通道句柄；
    | ②	void \*p_sound_out: 当前算法前级的音频通道句柄；
    | ③	void \*p_dac_cbuf: 输出到DAC的OBUF；
    | ④	void \**pp_effect: 存放当前音效算法的控制句柄指针的指针；
    | ⑤	u32 cmd: 音效控制指令；

    .. image:: 18-4-2-1-effect_cmd.png
        :alt: "图4 音效控制指令"
        :align: center
    .. centered:: 图4 音效控制指令

    如果需要在解码应用中接入该音效，需要做以下几个步骤：

        | 1、修改ld文件，防止音效算法与解码格式资源复用。
        | 2、添加音效串联接口，可仿照decoder_api.c中，decoder_list函数串联song_speed和eq的方法做音效串联。
        | 3、其中pp_effect参数可根据需要选择传NULL或者传自定义的effect句柄(可用于动态调整参数)
        | 4、如果有动态调参需求，可以在对应的音效api文件中查找动态调参接口（函数名一般为update_音效名_parm），将修改后的音效参数传入调参接口即可实现动态调参。

函数void \*voice_pitch_api(void \*obuf, u32 cmd, void \**ppsound)
*****************************************************************************

    | 该函数用于初始化变音音效相关参数，由函数link_voice_pitch_sound()调用即可；
    | 该函数内部会调用函数vp_cmd_case()，用于配置所选的变音音效以及其参数。
    

函数void rap_callback(void \*priv, int pos)
*****************************************************************************

    | 该函数为RAP模式的回调函数，由解码器调用。其中的参数pos表示RAP模式的状态；
    | RAP模式初始化后，pos会处于RAP_PREPARE状态等待输入音源；
    | 当输入音源大于所设置的noise_dc能量阈值后，会触发RAP模式，此时pos在会PAR_START状态；
    | 当RAP播放结束后，pos会在RAP_END状态循环。若需要重置RAP状态，需调用函数rap_reopen()。
    
函数void rap_reopen(void)
*****************************************************************************

    该函数用于RAP模式播放结束后，让RAP重回RAP_PREPARE状态。

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

变音音效算法参数函数
################################
    通过配置不同的参数，可以实现不同的音效，其中关键的函数有以下：
    
    1、音效参数选择函数：
    
    bool vp_cmd_case(VP_CMD cmd, VOICE_PITCH_PARA_STRUCT \*p_vc_parm)；
    
    2、rap音效参数配置函数：
    
    void vp_cmd_rap(p_vc_parm);
    
    3、实时rap音效参数配置函数；
    
    void vp_cmd_rap_realtime(VOICE_PITCH_PARA_STRUCT \*p_vc_parm)；
    
    4、平调机器人音效参数配置函数；
    
    void vp_cmd_robot(VOICE_PITCH_PARA_STRUCT \*p_vc_parm)；
    
    5、变调机器人音效参数配置函数；
    
    void vp_cmd_robot2(VOICE_PITCH_PARA_STRUCT \*p_vc_parm)；
    
    6、变速变调音效参数配置函数；
    
    void vp_cmd_pitchshift(VOICE_PITCH_PARA_STRUCT \*p_vc_parm)；
    
    7、变速变调2音效参数配置函数；
    
    void vp_cmd_pitchshift2(VOICE_PITCH_PARA_STRUCT \*p_vc_parm)；
    
    8、卡通音效参数配置函数；
    
    void vp_cmd_echo(VOICE_PITCH_PARA_STRUCT \*p_vc_parm)；
    
    9、混响音效参数配置函数；
    
    void vp_cmd_echo(VOICE_PITCH_PARA_STRUCT \*p_vc_parm)；

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

两种RAP音效的区别
###############################
    RAP与实时RAP的音效是一样的，都是在输入音频数据流有能量时进行一次变音；但是他们在使用控制时有较大的区别；
    
    1、RAP在调用启动后，会在输入的音频信号有能量时进行一次变音，再之后就会停止；下次启动变音需要调用回调函数，回调函数中调用rap_reopen可以再次启动RAP；
    
    2、实时RAP在启动后，变音会一直工作;


.. _RAP和RAP_REALTIME模式文件替换说明:   

RAP和RAP_REALTIME模式文件替换说明
#############################################################################

    用户可以通过替换该音效依赖的midi文件表来进行播出不同的音调，midi文件表位于头文件midi_file0_h.h。

    .. image:: midi_file0_headfile.png
        :alt: "midi_file0_headfile.png"
        :align: center

    用户可以通过get_miditabs工具生成midi文件表，首先将需要使用的midi文件表放入工具目录，然后点击t.bat生成头文件
    
    .. image:: get_miditabs.png
        :alt: "get_miditabs.png"
        :align: center

    打开头文件可以看到生成的midi文件表

    .. image:: midi_tab.png
        :alt: "midi_tab.png"
        :align: center

    最后将生成的文件表复制到SDK的头文件midi_file0_h.h，然后在函数初始化设置配置文件表，图中以rap_realtime模式为例

    .. image:: rap_realtime_config.png
        :alt: "rap_realtime_config.png"
        :align: center