.. _recorder-lib:

录音机
=========================

简介
-------------------------

SPV1x的录音库，提供音频录制和压缩存储功能。该录音库有如下特性：

 1. 音频采样率支持16KHz和24KHz。
 2. 使用MP3编码器压缩音频，压缩后的音频码率支持8kbps、16kbps、24kbps、32kbps、40kbps、48kbps、56kbps、64kbps。
 3. 向应用提供回调函数接口：录音开始回调、录音结束回调、帧采集完成回调、VAD计算完成回调。
 4. 提供音频回溯功能，在16kbps码率下，最长支持1秒的音频回溯。

相关的数据结构说明
-------------------------

.. c:enum:: recorder_lowpass_t

  不同码率下，低通滤波器截止频率配置。

  - *Recommended_Lowpass_for_8kbps*: 配置8kbps下，低通滤波器的截止频率。
  - *Recommended_Lowpass_for_16kbps*: 配置16kbps下，低通滤波器的截止频率。
  - *Recommended_Lowpass_for_24bps*: 配置24kbps下，低通滤波器的截止频率。
  - *Recommended_Lowpass_for_32kbps*: 配置32kbps下，低通滤波器的截止频率。
  - *Recommended_Lowpass_for_40kbps*: 配置40kbps下，低通滤波器的截止频率。
  - *Recommended_Lowpass_for_48kbps*: 配置48kbps下，低通滤波器的截止频率。
  - *Recommended_Lowpass_for_56kbps*: 配置56kbps下，低通滤波器的截止频率。
  - *Recommended_Lowpass_for_64kbps*: 配置64kbps下，低通滤波器的截止频率。

.. c:enum:: recorder_sample_rate_t

  录音的音频采样率选择。

  - *Sample_Rate_16khz*: 选择16KHz采样率。
  - *Sample_Rate_24khz*: 选择24KHz采样率。

.. c:enum:: recorder_bitrate_t

  录音编码后的码率选择。

  - *Bitrate_8Kbps*: 选择8kbps码率，1秒钟的录音将占用1KB flash空间。
  - *Bitrate_16Kbps*: 选择16kbps码率，1秒钟的录音将占用2KB flash空间。
  - *Bitrate_24Kbps*: 选择24kbps码率，1秒钟的录音将占用3KB flash空间。
  - *Bitrate_32Kbps*: 选择32kbps码率，1秒钟的录音将占用4KB flash空间。
  - *Bitrate_40Kbps*: 选择40kbps码率，1秒钟的录音将占用5KB flash空间。
  - *Bitrate_48Kbps*: 选择48kbps码率，1秒钟的录音将占用6KB flash空间。
  - *Bitrate_56Kbps*: 选择56kbps码率，1秒钟的录音将占用7KB flash空间。
  - *Bitrate_64Kbps*: 选择64kbps码率，1秒钟的录音将占用8KB flash空间。

.. c:struct:: recorder_init_parameter_t
  
  录音初始化参数结构体。

   .. c:member:: uint32_t flash_addr

      录音数据在flash中的起始地址。
   
   .. c:member:: uint32_t flash_size

      录音数据最大可占用的flash空间。

   .. c:member:: recorder_bitrate_t bitrate_kbps

      录音码率选择。

   .. c:member:: recorder_sample_rate_t sample_rate

      录音采样率选择。

   .. c:member:: recorder_lowpass_t lowpass

      录音低通滤波器截止频率选择。

   .. c:member:: uint32_t mic_single_end : 1

      mic_single_end ：  flags结构体成员。为0选择差分麦克风模式。为1选择单端麦克风模式。

API说明
-------------------------

.. c:function:: uint32_t recorder_init(recorder_init_parameter_t *recorder_init_parameter)

  录音库初始化。

  :param recorder_init_parameter: 录音初始化参数结构体 。。
  :returns: 录音库占用的SRAM大小(字节数)，该值用于评估项目内存使用情况。

.. c:function:: void recorder_set_start_hook(void (*start)(void))

   设置录音开始回调函数。

   :param start: 录音开始回调函数指针。
   :returns: 无
   :note: 用户调用 `recorder_start()` 后，录音并不是立即开始。因此录音开始回调函数的执行会相对 `recorder_start()` 有一定的延迟。

.. c:function:: void recorder_set_stop_hook(void (*stop)(void))

   设置录音结束回调函数。

   :param stop: 录音结束回调函数指针。
   :returns: 无
   :note: 用户调用 `recorder_stop()` 后，录音并不是立即结束。因此录音结束回调函数的执行会相对 `recorder_stop()` 有一定的延迟。

