StreamSourcePlayerService

Class Summary

OHOS::StreamSourcePlayerCallback

流媒体播放器事件回调接口，用于接收播放中断、错误、信息及播放完成通知

• 构造： 无

• 成员函数：

  接口名称	功能简述
  OnInterrupt	音频中断事件回调，通知中断类型与提示
  OnError	播放错误事件回调，通知错误类型与错误码
  OnInfo	播放信息事件回调，通知信息类型与附加码
  OnPlaybackComplete	播放完成事件回调

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

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

OHOS::StreamSourcePlayerService

流媒体源播放器服务，封装流式数据源与播放器的协同控制，提供流缓冲区管理与播放生命周期管理

• 构造： 无

• 成员函数：

  接口名称	功能简述
  SetPlayerCallback	设置播放器事件回调对象
  SetAudioStreamType	设置音频流类型
  SetStreamSourceInfo	设置流媒体源格式信息
  SetVideoSurface	设置视频渲染 Surface
  Start	启动流媒体播放
  Stop	停止流媒体播放并释放资源
  Pause	暂停流媒体播放
  Resume	恢复流媒体播放
  OnBufferAvailable	通知可用缓冲区信息
  SetStreamCallback	设置流数据回调对象
  GetBufferAddress	获取指定索引缓冲区的虚拟地址
  QueueBuffer	将已填充的缓冲区提交到播放队列
  GetAvailableBuffer	获取可用缓冲区信息
  GetPlayStatus	获取当前播放状态
  IsPlaying	查询是否正在播放
  GetDuration	获取媒体总时长

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

• 声明头文件： middleware/services/media/foundation/service/stream_source_player_service/include/stream_source_player_service.h
• 公有运算符： 无
• 继承关系： PlayerCallback、StreamSource、InterruptListener、std::enable_shared_from_this<StreamSourcePlayerService>
• 嵌套类型： 无
• 模板形参： 无

Functions

OHOS::StreamSourcePlayerCallback

OnInterrupt

virtual void OnInterrupt(int32_t type, int32_t hint) = 0

功能说明

• 核心用途：音频中断事件回调，当播放器被其他音频流中断时触发
• 设计目的：为上层应用提供音频焦点中断通知，支持中断类型与提示的区分处理
• 使用场景：来电中断媒体播放、语音助手抢占音频焦点等场景

入参

名称	参数类型	详细说明	约束取值范围
type	int32_t	中断类型	-
hint	int32_t	中断提示	-

OnError

virtual void OnError(int32_t errorType, int32_t errorCode) = 0

功能说明

• 核心用途：播放错误事件回调，当播放过程中发生错误时触发
• 设计目的：为上层应用提供播放异常通知，支持错误类型与错误码的区分
• 使用场景：解码失败、数据读取超时、文件格式不支持等错误场景

入参

名称	参数类型	详细说明	约束取值范围
errorType	int32_t	错误类型	-
errorCode	int32_t	错误码	-

OnInfo

virtual void OnInfo(int32_t type, int32_t extra) = 0

功能说明

• 核心用途：播放信息事件回调，当播放过程中产生信息通知时触发
• 设计目的：为上层应用提供播放状态信息通知，支持信息类型与附加码的区分
• 使用场景：播放开始、播放结束、定位开始、定位结束等状态通知

入参

名称	参数类型	详细说明	约束取值范围
type	int32_t	信息类型	-
extra	int32_t	附加信息码	-

OnPlaybackComplete

virtual void OnPlaybackComplete() = 0

功能说明

• 核心用途：播放完成事件回调，当媒体流播放到末尾时触发
• 设计目的：为上层应用提供播放结束通知，支持自动循环或资源释放等后续处理
• 使用场景：流媒体数据播放完成、EOS 标志到达后触发

OHOS::StreamSourcePlayerService

SetPlayerCallback

void SetPlayerCallback(const std::shared_ptr<StreamSourcePlayerCallback> &cb)

功能说明

