VideoPlayerService

Class Summary

OHOS::VideoPlayerService

视频播放服务类，提供视频播放、暂停、恢复、停止、跳转及状态查询等控制能力

• 构造：VideoPlayerService(std::string uri, bool isPureVideo)、VideoPlayerService(int32_t fd, uint64_t offset, bool isPureVideo)

• 成员函数：

  接口名称	功能简述
  VideoPlayerService	通过 URI 构造视频播放服务对象
  VideoPlayerService	通过文件描述符构造视频播放服务对象
  Play	开始播放视频
  Stop	停止播放视频
  Pause	暂停播放视频
  Resume	恢复播放视频
  SeekTo	跳转到指定时间位置
  GetCurrentTime	获取当前播放时间
  GetVideoWidth	获取视频宽度
  GetVideoHeight	获取视频高度
  GetDuration	获取视频总时长
  SetPlaybackSpeed	设置播放倍速
  GetPlaybackSpeed	获取当前播放倍速
  IsPlaying	查询是否正在播放
  IsPaused	查询是否处于暂停状态
  IsLooping	查询是否处于循环播放模式
  EnableSingleLooping	设置单循环播放模式
  SetSurface	设置视频渲染 Surface
  SetUILabelButton	设置 UI 标签按钮控件
  GetDumpInfo	获取播放器调试信息

• 使用包含头文件：#include "video_player_service.h"

• 声明头文件：middleware/services/media/foundation/service/video_player_service/include/video_player_service.h
• 公有运算符：无
• 继承关系：无
• 嵌套类型：无
• 模板形参：无

Functions

OHOS::VideoPlayerService

VideoPlayerService(uri)

VideoPlayerService(std::string uri, bool isPureVideo)

功能说明

• 通过 URI 地址构造视频播放服务对象，初始化内部 MediaVideoPlay 实例
• URI 可指向本地文件路径或网络流地址
• 构造时内部通过 new (std::nothrow) 创建 MediaVideoPlay 对象，若内存不足则内部指针为 nullptr

入参

名称	参数类型	详细说明	约束取值范围
uri	std::string	视频源 URI 地址，入参只读，不修改所指对象	有效的本地文件路径或网络 URI
isPureVideo	bool	是否为纯视频模式，入参只读	true：纯视频模式；false：音视频模式

VideoPlayerService(fd)

VideoPlayerService(int32_t fd, uint64_t offset, bool isPureVideo)

功能说明

• 通过文件描述符和偏移量构造视频播放服务对象，初始化内部 MediaVideoPlay 实例
• 适用于已打开的文件描述符场景，支持从指定偏移位置开始播放
• 构造时内部创建 MediaVideoPlay 对象，绑定文件描述符与偏移量

入参

名称	参数类型	详细说明	约束取值范围
fd	int32_t	文件描述符，入参只读	有效的已打开文件描述符，大于 0
offset	uint64_t	文件偏移量，入参只读	0 ~ 文件大小范围内
isPureVideo	bool	是否为纯视频模式，入参只读	true：纯视频模式；false：音视频模式

Play

int32_t Play(void)

功能说明

• 核心用途：启动视频播放，内部创建播放线程并请求音频焦点
• 设计目的：提供视频播放的启动入口，支持同步与异步退出模式
• 使用场景：视频开始播放、恢复播放后的首次启动

前置条件

• VideoPlayerService 对象已通过构造函数完成构造且内部 MediaVideoPlay 实例有效
• 当前未处于播放状态（isEntered_ 为 false）

返回值

• 返回类型：int32_t

返回播放操作结果

返回值	触发场景
MEDIA_OK(0)	播放启动成功
MEDIA_ERR(-3)	内部播放器实例为空或播放线程创建失败

Stop

int32_t Stop(void)

功能说明

• 核心用途：停止视频播放，内部停止播放器并释放资源
• 设计目的：提供视频播放的停止控制接口
• 使用场景：视频播放结束、用户主动停止播放

前置条件

• VideoPlayerService 对象已通过构造函数完成构造且内部 MediaVideoPlay 实例有效

返回值

• 返回类型：int32_t

返回停止操作结果

