1. 玩具应用篇（新工程 - voice_toy）

1.1. 简介

2023年7月11日发布的AD1x-457_AC104-release_v1.7.0 SDK，新增了voice_toy工程；

该工程在旧版玩具工程app_mg与示例工程simple基础上进行优化，使应用示例更加简单、直观，便于用户上手开发；

各芯片支持的应用模式如下：

应用模式

AD14N

AD15N

AD17N

AD18N

toy_music

√

√

√

√

toy_midi

√

√

√

√

toy_midi_keyboard

√

√

√

√

toy_record

√

toy_speaker

√

toy_linein

√

toy_softoff

√

√

√

√

toy_idle(demo)

√

√

√

√

不同的模式间会有资源和按键互斥的关系。应用上面做了一个简单的模式切换管理来管理不同模式的资源和按键。

模式管理的整体管理思路是，进入该模式的时候初始化模式需要使用的资源和按键处理函数，退出该模式的时候关闭该模式需要使用的资源和释放按键处理函数。

模式初始化以及模式切换函数：

void app(void);
void app_next_mode(void)

模式管理接口的文件摆布：

图1 voice_toy应用模式管理

1.1.1. 模式相关函数

1.1.1.1. 函数void app_next_mode(void)

此函数切换下一个应用模式，上一个应用切换前需要释放申请的资源:

1.2. toy_music 多路解码模式

1.2.1. 模式说明

多路解码模式使用了SYD文件系统，能够播放打包成dir文件的F1A/B/C/X、UMP3，并叠加A文件解码，同时支持外挂FLASH解码。
该模式还具备VM记忆，可记录解码文件序号与断点。

多路解码使用play_control结构体，其成员如下：:

typedef struct __play_control {
void *pfs;          //文件系统句柄
void *pfile;        //文件句柄
dec_obj *p_dec_obj; //解码器句柄
void *pdp;          //断点指针
u32  findex;        //当前播放的文件序号
u32  ftotal;        //当前文件夹中的文件总数
u16  dec_type;      //解码器支持的解码类型，如BIT_F1A1
u8   dev_index;     //当前挂载设备的序号，如INNER_FLASH_RO
u8   play_mode;     //播放模式(Music模式使用)
void *device;       //当前挂载设备的句柄
void *pdir;         //文件夹指针,用于切换文件夹
u8   *p_vm_tab;     //存放vm项指针,用于记忆不同文件夹的掉电数据
u8   dir_total;     //文件夹总数
u8   dir_index;     //当前播放的文件夹序号
u8   loop;          //播放循环次数
// u8   flag;          //标志位(Music模式使用)
} play_control;

涉及的文件目录：app\src\voice_toy\toy_music，涉及的应用函数如下：

1.2.2. 解码播放函数

1.2.2.1. 函数u32 simple_dev_fs_mount(play_control *ppctl)

此函数是多路解码挂载设备和SYD文件系统，其中参数：
1. ppctl：音乐播放器句柄指针；
2. 返回值：
    成功 返回0；
    失败 错误值可查看errno-base.h；

1.2.2.2. 函数u32 simple_dev_fs_close(play_control *ppctl)

此函数实现多路解码释放文件、文件系统句柄，并关闭设备；释放的句柄分别是结构体play_control中的成员pfile，pfs以及device，其中参数：
1. ppctl：音乐播放器句柄指针；
2. 返回值：0；

1.2.2.3. 函数u32 get_decoder_status(dec_obj *obj)

此函数实现获取多路解码当前的状态，分别有播放停止（MUSIC_STOP）、播放暂停（MUSIC_PAUSE）以及播放中（MUSIC_PLAY）三种状态，其中参数：
1. obj：解码句柄；
2. 返回值：返回当前解码器播放状态；

1.2.2.4. 函数u32 simple_play_file_bypath(play_control ppctl, const char path)

此函数实现通过传入的路径播放文件，其中参数：

1. ppctl：音乐播放器句柄指针；
2. path：音频文件路径（对于外挂flash，忽略第一级目录）；
3. 返回值：
    成功 返回0；
    失败 错误值可查看errno-base.h；

1.2.2.5. 函数u32 simple_play_file_byindex(play_control *ppctl, u32 index)

此函数实现通过传入的序号播放文件，ppctl中的pdir为需要播放的文件夹路径，其中参数：
1. ppctl：音乐播放器句柄指针；
2. index：音频文件序号；
3. 返回值：
    成功 返回0；
    失败 错误值可查看errno-base.h；

1.2.2.6. 函数u32 play_one_file(play_control *ppctl)

此函数实现通过ppctl中的findex参数播放文件，播放成功后记录VM数据，该接口由应用层调用，其中参数
1. ppctl：音乐播放器句柄指针；
2. 返回值：
    成功 返回0；
    失败 错误值可查看errno-base.h；

1.2.2.7. 函数u32 play_prev_file(play_control *ppctl)

此函数实现播放上一首音频，播放成功后记录VM数据，该接口由应用层调用，其中参数
1. ppctl：音乐播放器句柄指针；
2. 返回值：
    成功 返回0；
    失败 错误值可查看errno-base.h；