• 核心用途：设置播放器事件回调对象，用于接收播放中断、错误、信息及播放完成通知
• 设计目的：将上层业务回调注册到播放器服务中，实现事件通知的向上传递
• 使用场景：在调用 Start 前注册回调，用于处理播放过程中的中断、错误与完成事件

入参

名称	参数类型	详细说明	约束取值范围
cb	const std::shared_ptr &	入参只读引用，播放器事件回调智能指针	有效 StreamSourcePlayerCallback 对象

SetAudioStreamType

int32_t SetAudioStreamType(AudioStreamType type)

功能说明

• 核心用途：设置音频流类型，用于音频焦点管理策略的判定
• 设计目的：在播放前指定音频流类型，确保音频中断策略与业务场景匹配
• 使用场景：在 Start 前调用，指定当前播放流的类型（如媒体音、健身视频音）

入参

名称	参数类型	详细说明	约束取值范围
type	AudioStreamType	音频流类型	AUDIO_STREAM_MUSIC / AUDIO_STREAM_FITNESS_VIDEO

返回值

• 返回类型：int32_t

返回设置结果

返回值	触发场景
MEDIA_OK(0)	设置成功
MEDIA_INVALID_PARAM(-1)	传入的音频流类型不在合法范围内

SetStreamSourceInfo

int32_t SetStreamSourceInfo(Format &formats)

功能说明

• 核心用途：设置流媒体源的格式信息，用于播放器初始化时的数据源配置
• 设计目的：在播放前将流媒体格式参数拷贝到服务内部，供 PreparePlayer 构造 Source 时使用
• 使用场景：在 Start 前调用，设置流数据源的编码格式、采样率等参数

入参

名称	参数类型	详细说明	约束取值范围
formats	Format &	入参引用，流媒体格式信息	有效的 Format 对象

返回值

• 返回类型：int32_t

返回设置结果

返回值	触发场景
MEDIA_OK(0)	设置成功

SetVideoSurface

int32_t SetVideoSurface(Surface *surface)

功能说明

• 核心用途：设置视频渲染 Surface，用于视频帧的显示输出
• 设计目的：在播放前指定视频渲染目标，播放器 Prepare 时将 Surface 传递给底层
• 使用场景：在 Start 前调用，设置视频渲染目标 Surface

入参

名称	参数类型	详细说明	约束取值范围
surface	Surface *	入参指针，视频渲染 Surface	非 nullptr，有效的 Surface 对象

返回值

• 返回类型：int32_t

返回设置结果

返回值	触发场景
MEDIA_OK(0)	设置成功
MEDIA_INVALID_PARAM(-1)	传入 surface 为 nullptr

Kconfig 配置

配置项	说明	默认值
ENABLE_UIKIT	启用 UIKIT 视频渲染支持	n

Start

int32_t Start(void)

功能说明

• 核心用途：启动流媒体播放，初始化播放器并开始播放
• 设计目的：将播放状态从 IDLE 转换为 PLAYED，内部执行 InitPlayer、PreparePlayer、Play 三步流程
• 使用场景：完成 SetStreamSourceInfo/SetAudioStreamType/SetVideoSurface 等配置后调用

前置条件

• 播放器状态必须为 STREAM_SOURCE_PLAYER_IDLE
• 已调用 SetStreamSourceInfo 设置流源格式信息
• 已调用 SetAudioStreamType 设置音频流类型

返回值

• 返回类型：int32_t

返回启动结果

返回值	触发场景
MEDIA_OK(0)	启动成功
MEDIA_ERR(-3)	状态非 IDLE；初始化播放器失败；准备播放器失败；开始播放失败

Stop

int32_t Stop(void)

功能说明

• 核心用途：停止流媒体播放，释放播放器资源
• 设计目的：将播放状态转换为 STOPED，内部依次调用 Player 的 Stop、Reset、Release
• 使用场景：播放完成或需要结束播放时调用，IDLE 状态也允许调用

返回值

• 返回类型：int32_t

返回停止结果

返回值	触发场景
MEDIA_OK(0)	停止成功；已处于 STOPED 状态；播放器对象为 nullptr

Pause