返回值	触发场景
MEDIA_OK(0)	停止成功或视频已处于停止状态
MEDIA_ERR(-3)	内部播放器实例为空

Pause

int32_t Pause(void)

功能说明

• 核心用途：暂停当前视频播放，保持播放位置
• 设计目的：提供视频播放的暂停控制接口，暂停后可调用 Resume 恢复
• 使用场景：用户主动暂停、音频焦点中断暂停

前置条件

• VideoPlayerService 对象已通过构造函数完成构造且内部 MediaVideoPlay 实例有效
• 当前处于播放状态（isEntered_ 为 true）且未处于停止、完成或暂停状态

返回值

• 返回类型：int32_t

返回暂停操作结果

返回值	触发场景
MEDIA_OK(0)	暂停成功
MEDIA_ERR(-3)	内部播放器实例为空或当前状态不允许暂停

Resume

int32_t Resume(void)

功能说明

• 核心用途：恢复暂停的视频播放，从暂停位置继续播放
• 设计目的：提供视频播放的恢复控制接口，与 Pause 配对使用
• 使用场景：用户主动恢复播放、音频焦点恢复后继续播放

前置条件

• VideoPlayerService 对象已通过构造函数完成构造且内部 MediaVideoPlay 实例有效
• 当前处于暂停状态（isPause_ 为 true）且未处于停止、完成状态

返回值

• 返回类型：int32_t

返回恢复操作结果

返回值	触发场景
MEDIA_OK(0)	恢复成功
MEDIA_ERR(-3)	内部播放器实例为空或当前状态不允许恢复

SeekTo

int32_t SeekTo(int64_t mSeconds)

功能说明

• 核心用途：将视频播放位置跳转到指定时间点
• 设计目的：提供视频播放的随机访问能力，支持快进快退
• 使用场景：进度条拖拽、章节跳转、快进快退

入参

名称	参数类型	详细说明	约束取值范围
mSeconds	int64_t	目标跳转时间，单位为毫秒，入参只读	0 ~ 视频总时长

前置条件

• VideoPlayerService 对象已通过构造函数完成构造且内部 MediaVideoPlay 实例有效

返回值

• 返回类型：int32_t

返回跳转操作结果

返回值	触发场景
MEDIA_OK(0)	跳转成功
MEDIA_ERR(-3)	内部播放器实例为空或跳转失败

GetCurrentTime

int32_t GetCurrentTime(int64_t *currentTime)

功能说明

• 核心用途：获取当前视频播放位置的时间
• 设计目的：提供播放进度查询能力
• 使用场景：进度条更新、播放时间显示

入参

名称	参数类型	详细说明	约束取值范围
currentTime	int64_t *	出参指针，由被调用方写入当前播放时间（毫秒），不可为 nullptr	非 nullptr，指向有效内存

出参

名称	数据类型	输出说明
currentTime	int64_t	当前播放位置时间，单位为毫秒

前置条件

• VideoPlayerService 对象已通过构造函数完成构造且内部 MediaVideoPlay 实例有效
• currentTime 指针不为 nullptr

返回值

• 返回类型：int32_t

返回查询操作结果

返回值	触发场景
MEDIA_OK(0)	获取成功
MEDIA_ERR(-3)	内部播放器实例为空或获取失败

GetVideoWidth

int32_t GetVideoWidth(void)

功能说明

• 核心用途：获取视频画面的宽度
• 设计目的：提供视频分辨率查询能力
• 使用场景：视频渲染布局、分辨率适配

返回值

• 返回类型：int32_t

返回视频宽度值

返回值	触发场景
0	当前实现固定返回 0

GetVideoHeight

int32_t GetVideoHeight(void)

功能说明

• 核心用途：获取视频画面的高度
• 设计目的：提供视频分辨率查询能力
• 使用场景：视频渲染布局、分辨率适配

返回值

• 返回类型：int32_t

返回视频高度值

返回值	触发场景
0	当前实现固定返回 0

GetDuration

int32_t GetDuration(int64_t &duration)

功能说明

• 核心用途：获取视频总时长
• 设计目的：提供视频时长查询能力
• 使用场景：进度条总长计算、播放时间显示

入参

