全志R128芯片 基础组件开发指南——RTOS 多媒体解码
RTOS 多媒体解码
介绍 FreeRTOS 下如何使用 rtplayer 的接口来开发播放器应用程序，方便播放器开发人员快速正确地开发，以及播放器测试人员如何根据该文档对 rtplayer 播放器进行验证测试。
rtplayer 状态图
这张状态转换图清晰地描述了 rtlayer 的各个状态，也列举了主要的方法的调用时序，每种方法只能在一些特定的状态下使用，否则会出错。另外，只有在 Prepared、Started、Paused、Play‑backCompleted 这四种状态下可以进行 seekTo() 操作，并且 seekTo() 之后，状态不变。
Idle 状态
Idle 状态：当调用 player_init() 创建一个 rtplayer 或者调用了其 reset() 方法时，rtplayer 处于 idle状态。
Initialized 状态
这个状态比较简单，调用 setDateSource_url() 方法就进入 Initialized 状态，表示此时要播放的文件已经设置好了
Preparing 状态
调用 prepare() 函数还没返回或者是调用 prepareAsync() 并且还没收到 RTPLAYER_NOTIFY_PREPARED 这个回调消息的时候就处于 Preparing 状态
Prepared 状态
调用 prepare() 函数已经返回或者是调用 prepareAsync() 并且已经收到 RTPLAYER_NOTIFY_PREPARED 这个回调消息之后的状态就处于 Prepared 状态。在这个状态下说明所有的资源都已经就绪了，调用 start() 函数就可以播放了。
Started 状态
rtplayer 一旦 prepare 完成，就可以调用 start() 方法，这样 rtplayer 就处于 Started 状态，这表明 rtplayer 正在播放文件过程中。可以使用 XPlayerIsPlaying() 测试 rtplayer 是否处于了 Started 状态。如果播放完毕，而又设置了循环播放，则 rtplayer 仍然会处于 Started 状态。
Paused 状态
Started 状态下可以调用 pause_l() 方法暂停 rtplayer，从而进入 Paused 状态，rtplayer 暂停后再次调用 start() 则可以继续 TPlayer 的播放，转到 Started 状态。
Stopped 状态
Started 或者 Paused 状态下均可调用 stop() 停止 rtplayer，而处于 Stop 状态的 rtplayer 要想重新播放，需要通过 prepareAsync() 和 prepare() 回到先前的 Prepared 状态重新开始才可以。
PlaybackCompleted 状态
文件正常播放完毕，而又没有设置循环播放的话就进入该状态，并且会通过 RTPLAYER_NOTIFY_PLAYBACK_COMPLETE 这个消息回调给应用。此时可以调用 start() 方法重新从头播放文件，也可以 stop() 停止 rtplayer，或者也可以 seekTo() 来重新定位播放位置。
Error 状态
由于某种原因 rtplayer 出现了错误，就会进入该状态，并且会通过 RTPLAYER_NOTIFY_MEDIA_ERROR 这个消息回调给应用。如果 rtplayer 进入了 Error 状态，可以通过调用 reset() 来恢复，使得 rtplayer 重新返回到 Idle 状态。
End 状态
通过 plater_deinit() 的方法可以进入 End 状态，只要 rtplayer 不再被使用，就应当尽快将其 destroy 掉。
rtplayer 层接口
创建一个 rtplayer
函数原型
uint32_t player_init(void)
参数：
- 无
返回值：
- 成功返回 rtplayer 的指针，失败返回 NULL
销毁一个 rtplayer
函数原型
void player_deinit(void* handle)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针
返回值：
- 无
设置 rtplayer 的消息回调函数
函数原型
void registerCallback(void* handle, void* userData, player_callback_t fn)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针
- userData: 回调消息处理对象
- fn: 回调消息处理函数指针，需要由应用实现
返回值：
- 无
创建完 rtplayer 播放器之后，就要调用该函数设置回调消息处理函数。
设置播放文件的 url
可以是本地文件也可以是网络源
函数原型
status_t setDataSource_url(void* handle,void* userData, const char * url, int id)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针
- userData: 回调消息处理对象
- url: 需要播放的文件的 url
- id: 回调时使用的播放索引, 为 0 即可
返回值：
- 成功返回 0，失败返回‑1 或错误码
解析文件头部信息，获取元数据
函数原型
status_t prepare(void* handle)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针;
返回值：
- 成功返回 0，失败返回‑1 或错误码
异步解析文件头部信息，获取元数据
函数原型
status_t prepareAsync(void* handle)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针;
返回值：
- 成功返回 0，失败返回‑1
该函数是非阻塞函数，需要等到 RTPLAYER_NOTIFY_P‑ REPARED 消息回调之后才能调 start() 函数进行播放，而且 start() 函数不能在回调函数中调用
开始播放
函数原型
status_t start(void* handle)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针;
返回值：
- 成功返回 0，失败返回‑1
暂停播放
函数原型
status_t pause_l(void* handle)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针;
返回值：
- 成功返回 0，失败返回‑1
停止播放
函数原型
status_t stop(void* handle)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针
返回值：
- 成功返回 0，失败返回‑1
重置播放器
函数原型
status_t reset(void* handle)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针;
返回值：
- 成功返回 0，失败返回‑1
在任何状态下都可以调用该函数，每次播放不同的音频之前，都需要调用该函数重置播放器，另外，一般收到 RTPLAYER_NOTIFY_MEDIA_ERROR 这个消息的时候，也需要通过调用该函数来重置播放器。但是不能在回调函数中调用该函数，否则会出现死锁
跳播
函数原型
status_t seekTo(void* handle, int sec)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针
- sec: 跳播的位置，单位是：s
返回值：
- 成功返回 0，失败返回‑1
获取当前播放的位置
函数原型
status_t getCurrentPosition(void* handle, int * sec)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针;
- sec: 存放当前播放的位置值，单位：s
返回值：
- 成功返回 0，失败返回‑1
获取播放的文件总时长
函数原型
status_t getDuration(void* handle, int * sec)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针;
- sec: 存储文件总时长，单位：s
返回值：
- 成功返回 0，失败返回‑1
需要在 prepared 状态之后才可以调用该函数
获取播放的文件信息
函数原型
MediaInfo* getMediaInfo(void* handle)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针;
返回值：
- 成功返回 0，失败返回‑1
需要在 prepared 状态之后才可以调用该函数
设置循环播放模式
函数原型
status_t setLooping(void* handle, int loop)
参数：
- handle: 通过 player_init() 函数创建的 rtplayer 指针;
- loop:1 表示单曲循环，0 表示不会单曲循环
返回值：
- 成功返回 0，失败返回‑1
XPlayer 层播放接口
创建一个 XPlayer
函数原型
XPlayer* XPlayerCreate()
参数：
- 无
返回值：
- 成功: XPlayer 指针; 失败: NULL
设置 XPlayer 的回调通知
函数原型
int XPlayerSetNotifyCallback(XPlayer* p, XPlayerNotifyCallback notifier, void* pUserData)
参数：
- P：通过 XPlayerCreate 创建的 Xplayer 指针
- notifier：回调通知
- pUserData：应用程序传下来的自定义数据
返回值：
- 成功：XPlayer 指针；失败：NULL
Xplayer 将接收来自下层的回调通知，进行相应的操作
创建指向音频播放设备管理模块的指针，用于播放音频
函数原型
SoundCtrl* RTSoundDeviceCreate(int card)
参数：
- card:声卡序号0：default;1：sw:audio1;2:sw:audio2;3:sw:audio3;4:sw:audio4;5:sw:audio5
返回值：
- 成功：音频播放设备管理模块的指针；失败：NULL
创建指向音频播放设备管理模块的指针，用于播放音频
函数原型
int XPlayerSetDataSourceUrl(XPlayer* p, const char* pUrl, void* httpService, const CdxKeyedVectorT* pHeaders)
参数：
- pUrl：url 地址
- httpService：服务器信息
- pHeaders：头文件信息
返回值：
- 返回值: 成功：0；失败：‑1 或线程响应设置数据源命令的返回值或线程响应 xplayer prepare 命令的返回值
调用说明: 发送 SetDataSource 命令，获取需要播放的音频数据内容
将 XPlayer 置为准备状态, 解析头部信息，获取元数据
函数原型
int XPlayerPrepare(XPlayer* p)
参数：
- p：通过 XPlayerCreate 创建的 Xplayer 指针
返回值：
- 成功：线程响应异步 Prepare 命令的返回值；失败：NULL
该函数是阻塞函数，调用完返回之后就进入了 Prepared 状态，此时可调 XPlayerStart() 函数进行播放
将 XPlayer 置为异步准备状态
函数原型
int XPlayerPrepareAsync(XPlayer* p)
参数：
- p：通过 XPlayerCreate 创建的 XPlayer 指针
返回值：
- 成功：线程响应异步 Prepare 命令的返回值；失败：NULL
网络播放源一般采用 PrepareAsync，而不是 Prepare 命令，PrepareAsync 命令的返回值为 0 时说明响应成功，播放器准备工作已经完成可以开始播放，为‑1 时说明响应失败
将 XPlayer 置为启动状态
函数原型
int XPlayerStart(XPlayer* p)
参数：
- p：通过 XPlayerCreate 创建的 XPlayer 指针
返回值：
- 成功：线程响应 start 命令的返回值；失败：NULL
Start 命令的返回值为 0 时说明响应成功，为‑1 时说明响应失败
将 XPlayer 置为暂停状态
函数原型
int XPlayerPause(XPlayer* p)
参数：
- p：通过 XPlayerCreate 创建的 XPlayer 指针
返回值：
- 成功：线程响应 pause 命令的返回值；失败：NULL
在 XPlayer 处于 start 状态时可调用此接口，Pause 命令的返回值为 0 时说明响应成功，为‑1 时说明响应失败
将 XPlayer 置为停止状态
函数原型
int XPlayerStop(XPlayer* p)
参数：
- p：通过 XPlayerCreate 创建的 XPlayer 指针
返回值：
- 成功：返回 0；失败：返回‑1
重置 XPlayer
将相关变量复位，并销毁各模块，如音频解码模块、音频解码数据接收模块等
函数原型
int XPlayerReset(XPlayer* p)
参数：
- p：通过 XPlayerCreate 创建的 XPlayer 指针
返回值：
- 成功：线程响应 Reset 命令的返回值；失败：NULL
Reset 命令的返回值为 0 时说明响应成功，为‑1 时说明响应失败
获取节目时长
函数原型
int XPlayerGetDuration(XPlayer* p, int *msec)
参数：
- p：通过 XPlayerCreate 创建的 Xplayer 指针
- msec：保存节目时长
返回值：
- 成功：0；失败：‑1
在 XPlayer 处于 PREPARED、STARTED、PAUSED、STOPPED 或 COMPLETE 状态下才可调用此接口，否则操作无效
Seek 到给定的时间点
函数原型
int XPlayerSeekTo(XPlayer* p, int nSeekTimeMs)
参数：
- p：通过 XPlayerCreate 创建的 Xplayer 指针
- nSeekTimeMs：跳转的时间点
返回值：
- 成功：线程响应 Seek 命令的返回值；失败：NULL
如果跳转前播放处于暂停状态，则跳转后将保持在暂停状态
获取媒体文件的总时长
函数原型
int XPlayerGetDuration(XPlayer* p, int *msec)
参数：
- p：通过 XPlayerCreate 创建的 XPlayer 指针
- msec：保存媒体文件的总时长
返回值：
- 成功：0；失败：‑1
需要在 prepared 状态之后才可以调用该函数
获取当前的播放时间点（即播放位置）
在 XPlayer 处于 PREPARED、STARTED、PAUSED、STOPPED 或 COMPLETE 状态下才可调用此接口，否则操作无效，在 complete 状态下，可能会调用 prepare 方法并更改媒体信息，获取的播放时间以 ms 为单位
函数原型
int XPlayerGetCurrentPosition(XPlayer* p, int* msec)
参数：
- p：通过 XPlayerCreate 创建的 XPlayer 指针
- msec：保存当前的播放时间
返回值：
- 成功：0；失败：‑1
获取媒体信息
函数原型
MediaInfo* XPlayerGetMediaInfo(XPlayer* p)
参数：
- p：通过 XPlayerCreate 创建的 XPlayer 指针
返回值：
- 成功返回 0，失败返回‑1。如果失败，则 mediaInfo 指针为 NULL
需要在 prepared 状态之后才可以调用该函数
设置循环播放模式
函数原型
int XPlayerSetLooping(XPlayer* p, int loop)
参数：
- p：通过 XPlayerCreate 创建的 XPlayer 指针
- loop: 1: 表示单曲循环模式；0：表示不会循环
返回值：
- 无
查询是否正在播放
函数原型
int XPlayerIsPlaying(XPlayer* p)
参数：
- p：通过 XPlayerCreate 创建的 XPlayer 指针
返回值：
- 1：正在播放；0：未播放
销毁一个 XPlayer
函数原型
void XPlayerDestroy(XPlayer* p)
参数：
- p：通过 XPlayerCreate 创建的 XPlayer 指针
返回值：
- 无
播放器开发示例
- player_init() 创建一个播放器
- registerCallback() 设置消息回调函数
- setDataSource_url() 设置 url
- prepare() 或 prepareAsync() 解析头部信息，获取元数据，并根据元数据的信息初始化对应的解码器
- start() 播放 (注: 如果是用 prepareAsync() 函数，则需要等到 RTPLAYER_NOTIFY_PREPARED 消息回调之后才可以调用 start() 函数进行播放)
- 如果需要跳播，则可以调用 seekTo() 函数
- 如果需要暂停，则调用 pause_l() 函数进行暂停
- 如果需要停止，则可以调用 stop() 或 reset() 函数进行停止 (注：建议用 reset() 函数进行停止，因为任何状态下都可以调用 reset() 函数)
- 如果需要播放下一个或其他的，则可以先调用 reset() 函数使播放器进入 idle 状态，然后再重复 (3)(4)(5) 的步骤
#include [data]\n" );
return -1;
}
int data = 0;
if(argc==3)
data = atoi(argv[2]);
rtplayer_send_cmd(mRTplayerMq, argv[1][0], data);
return 0;
}
FINSH_FUNCTION_EXPORT_CMD(cmd_rtplayer_controller, rtpc, control the rtplayer);
注意事项
-
目前 rtplayer/xplayer 仅支持音频解码，且不支持对视频文件进行解封装，因此 rtplayer 播放器应用只支持音频文件的播放。
-
void registerCallback(void* handle, void* userData, player_callback_t fn)函数必须要调用，而且 fn 不能为 NULL。 -
回调函数中不能调用 rtplayer 的任何一个接口，如：reset、stop、start 等这些接口不能在回调函数中调用。
-
播放本地文件的情况下，set url 时，XPlayer 会进行一次同步 prepare，用于提前获取信息给 parser，因此异步 prepare 前，应对 XPlayerSetDataSourceUrl 的返回值进行判断。
-
改变播放器的状态，应满足状态图中的对应的函数调用流程，如播放结束后需要播放下一首歌，应调用 reset 清空信息，进入 idle 状态，再调用 setDataSource_Url 进行填充下一首歌到播放器中
-
采取异步 prepare 时（prepareAsync），应注意添加信号量进行同步。
原贴链接：https://bbs.aw-ol.com/topic/4374/
资源获取、问题讨论可以到全志在线开发者社区进行：https://www.aw-ol.com
全志及开发者最新动态可以关注全志在线微信公众号