.. c:function:: void recorder_set_vad_hook(void (*vad)(uint32_t *energy,uint32_t len))

   设置VAD计算完成回调函数。

   :param vad: VAD计算完成回调函数指针。该回调函数带2个形参，energy指向音频能量值数组，len表示音频能量值数组的长度。
   :returns: 无

.. c:function:: void recorder_set_frame_hook(void (*frame)(int16_t * pcm,uint32_t len))

   设置帧采集完成回调函数。

   :param frame: 帧采集完成回调函数指针。该回调函数第一个参数为当前帧PCM数据的内存地址，第二个参数为PCM数据的长度（采样点数目）。
   :returns: 无

.. c:function:: void recorder_deinit(void)

  录音库去初始化。

  :returns: 无

.. c:function:: void recorder_start(uint32_t pre_time_ms)

   请求开始录音。

   :param pre_time_ms: 录音需要回溯的时间，0ms ≤ pre_time_ms ≤ 1000ms。
   :returns: 无
   :note: 录音库在初始化后就开始缓存音频数据，在16kbps码率下，最多缓存1秒的音频，码率增大时，缓存的时间会线性缩短。如果在初始化录音库后立即开始录音，则没有音频数据可以回溯。

.. c:function:: void recorder_stop(void)

   请求停止录音。

   :returns: 无


录音数据在flash中的存放
-------------------------

 .. image:: ../../_static/recorder_data_area.png
  :align: center

 1. 录用功能使用的flash区域由调用 `recorder_init()` 时，传入的recorder_init_parameter中的参数 `flash_addr` 和 `flash_size` 决定。
 2. flash区域的第一个word（0~4字节，小端格式）保存着实际录音数据的长度信息。
 3. flash区域的第二个word（4~8字节，小端格式）保存着 `RECORDER_MAGIC` 常数，其值为0x00444352。该值用于确定flash区域是否存在有效的录音数据。
 4. 从第9字节开始，用于存放MP3编码后的录音数据。

录音库使用方法
-------------------------

 1. 确认ADC和麦克风引脚已初始化就绪。ADC和麦克风引脚的初始化见本章注意事项。
 2. 调用 `recorder_init()` 初始化录音功能需要用到的资源，并传入用于保存录音数据的flash区域参数以及码率。
 3. 根据需求，设置对应的回调函数。未设置的回调函数默认为NULL，录音库会跳过对NULL回调函数的调用。
 4. 调用 `recorder_start()` 开始录音：SPV1x对ADC采集的音频数据进行编码压缩，然后写入flash。
    当指定长度的flash空间用尽后，SPV1x自动停止录音。
 5. 用户也可以根据场景需求，主动调用 `recorder_stop()` 手动停止录音。
 6. 如果需要进行VAD录音，用户可以在VAD回调函数中对音频帧的能量参数进行判断，并决定是否调用 `recorder_start()` 启动录音或者调用 `recorder_stop()` 停止录音。
 7. 调用 `recorder_deinit()` 去初始化：释放录音功能需要用到的资源，结束录音机场景。

注意事项
-------------------------

 1. 录音功能需要配合SPV1x的 `事件驱动型用户程序框架`_ 使用。
 2. 录音功能用会用到一些外设资源，用户应避免这些资源的使用，以免因为资源冲突导致录音功能无法正常工作。录音用到外设资源如下：

   a. ADC：采集音频数据。
   b. DMA：通道3，录音过程中音频数据的搬运。
   c. 软件中断（MSIP）：音频数据的编码和其他处理。
   d. SPI0：操作flash进行录音数据的保存。
   e. GPIO10~13：作为SPI0的功能引脚。

 3. 录音开始回调、录音结束回调、帧采集完成回调、VAD计算完成回调都在中断函数中调用，因此回调函数的内容需要简短。
 4. flash的擦写时间对录音功能影响较大，普冉flash的擦除时间比较能满足录音功能的需求。
 5. 使用录音功能前，需要先调用 `adc_sys_init()` 初始化ADC，以及调用 `adc_diff_mic_pin_init()` （差分麦克风接线方式）或调用 `adc_single_end_mic_pin_init()` （单端麦克风接线方式）设置麦克风相关引脚的复用功能。
    麦克风相关引脚首次初始化后，其引脚连接的相关电容需要一定的时间（约300~500ms）进行充电并稳定。因此在应用中，建议麦克风引脚初始化后，就一直保持其为初始化后的状态，不再对其进行去初始化。

 .. _事件驱动型用户程序框架: ../../user-guide/user-fw-design.html