int32_t Pause(void)

功能说明

• 核心用途：暂停流媒体播放
• 设计目的：将播放状态从 PLAYED 转换为 PAUSED，暂停播放器输出
• 使用场景：用户主动暂停、音频中断暂停等场景

前置条件

• 播放器状态必须为 STREAM_SOURCE_PLAYER_PLAYED

返回值

• 返回类型：int32_t

返回暂停结果

返回值	触发场景
MEDIA_OK(0)	暂停成功
MEDIA_ERR(-3)	状态非 PLAYED；Player Pause 失败

Resume

int32_t Resume(void)

功能说明

• 核心用途：恢复流媒体播放
• 设计目的：将播放状态从 PAUSED 转换为 PLAYED，恢复播放器输出
• 使用场景：用户主动恢复、音频中断恢复等场景

前置条件

• 播放器状态必须为 STREAM_SOURCE_PLAYER_PAUSED

返回值

• 返回类型：int32_t

返回恢复结果

返回值	触发场景
MEDIA_OK(0)	恢复成功
MEDIA_ERR(-3)	状态非 PAUSED；Player Play 恢复失败

OnBufferAvailable

void OnBufferAvailable(size_t index, size_t offset, size_t size, int32_t flag) override

功能说明

• 核心用途：当播放器有可用缓冲区时回调，通知应用层可填充数据
• 设计目的：实现 StreamSource 接口，将可用缓冲区信息存入内部队列供 GetAvailableBuffer 读取
• 使用场景：播放器内部检测到空闲缓冲区时自动回调，应用层通过 GetAvailableBuffer 获取信息

入参

名称	参数类型	详细说明	约束取值范围
index	size_t	缓冲区索引	-
offset	size_t	数据写入起始偏移	-
size	size_t	缓冲区可存储数据大小	-
flag	int32_t	缓冲区标志	-

SetStreamCallback

void SetStreamCallback(const std::shared_ptr<StreamCallback> &callback) override

功能说明

• 核心用途：设置流数据回调对象，用于获取缓冲区地址与提交已填充缓冲区
• 设计目的：实现 StreamSource 接口，将播放器提供的 StreamCallback 保存为弱引用，供 GetBufferAddress 和 QueueBuffer 使用
• 使用场景：播放器内部在 SetSource 后调用，注册流数据操作回调

入参

名称	参数类型	详细说明	约束取值范围
callback	const std::shared_ptr &	入参只读引用，流数据回调智能指针	有效 StreamCallback 对象

GetBufferAddress

uint8_t *GetBufferAddress(size_t idx)

功能说明

• 核心用途：获取指定索引缓冲区的虚拟地址
• 设计目的：通过 StreamCallback 获取播放器分配的缓冲区地址，供应用层写入流数据
• 使用场景：应用层获取可用缓冲区后，调用此接口获取缓冲区地址以写入数据

入参

名称	参数类型	详细说明	约束取值范围
idx	size_t	缓冲区索引	-

返回值

• 返回类型：uint8_t *

返回缓冲区虚拟地址

返回值	触发场景
非 nullptr	成功获取缓冲区地址
nullptr	StreamCallback 弱引用已失效

QueueBuffer

void QueueBuffer(size_t index, size_t offset, size_t size, int64_t timestampUs, uint32_t flags)

功能说明

• 核心用途：将已填充数据的缓冲区提交到播放器队列
• 设计目的：通过 StreamCallback 将应用层已写入数据的缓冲区提交给播放器进行解码播放
• 使用场景：应用层向缓冲区写入数据后，调用此接口提交缓冲区

入参

名称	参数类型	详细说明	约束取值范围
index	size_t	缓冲区索引	-
offset	size_t	数据写入起始偏移	-
size	size_t	已填充数据大小	-
timestampUs	int64_t	帧时间戳（微秒），AAC 流设为 0	-
flags	uint32_t	缓冲区标志	STREAM_FLAG_SYNCFRAME / STREAM_FLAG_CODECCONFIG / STREAM_FLAG_EOS / STREAM_FLAG_PARTIAL_FRAME / STREAM_FLAG_ENDOFFRAME / STREAM_FLAG_MUXER_DATA

