S1A单声道播放器

备注

前置知识：音频媒体文件调用方法和音频播放器的必需数据结构

简介

该场景库实现S1A文件解码并通过DSM单元播放，限8khz、16KHz单声道PCM编码的S1A文件使用。

特点

支持8khz、12khz、16khz采样，分别5、6、8，10、12、16kbps码率，单声道S1A文件解码

支持上采样播放，

支持DRC

支持淡入淡出；

支持变速，范围（0.5-2）

支持掐头播放（小文件组合播放）

API说明

int32_t player_s1a_init(player_init_parameter_t *init_parameter)

初始化S1A单声道播放器。

参数

init_parameter – player_init_parameter_t类型指针。详细信息参看 player_init_parameter_t

返回

播放器初始化后的SRAM空间已使用的总量(字节数)。

返回值

>0 – 播放器使用到sram的等高线
-1 – SRAM不足，播放器初始化失败。
<-1 – 绝对值为播放器初始化后使用到sram的等高线,负号表示tsps初始化失败

int32_t player_s1a_deinit()

单声道S1A播放器去初始化。

返回值

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

int32_t player_s1a_cmd(player_music_cmd_t cmd)

S1A控制命令。

参数

cmd – 支持预设枚举定义，见 player_music_cmd_t

返回值

0 – 播放器命令执行成功。
-1 – 播放器不存在。
-2 – 并未解码过，即刚初始化就调用stop。
-3 – 不支持的命令。

int32_t player_s1a_get_state(dec_info_t *dec_info)

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

参数

dec_info_t – 结构体 dec_info_t 指针，结构体定义见后文。

返回值

0 – 内部解码器状态获取成功。
-1 – 播放器不存在。

int32_t player_s1a_set_volume_scale(uint32_t scale)

设置播放器的音量缩放。

参数

scale – Q16.16格式无符号定点数，65536对应无缩放。

返回值

0 – 缩放因子设置成功。
-1 – 播放器不存在。

Note

当drc使能，最大音量16*65536；当drc失能，最大音量8*65536。

int32_t player_s1a_set_frame_hook(void (*func)(void *buffer_addr, int32_t *len))

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

参数

func – 钩子函数，包含两个参数，一个为解码音频地址，第二个为解码音频长度，宽度默认32bit。

返回值

0 – 钩子函数设置成功。
-1 – 播放器不存在。

int32_t player_s1a_set_end_hook(void (*func)())

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

参数

func – 钩子函数，要求无参无返回值。

返回值

0 – 钩子函数设置成功。
-1 – 播放器不存在。

int32_t player_s1a_set_stop_hook(void (*func)())

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

参数

func – 钩子函数，要求无参无返回值。

返回值

0 – 钩子函数设置成功。
-1 – 播放器不存在。

Note

当正常播，会在中断中调用;当已经播放完毕调用stop会在，stop命名后立马回调

int32_t player_s1a_append_upon_stop(player_init_parameter_t *preplay_info)

调用stop命令之前，指定stop完成之后播放的文件信息。因为stop命令会经行fade out，并不是立马停止播放。

参数

preplay_info – 文件信息，与初始化播放器参数一致。

返回值

0 – 设置成功。
-1 – 播放器不存在。

Note

调用stop命令之后，需要立马播放指定文件时，需要在stop命令前调用此函数。

int32_t player_s1a_set_loop_hook(int32_t (*func)(void))

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

参数

func – 回调函数。返回值 :结束循环标志，返回值不为0，将使单曲循环结束，使end_hook被调用

返回值

0 – 设置成功。
-1 – 播放器不存在。

Note

单曲循环不失能，该钩子函数不会被调用

int32_t player_s1a_get_bp_info(void *bp_info)

获取调用时，用于掐头的播放信息，

参数

bp_info – 存放用于掐头播放信息的地址。地址指向空间需要8byte，并对齐4

返回值

0 – 完成
-1 – 播放器不存在,或传入参数为空、或未对齐到4

使用方法

调用 player_s1a_init() 进行播放器初始化，播放器进入 Ready 状态。

调用 player_s1a_cmd(Player_CMD_Start)，开始播放，播放器进入 Playing 状态。

播放过程中可以随时调用 player_s1a_cmd(Player_CMD_Pause)/player_s1a_cmd(Player_CMD_Resume) 在 Playing 和 Paused 之间切换播放器状态。

播放过程自然结束或调用 player_s1a_cmd(Player_CMD_Stop) 都会使得播放器进入 Stopped 状态。

通过调用 player_s1a_init() 可以将播放器重新置于 Ready 状态。

否则，调用 player_s1a_deinit() 即可释放播放器资源占用(Cleared 状态)。

注意事项

源码中需要先定义在音频播放器的必须品中的：player_dec_sequence_t ,player_file_attribute_t ,player_music_cmd_t 枚举和 dec_info_t 结构体，否者编译错误

播放器运行过程占用DSM单元，指定的一路DMA3通道，以及软件中断(MSIP)。播放器去初始化后，资源占用将被释放。

提供两个s1a解码播放库，其中名字中不带-vfs为flash播放库，带有-vfs为同时支持sd卡和flash播放库。