.. _mbox_flash应用篇:    

小音箱应用篇（mbox_flash）
=====================================

简介
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    2025年8月分布的AD23N-release_V1.0.0 SDK支持小音箱应用（mbox_flash），基本功能与AD16、AC104 SDK一致，包含以下应用模式:

        - 1、音乐模式（MUSIC_MODE，支持播放内置flash、SD的音源文件）
        - 2、linein模式（AUX_MODE，支持样机通过linein线连接电脑，电脑播放的音乐可以通过样机播出声音）
        - 3、录音模式（RECORD_MODE，支持MP3、UMP3和A格式文件编码，支持录音到SD卡或内置flash）
        - 4、midi解码模式（MIDI_DEC_MODE，支持播放midi格式的文件）
        - 5、midi琴模式（MIDI_KEYBOARD_MODE）
        - 6、多路解码模式（SIMPLE_DEC_MODE，公版SDK默认支持 F1A格式+A格式 两路解码，用户可仿照修改实现更多路解码）
        - 7、扩音模式（LOUDSPEAKER_MODE，可串联多种音效，详细见speaker_api.c）
        - 8、空闲模式（IDLE_MODE，仅用于给开发者提供示例，没有实际功能）

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


音乐解码模式(MUSIC_MODE)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    | 音乐解码模式主要功能为解码播歌，可以实现内置flash，sd卡随意切换来播放支持的解码格式音乐文件；
    | 用户可通过按键来暂停/播放，上下一曲，切换播放设备等等操作；
    | 涉及的文件目录：app\\ src\\ mbox_flash\\ music；

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

普通解码模式(SIMPLE_DEC_MODE)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    | 普通解码模式主要功能为解码播歌，是最简单实现解码播放的应用，目的是为了让用户更容易了解解码播放的整个流程。
    | 用户可通过按键来暂停/播放，上下一曲，切换播放设备等等操作。
    | 涉及的文件目录：app\\ src\\ mbox_flash\\ simple_decode；
    | 下面简要介绍主要涉及函数：


函数u32 simple_dev_fs_mount(play_control \*ppctl)
********************************************************************************************

    此函数是多路解码挂载设备和SYD文件系统，其中参数： ::

        1、ppctl：音乐播放器句柄指针；
        2、返回值：
            成功 返回0；
            失败 错误值可查看errno-base.h；

函数u32 simple_dev_fs_close(play_control \*ppctl)
********************************************************************************************

    此函数实现多路解码释放文件、文件系统句柄，并关闭设备；释放的句柄分别是结构体play_control中的成员pfile，pfs以及device，其中参数： ::

        1、ppctl：音乐播放器句柄指针；
        2、返回值：0；

函数u32 simple_play_file_byindex(play_control \*ppctl)
********************************************************************************************

    此函数实现多路解码按文件序号播放指定文件，播放的文件序号使用结构体play_control中的成员findex，其中参数： ::

        1、ppctl：音乐播放器句柄指针；
        2、返回值：0；

5.4 函数u32 get_decoder_status(dec_obj \*obj)
********************************************************************************************

    此函数实现获取多路解码当前的状态，分别有播放停止（MUSIC_STOP）、播放暂停（MUSIC_PAUSE）以及播放中（MUSIC_PLAY）三种状态，其中参数： ::

        1、obj：解码句柄；
        2、返回值：返回当前解码器播放状态；

函数static bool simple_switch_device(play_control \*ppctl)
********************************************************************************************

    此函数实现多路解码切换下一个设备，函数中需要停止解码器，关闭上次播放的文件与设备，重新初始化下一个需要播放的设备并开始解码，其中参数： ::

        1、ppctl：音乐播放器句柄指针；
        2、返回值：
            成功 true；
            失败 false；

函数static bool simple_next_dir(play_control \*ppctl)
********************************************************************************************

    此函数实现多路解码切换下一个dir文件夹，函数中需要停止解码器，关闭上次播放的文件与设备，重新初始化下一个需要播放的设备并开始解码，其中参数： ::

        1、ppctl：音乐播放器句柄指针；
        2、返回值：
            成功 true；
            失败 false；


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

.. _录音模式(RECORD_MODE):

录音模式(RECORD_MODE)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    | 录音模式主要功能为录音并播放录音文件。
    | 用户可通过按键来开始/播放录音，变速变调等操作；
    | 涉及的文件目录：apps\\ app\\ src\\ mbox_flash\\ record；


函数int encode_start(Encode_Control \*obj)
********************************************************************************************

    | 此函数实现配置AUDIO_ADC采样率，并识别当前在线设备进行编码；
    | SD卡/U盘挂载fat文件系统录制标准mp2音频，内置flash挂载norfs文件系统录制ump3或a格式音频；
    
    其中参数：::

        1、obj：编码器句柄指针；
        2、返回值：
            成功 返回0；
            失败 错误值可查看errno-base.h；