GetAvailableBuffer

int32_t GetAvailableBuffer(IdleBuffer *buffer)

功能说明

• 核心用途：获取可用缓冲区信息，从内部队列中取出一个可用缓冲区
• 设计目的：将 OnBufferAvailable 回调存入的缓冲区信息提供给应用层，供应用层获取可写入的缓冲区
• 使用场景：应用层在收到缓冲区可用通知后，调用此接口获取缓冲区索引、偏移、大小等信息

入参

名称	参数类型	详细说明	约束取值范围
buffer	IdleBuffer *	入参指针，出参载体，存放可用缓冲区信息	非 nullptr

出参

名称	数据类型	输出说明
buffer	IdleBuffer	出参指针，由被调用方写入可用缓冲区信息

返回值

• 返回类型：int32_t

返回获取结果

返回值	触发场景
0	成功获取可用缓冲区信息
MEDIA_ERR(-3)	buffer 为 nullptr
-1	可用缓冲区队列为空

GetPlayStatus

int32_t GetPlayStatus(void)

功能说明

• 核心用途：获取当前播放器状态
• 设计目的：将内部状态枚举转换为 int32_t 返回，供上层查询播放器当前状态
• 使用场景：上层轮询播放器状态、UI 状态同步等场景

返回值

• 返回类型：int32_t

返回播放状态，对应 StreamSourcePlayerStates 枚举值

返回值	触发场景
0	STREAM_SOURCE_PLAYER_IDLE
1	STREAM_SOURCE_PLAYER_PAUSED
2	STREAM_SOURCE_PLAYER_PLAYED
3	STREAM_SOURCE_PLAYER_STOPED

IsPlaying

bool IsPlaying(void)

功能说明

• 核心用途：查询播放器是否正在播放
• 设计目的：直接委托 Player 对象的 IsPlaying 方法返回播放状态
• 使用场景：上层需要快速判断当前是否处于播放状态

返回值

• 返回类型：bool

返回播放状态

返回值	触发场景
true	播放器正在播放
false	播放器未在播放；播放器对象为 nullptr

GetDuration

int32_t GetDuration(int64_t &durationMs)

功能说明

• 核心用途：获取媒体总时长
• 设计目的：委托 Player 对象获取媒体总时长，通过出参返回毫秒级时长
• 使用场景：上层需要显示播放进度或总时长

入参

名称	参数类型	详细说明	约束取值范围
durationMs	int64_t &	入参引用，出参载体，存储媒体总时长（毫秒）	-

出参

名称	数据类型	输出说明
durationMs	int64_t	出参引用，由被调用方写入媒体总时长（毫秒）

返回值

• 返回类型：int32_t

返回获取结果

返回值	触发场景
MEDIA_OK(0)	成功获取时长
MEDIA_ERR(-3)	播放器对象为 nullptr

Enumerations

StreamSourcePlayerStates

enum class StreamSourcePlayerStates : int32_t {
    STREAM_SOURCE_PLAYER_IDLE,
    STREAM_SOURCE_PLAYER_PAUSED,
    STREAM_SOURCE_PLAYER_PLAYED,
    STREAM_SOURCE_PLAYER_STOPED,
};

枚举成员	取值	描述
STREAM_SOURCE_PLAYER_IDLE	0	空闲状态，播放器未初始化
STREAM_SOURCE_PLAYER_PAUSED	1	暂停状态
STREAM_SOURCE_PLAYER_PLAYED	2	播放状态
STREAM_SOURCE_PLAYER_STOPED	3	停止状态

Structures

IdleBuffer

typedef struct TagIdleBuffer {
    size_t idx;
    size_t offset;
    size_t size;
    int32_t flag;
} IdleBuffer;

成员说明

成员名称	数据类型	描述
idx	size_t	缓冲区索引
offset	size_t	数据写入起始偏移
size	size_t	缓冲区可存储数据大小
flag	int32_t	缓冲区标志