名称	参数类型	详细说明	约束取值范围
duration	int64_t &	出参引用，由被调用方写入视频总时长（毫秒）	有效引用

出参

名称	数据类型	输出说明
duration	int64_t	视频总时长，单位为毫秒

前置条件

• VideoPlayerService 对象已通过构造函数完成构造且内部 MediaVideoPlay 实例有效

返回值

• 返回类型：int32_t

返回查询操作结果

返回值	触发场景
MEDIA_OK(0)	获取成功
MEDIA_ERR(-3)	内部播放器实例为空或获取失败

SetPlaybackSpeed

int32_t SetPlaybackSpeed(PlaybackRateMode mode)

功能说明

• 核心用途：设置视频播放倍速
• 设计目的：提供倍速播放控制接口
• 使用场景：快进播放、慢放回放

入参

名称	参数类型	详细说明	约束取值范围
mode	PlaybackRateMode	播放倍速模式，入参只读	PlaybackRateMode 枚举值

返回值

• 返回类型：int32_t

返回设置操作结果

返回值	触发场景
0	当前实现固定返回 0

GetPlaybackSpeed

int32_t GetPlaybackSpeed(PlaybackRateMode &mode)

功能说明

• 核心用途：获取当前视频播放倍速
• 设计目的：提供倍速状态查询能力
• 使用场景：倍速设置确认、UI 状态同步

入参

名称	参数类型	详细说明	约束取值范围
mode	PlaybackRateMode &	出参引用，由被调用方写入当前倍速模式	有效引用

出参

名称	数据类型	输出说明
mode	PlaybackRateMode	当前播放倍速模式

返回值

• 返回类型：int32_t

返回查询操作结果

返回值	触发场景
0	当前实现固定返回 0

IsPlaying

bool IsPlaying(void)

功能说明

• 核心用途：查询视频是否正在播放中
• 设计目的：提供播放状态查询能力
• 使用场景：播放状态判断、UI 状态更新

返回值

• 返回类型：bool

返回播放状态标志

返回值	触发场景
true	视频正在播放中（isEntered_ 为 true）
false	内部播放器实例为空或视频未在播放

IsPaused

bool IsPaused(void)

功能说明

• 核心用途：查询视频是否处于暂停状态
• 设计目的：提供暂停状态查询能力
• 使用场景：暂停状态判断、UI 暂停按钮显示

返回值

• 返回类型：bool

返回暂停状态标志

返回值	触发场景
true	视频处于暂停状态（isPause_ 为 true）
false	内部播放器实例为空或视频未暂停

IsLooping

bool IsLooping(void)

功能说明

• 核心用途：查询视频是否处于循环播放模式
• 设计目的：提供循环播放状态查询能力
• 使用场景：循环模式判断、UI 循环按钮状态显示

返回值

• 返回类型：bool

返回循环播放状态标志

返回值	触发场景
true	处于循环播放模式（isLoop_ 为 true）
false	内部播放器实例为空或未开启循环播放

EnableSingleLooping

void EnableSingleLooping(bool isLoop)

功能说明

• 核心用途：设置或取消单循环播放模式
• 设计目的：提供循环播放控制接口，与 IsLooping 配对使用
• 使用场景：循环播放开关、播放列表循环控制

入参

名称	参数类型	详细说明	约束取值范围
isLoop	bool	是否启用单循环播放，入参只读	true：启用循环；false：取消循环

SetSurface

void SetSurface(Surface *surface)

功能说明

• 核心用途：设置视频渲染的 Surface 对象
• 设计目的：提供视频画面渲染目标设置接口
• 使用场景：视频渲染窗口绑定、Surface 切换

前置条件

• VideoPlayerService 对象已通过构造函数完成构造且内部 MediaVideoPlay 实例有效
• 视频未处于播放状态（isEntered_ 为 false）

入参

名称	参数类型	详细说明	约束取值范围
surface	Surface *	Surface 指针，入参指针，由调用方提供，被调用方不接管所有权	非 nullptr，指向有效的 Surface 对象

SetUILabelButton

void SetUILabelButton(UILabelButton *button)

功能说明

