.. _vorbis-player:

VORBIS单声道播放器
======================

.. _音频媒体文件调用方法: media-file.html

.. note::
   
   前置知识： :ref:`media-file-format` 和 :ref:`player-parameter-structure`

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

该场景库实现OGG VORBIS文件解码并通过DSM单元播放，支持12KHZ,16KHZ,24KHZ单声道PCM编码的VIRBIS文件使用。

特点
-------------------------
 - 支持8KHZ,12KHZ,16KHZ,24KHZ采样率，8k-100kbsp码率，单声道vorbis文件解码；其中8KHZ最低码率8kbps，12KHZ最低码率12kbps，16、24KHZ最低码率16kbps
 - 支持DRC ；
 - 支持淡入淡出；
 - 支持vfs方式访问
 - 支持快进快退


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


.. c:function:: int32_t player_vorbis_init(player_init_parameter_t *init_parameter)

  初始化单声道vorbis播放器。

  :param init_parameter: player_init_parameter_t类型指针。详细信息参看 player_init_parameter_t
  :returns: 播放器初始化后的SRAM空间已使用的总量(字节数)。
  :retval >0: 播放器使用到sram的等高线
  :retval -1: SRAM不足，播放器初始化失败。
  :retval -2: 资源文件非vorbis文件。
  :retval -4: 掐头去尾参数不合适。
  :note: 初始化结构体player_init_parameter_t参数中file_info发生变化，当非vfs版本，需要file_info指向存放vorbis和codebook文件地址的指针；对于vfs版本，需要file_info指向codebook文件地址。
  :note: 无论是否使用vfs解码库，codebook只能存放在内部flash。

.. c:function:: int32_t player_vorbis_deinit()

  单声道播放器去初始化。

  :retval  >0: 播放器释放sram后的地址
  :retval -1: 播放器不存在。

.. c:function:: int32_t player_vorbis_cmd(player_music_cmd_t cmd)

  控制命令。

  :param cmd: 支持预设枚举定义，见 player_music_cmd_t
  :retval  0: 播放器命令执行成功。
  :retval -1: 播放器不存在。
  :retval -2: 并未解码过，即刚初始化就调用stop。
  :retval -3: 不支持的命令。



.. c:function:: int32_t player_vorbis_get_status(dec_info_t *dec_info)

  获取播放器内部解码器状态信息。

  :param dec_info_t: 结构体 dec_info_t 指针，结构体定义见后文。 
  :retval  0: 内部解码器状态获取成功。
  :retval -1: 播放器不存在。

.. c:function:: int32_t player_vorbis_skip(int32_t skip_len);

  从当前播放位置向前后跳动指定文件长度

  :param skip_len: 跳动文件长度，in byte
  :retval  0: 跳转成功。
  :retval -1: 播放器不存在。
  :note: 可能需要较长时间

.. c:function:: int32_t player_vorbis_set_volume_scale(uint32_t scale)

  设置播放器的音量缩放。

  :param scale: Q16.16格式无符号定点数，65536对应无缩放。
  :retval  >=0: 设定的音量值。
  :retval -1: 播放器不存在。
  :note: 当drc使能，最大音量16*65536；当drc失能，最大音量8*65536。

.. c:function:: int32_t player_vorbis_set_frame_hook( void (*func)(void* buffer_addr,int32_t *len) )

  可选配钩子函数，配置每帧解码完成钩子函数

  :param func: 钩子函数，包含两个参数，一个为解码音频地址，第二个为解码音频长度，宽度默认32bit。
  :retval  0: 钩子函数设置成功。
  :retval -1: 播放器不存在。

.. c:function:: int32_t player_vorbis_set_end_hook(void (*func)())

  可选配钩子函数，配置后在曲目播放自然结束后触发调用。

  :param func: 钩子函数，要求无参无返回值。
  :retval  0: 钩子函数设置成功。
  :retval -1: 播放器不存在。

.. c:function:: int32_t player_vorbis_set_stop_hook(void (*func)())

  可选配钩子函数，设置播放一首音乐主动停止钩子函数

  :param func: 钩子函数，要求无参无返回值。
  :retval  0: 钩子函数设置成功。
  :retval -1: 播放器不存在。
  :note: 当正常播，会在中断中调用;当已经播放完毕调用stop命名后立马回调

.. c:function:: int32_t player_vorbis_set_loop_hook( int32_t (*func)(void) )

  设置播放一首音乐在单曲循环切换时的钩子函数，一首音乐播放使能了单曲循环，
  在循环切换使调用该注册的钩子函数

  :param func: 回调函数。返回值 :结束循环标志，返回值不为0，将使单曲循环结束，使end_hook被调用
  :retval  0: 设置成功。
  :retval -1: 播放器不存在。
  :note: 单曲循环不失能，该钩子函数不会被调用

使用方法
-------------------------

 .. image:: ../../_static/kiwi-mp3-16k-fsm.png
  :align: center
 
 1. 调用 player_vorbis_init() 进行播放器初始化，播放器进入 Ready 状态。
 2. 调用 player_vorbis_cmd(`Player_CMD_Start`)，开始播放，播放器进入 Playing 状态。
 3. 播放过程中可以随时调用 player_vorbis_cmd(`Player_CMD_Pause`)/player_vorbis_cmd(`Player_CMD_Resume`) 在 Playing 和 Paused 之间切换播放器状态。
 4. 播放过程自然结束或调用 player_vorbis_cmd(`Player_CMD_Stop`) 都会使得播放器进入 Stopped 状态。
 5. 通过调用 player_vorbis_init() 可以将播放器重新置于 Ready 状态。
 6. 否则，调用 player_vorbis_deinit() 即可释放播放器资源占用(Cleared 状态)。

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

 1. 源码中需要先定义在音频播放器的必需数据结构中的 player_dec_sequence_t ,player_file_attribute_t ,player_music_cmd_t 枚举和 dec_info_t 结构体，否者编译错误
 2. 播放器运行过程占用DSM单元，指定的一路DMA3通道，以及软件中断(MSIP)。播放器去初始化后，资源占用将被释放。
 3. 初始化player_vorbis_init()调用，参数有所变化，初始化结构体player_init_parameter_t参数中file_info发生变化，当非vfs版本，需要file_info指向存放vorbis和codebook文件地址的指针；对于vfs版本，需要file_info指向codebook文件地址。
 4. 无论是否使用vfs解码库，codebook只能存放在内部flash。