1.2.2.8. 函数u32 play_next_file(play_control *ppctl)

此函数实现播放下一首音频，播放成功后记录VM数据，该接口由应用层调用，其中参数
1. ppctl：音乐播放器句柄指针；
2. 返回值：
    成功 返回0；
    失败 错误值可查看errno-base.h；

1.2.2.9. 函数u32 simple_switch_device(play_control *ppctl)

此函数实现切换播放设备（内置-外挂flash互相切换），该接口由应用层调用，其中参数
1. ppctl：音乐播放器句柄指针；
2. 返回值：
    成功 返回0；
    失败 错误值可查看errno-base.h；

1.2.2.10. 函数u32 simple_next_dir(play_control *ppctl)

此函数实现切换下一个文件夹，该接口由应用层调用，其中参数
1. ppctl：音乐播放器句柄指针；
2. 返回值：
    成功 返回0；
    失败 错误值可查看errno-base.h；

1.2.2.11. 函数int simple_play_speed_set(play_control ppctl, SPEED_PITCH_PARA_STRUCT sp_parm)

此函数实现在播放过程中动态调整变速变调参数，该接口需要在链接变速变调音效后才可在应用层使用，其中参数:
1. ppctl：音乐播放器句柄指针；
2. 变速变调参数：其结构体成员具体可查看音效变速变调章节；
3. 返回值：
    成功 返回0；
    失败 返回-1；

1.3. toy_midi midi解码模式

1.3.1. 模式说明

midi解码模式使用了SYD文件系统，能够播放打包生成dir的midi文件，并叠加A文件解码。
midi解码同样使用了play_control结构体作为播放句柄。

1.3.2. 相关函数

1.3.2.1. 函数void midi_decode_init(void)

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

1.3.2.2. 函数void midi_dec_config(dec_obj p_dec_pbj, u32 cmd, void parm)

此函数实现查找midi解码的功能参数，cmd的具体介绍请看midi文件第2节MIDI乐谱解码介绍，其中参数码的音色库并记录音色库信息，在系统初始化中调用；

1.3.2.3. 函数void midi_mode_set(dec_obj *p_dec_pbj, u8 mode)

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

1、p_dec_obj：midi解码句柄；
2、mode：midi解码模式，可用mode如下：
    ①　CMD_MIDI_CTRL_MODE_0，正常解码模式；
    ②　CMD_MIDI_CTRL_MODE_1，one key one note模式；
    ③　CMD_MIDI_CTRL_MODE_2，只推消息不出声模式；
    ④　CMD_MIDI_CTRL_MODE_W2S，外部音源模式；

1.3.2.4. 函数void midi_okon_goon(dec_obj *p_dec_pbj)

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

1、p_dec_obj：midi解码句柄

1.3.2.5. 函数void midi_init_info(MIDI_INIT_STRCUT *init_info)

该函数实现midi解码配置初始化，会给midi解码器主动调用，其中参数：:
1、init_info: midi解码初始化配置结构体，具体请参照代码中的配置信息

1.4. toy_midi_keyboard midi琴模式

1.4.1. 模式说明

MIDI琴功能支持通过函数驱动midi解码。该应用依赖我司自定义的mid音色库，用户可通过我司mid工具进行转换，详情请看《JLmidi工具使用说明》。

1.4.2. 相关函数

1.4.2.1. 函数void midi_ctrl_decode_init(void)

该函数实现查找midi琴的音色库并记录音色库信息；

1.4.2.2. 函数u32 toy_midi_ctrl_set_prog(dec_obj *obj, u8 prog, u8 chn)

该函数实现查找设置midi琴的乐器，0其中参数：:

obj：midi琴解码句柄；
prog：乐器号，与midi音色库制作工具中的乐器号一致。详情请看《杰理AD14 AD15N MIDI应用说明文档》说明；
chn：发声通道，该值范围在0~15；
返回值：成功 0；
    失败 其他值；

1.4.2.3. 函数u32 toy_midi_ctrl_pitch_bend(dec_obj *obj, u16 pitch_val, u8 chn)

该函数实现配置midi琴弯音轮参数，其中参数：:

obj：midi琴解码句柄；
pitch_val：弯音值，默认值是256，可根据该值调整；
chn：发声通道，该值范围在0~15；
返回值：成功 0；
    失败 其他值；

1.4.2.4. 函数u32 toy_midi_ctrl_dec_config_api(dec_obj obj, u32 cmd, void parm)

该函数实现配置midi琴的其他功能，其功能参数和midi解码中的一致，其中参数：:

1.obj：midi琴解码句柄；
2.cmd：可用命令如下：
    CMD_MIDI_CTRL_TEMPO；
    CMD_MIDI_SET_EX_VOL；
    CMD_INIT_CONFIGS；
    CMD_MIDI_SET_SEMITONE；
    CMD_MIDI_SET_SWITCH；
3.parm：命令参数，可查看midi解码中的介绍；
4.返回值：成功 0；
        失败 其他值