• 核心用途：设置与视频播放关联的 UI 标签按钮控件
• 设计目的：提供播放控制 UI 绑定接口，播放器自动更新按钮文本
• 使用场景：播放/暂停按钮绑定、UI 控件联动

前置条件

• VideoPlayerService 对象已通过构造函数完成构造且内部 MediaVideoPlay 实例有效
• 视频未处于播放状态（isEntered_ 为 false）

入参

名称	参数类型	详细说明	约束取值范围
button	UILabelButton *	UILabelButton 指针，入参指针，由调用方提供，被调用方不接管所有权	非 nullptr，指向有效的 UILabelButton 对象

GetDumpInfo

int32_t GetDumpInfo(Media::PlayerDebugInfo *playerInfo)

功能说明

• 核心用途：获取播放器调试信息，包含文件、视频流、音频流及播放控制状态
• 设计目的：提供播放器运行状态诊断能力
• 使用场景：故障排查、性能分析、播放状态调试

入参

名称	参数类型	详细说明	约束取值范围
playerInfo	Media::PlayerDebugInfo *	出参指针，由被调用方写入调试信息，不可为 nullptr	非 nullptr，指向有效内存

出参

名称	数据类型	输出说明
playerInfo	Media::PlayerDebugInfo	播放器调试信息，包含文件信息、视频流信息、音频流信息及播放控制信息

前置条件

• VideoPlayerService 对象已通过构造函数完成构造且内部 MediaVideoPlay 实例有效
• playerInfo 指针不为 nullptr

返回值

• 返回类型：int32_t

返回获取操作结果

返回值	触发场景
MEDIA_OK(0)	获取成功
MEDIA_ERR(-3)	内部播放器实例为空或获取失败

Enumerations

PlaybackRateMode

enum PlaybackRateMode : int32_t {
    SPEED_FORWARD_0_25_X,
    SPEED_FORWARD_0_50_X,
    SPEED_FORWARD_0_75_X,
    SPEED_FORWARD_1_00_X,
    SPEED_FORWARD_1_25_X,
    SPEED_FORWARD_1_50_X,
    SPEED_FORWARD_1_75_X,
    SPEED_FORWARD_2_00_X,
    SPEED_FORWARD_4_00_X,
    SPEED_FORWARD_8_00_X,
    SPEED_FORWARD_16_00_X,
    SPEED_FORWARD_32_00_X,
    SPEED_FORWARD_64_00_X,
    SPEED_REWIND_64_X,
    SPEED_REWIND_32_X,
    SPEED_REWIND_16_X,
    SPEED_REWIND_8_X,
    SPEED_REWIND_4_X,
    SPEED_REWIND_2_X,
    SPEED_REWIND_1_X,
};

枚举成员	取值	描述
SPEED_FORWARD_0_25_X	0	0.25 倍速正向播放
SPEED_FORWARD_0_50_X	1	0.5 倍速正向播放
SPEED_FORWARD_0_75_X	2	0.75 倍速正向播放
SPEED_FORWARD_1_00_X	3	1.0 倍速正向播放（正常速度）
SPEED_FORWARD_1_25_X	4	1.25 倍速正向播放
SPEED_FORWARD_1_50_X	5	1.5 倍速正向播放
SPEED_FORWARD_1_75_X	6	1.75 倍速正向播放
SPEED_FORWARD_2_00_X	7	2.0 倍速正向播放
SPEED_FORWARD_4_00_X	8	4.0 倍速正向播放
SPEED_FORWARD_8_00_X	9	8.0 倍速正向播放
SPEED_FORWARD_16_00_X	10	16.0 倍速正向播放
SPEED_FORWARD_32_00_X	11	32.0 倍速正向播放
SPEED_FORWARD_64_00_X	12	64.0 倍速正向播放
SPEED_REWIND_64_X	13	64 倍速倒退
SPEED_REWIND_32_X	14	32 倍速倒退
SPEED_REWIND_16_X	15	16 倍速倒退
SPEED_REWIND_8_X	16	8 倍速倒退
SPEED_REWIND_4_X	17	4 倍速倒退
SPEED_REWIND_2_X	18	2 倍速倒退
SPEED_REWIND_1_X	19	1 倍速倒退