函数void encode_stop(Encode_Control \*obj)
********************************************************************************************

    此函数实现停止编码器工作，并保存录制完成的文件，其中参数： ::

        1、obj：编码器句柄指针；
        2、返回值：无；

函数int fatfs_enc_file_create(Encode_Control \*obj)
********************************************************************************************

    此函数实现打开SD卡/U盘设备，并创建固定命名格式的文件，创建的文件名遵循”AD16****.mp3”格式，可录制文件”AD160000.mp3”至”AD169999.mp3”，文件系统能识别最大后缀序号，并自增作为新建文件名，其中参数： ::

        1、obj：编码器句柄指针；
        2、返回值：
            成功 返回0；
            失败 错误值可查看errno-base.h；

函数dec_obj \*fatfs_enc_file_decode(Encode_Control \*obj, u16 dec_type)
********************************************************************************************

    此函数实现播放SD卡/U盘设备录制的标准mp2编码文件，其中参数： ::

        1、obj：编码器句柄指针；
        2、dec_type：解码格式、音效选择；
        3、返回值：
            成功 返回解码器句柄；
            失败 返回NULL；

函数int norfs_enc_file_create(Encode_Control \*obj)
********************************************************************************************

    此函数实现内置flash挂载norfs文件系统录制ump3/a格式音频，norfs为循环管理的可读写文件系统，写满后会自动覆盖最开始的数据，该文件系统只能用文件序号打开文件，创建新文件时，会返回最新文件序号，其中参数： ::

        1、obj：编码器句柄指针；
        2、返回值：
            成功 返回0；
            失败 错误值可查看errno-base.h；

函数dec_obj \*norfs_enc_file_decode(Encode_Control \*obj, u16 dec_type)
********************************************************************************************

    此函数实现播放内置flash录制的ump3/a编码文件，其中参数： ::

        1、obj：编码器句柄指针；
        2、dec_type：解码格式、音效选择；
        3、返回值：
            成功 返回解码器句柄；
            失败 返回NULL；


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

.. _linein模式(AUX_MODE):

linein模式(AUX_MODE)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    | Linein模式支持数字LINEIN模式。
    | 用户在开发板上只需把AUXL 和 AUXR 一并连接到 PA4即可实现 PC linein 连接小机播放PC端音频（具体io更好可以在cpu_config.c里的audio_adc_aux_input_mode替换）；
    | 涉及的文件目录：apps\\ app\\ src\\ mbox_flash\\ linein；

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

.. _MIDI模式(MIDI_MODE):

MIDI模式(MIDI_MODE)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    | MIDI模式支持播放MIDI格式文件 并 叠加a文件解码播放。
    | 用户在通过按键来切换midi模式，上下一曲等操作；
    | 涉及的文件目录：app\\ src\\ mbox_flash\\ midi_dec；

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

.. _MIDI琴模式(MIDI_CTRL_MODE):

MIDI琴模式(MIDI_CTRL_MODE)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    | MIDI琴模式支持通过函数驱动midi解码，该应用依赖我司自定义的mid音色库，用户可通过我司mid工具进行转换，详情请看《JLmidi工具使用说明》;
    | 用户在通过按键来模拟乐器打击，弯音轮等操作；
    | 涉及的文件目录：app\\ src\\ mbox_flash\\ midi_keyoboard；

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


.. _扩音模式(LOUDSPEAKER_MODE): 

扩音模式(LOUDSPEAKER_MODE)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    | 扩音模式为mic采集音频数据，串联一个或多个音效算法并将处理后的数据输出至DAC出声的功能，常用于扩音喇叭等应用；
    | 扩音模式支持多种音效串联，但需要注意各音效之间是否overlay同一块区域，具体可观察app_ld.c里每个音效段是否为同级关系，是则不能同时开该音效。
    | 目前可串联的音效有：

        - 1）speed实时变调音效；
        - 2）echo混响音效；
        - 3）voice_pich变音音效；
        - 4）notcch_howling陷波啸叫抑制音效；
        - 5）pitchshift_howling移频啸叫抑制音效；
        - 6）pcm_eq音效；

    | 以上音效可在speaker._api.c文件中通过link函数形式串联到数据流中；
    | 涉及的文件目录：apps\\ app\\ src\\ mbox_flash\\ loudspeaker；

函数void audio_adc_speaker_start(u32 sr)
********************************************************************************************

    此函数实现启动mic直通喇叭功能，其中参数： ::

        1、sr：speaker工作采样率，可选的采样率根据芯片的音频硬件支持情况来决定；