1.4.2.5. 函数u32 toy_midi_ctrl_note_on(dec_obj *obj, u8 nkey, u8 nvel, u8 chn)

该函数实现弹奏指定通道的音符，其中参数：:

obj：midi琴解码句柄；
nkey：音符，与midi音色库制作工具中的音符号一致，范围在0~127；
nvel：琴键按下力度，范围在0~127；部分乐器（如钢琴）有效，不同力度会使按下后的余音长短不同；
chn：发声通道，该值范围在0~15；
返回值：成功 0；
        失败 其他值；

1.4.2.6. 函数u32 toy_midi_ctrl_note_off(dec_obj *obj, u8 nkey, u8 chn, u16 decay_time)

该函数实现查找设置midi琴的乐器。对于声音不会衰弱的乐器（如笛子），调用Note_on函数后需要调用该函数以结束音符，对于声音会衰弱的乐器（如钢琴）可不用。其中参数：:
1.obj：midi琴解码句柄；
2.nkey：音符，与midi音色库制作工具中的音符号一致，范围在0~127；
3.chn：发声通道，该值范围在0~15；
4.decay_time：衰减时间，单位ms，若为0则使用音色自带的衰减；
5.返回值：成功 0；
失败 其他值；

1.4.2.7. 函数u32 toy_midi_ctrl_vel_vibrate(dec_obj *obj, u8 nkey, u8 vel_step, u8 vel_rate, u8 chn)

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

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

1.4.2.8. 函数u32 midi_ctrl_melody_stop_trigger(void *priv, u8 key)

该函数实现停止midi琴解码，在所有音符停止后会被调用，其中参数：:
1.obj：midi琴解码句柄；
2.返回值：无；

1.4.2.9. 函数void midi_ctrl_callback_init(dec_obj obj, u32(melody_callback)(void , u8, u8), u32(melody_stop_callback)(void *, u8))

该函数实现配置音符开始与结束的回调函数，其中参数：:

obj：midi琴解码句柄；
melody_callback：音符开始回调函数，回调函数的原型参照《杰理AD14 AD15N MIDI应用说明文档》1.2.6.1主旋律的音符回调功能中的说明；
melody_stop_callback：音符结束回调函数，回调函数的原型参照《杰理AD14 AD15N MIDI应用说明文档》1.2.6.2主旋律的音符结束回调功能中的说明；
返回值：无；

1.4.2.10. 函数void toy_midi_ctrl_get_play_key(dec_obj *obj, u8 chn)

该函数实现获取指定通道正在播放的所有key值，其中参数：:
1.obj：midi琴解码句柄；
2.chn：需要查询的通道；
返回值：无；

1.5. toy_speaker 扩音模式

1.5.1. 模式说明

扩音模式实现将mic采集到的数据直通或者串联算法输出到dac。
扩音模式算法支持的算法详细见音效算法章节。

1.5.2. 相关函数

1.5.2.1. 函数void audio_adc_speaker_start(void)

该函数实现扩音模式初始化adc和dac，并且串联算法的整体流程，初始化扩音模式时使用；

1.5.2.2. 函数audio_adc_speaker_reless(void)

该函数实现扩音模式断开adc和dac数据流链接流程，并且释放src变采样申请使用的资源，在关闭扩音模式时使用；

1.6. toy_linein linein模式

1.6.1. 模式说明

该模式实现数字linein，该模式下需要将AUDIO_ADC和AUDIO_DAC配置到相同的采样率，可调节音量

1.7. toy_record 录音模式

1.7.1. 模式说明

录音模式实现将mic采集到的数据进行编码，并通过norfs文件系统方式保存至内置flash(放置代码的flash)
支持A格式和ump3格式编码

录音模式使用Encode_Control结构体，其成员如下：:

typedef struct _Encode_Control {
char fs_name[8];            //编码文件系统名
void *device;               //编码设备句柄
void *pfs;                  //编码文件系统句柄
void *pfile;                //编码文件句柄
union {
    u32 rec_file_index;     //nor_fs最新文件号
};
u8 dev_index;               //编码设备序号
ENC_STATUS enc_status;      //编码器工作状态
} Encode_Control;

1.7.2. 相关函数

1.7.2.1. 函数static int encode_start(Encode_Control *obj)

该函数实现录音功能启动。内部会开启ADC模块和整个录音的设备和文件流程；

1.7.2.2. 函数int norfs_enc_file_create(Encode_Control *obj)

该函数实现录音模式创建录音文件，内部包含开设备、挂载norfs文件系统和创建文件流程，其参数：
1、obj：录音句柄；
2、返回值:
    成功 返回0；
    失败 其他值；

1.7.2.3. 函数void encoder_stop(Encode_Control *obj)

该函数实现录音模式停止编码，内部会关闭编码、写文件流程和ADC模块；

1.7.2.4. 函数dec_obj norfs_enc_file_decode(Encode_Control obj， u16 dec_type)

该函数实现录音模式播放录音文件，内部包含开设备、挂载norfs文件系统和创建文件流程，其参数：
1、obj：录音句柄；
2、dec_type：解码格式；
3、返回值:
    成功 返回0；
    失败 其他值；