AudioPlayerService

Class Summary

OHOS::AudioPlayerServiceCallback

音频播放服务回调抽象基类，用于接收播放中断、错误、完成等事件通知。

• 构造： 无

• 成员函数：

  接口名称	功能简述
  OnInterrupt	音频中断事件回调，通知中断类型和提示
  OnError	播放错误事件回调，通知错误类型和错误码
  OnPlaybackComplete	播放完成事件回调
  OnPlay	播放开始事件回调
  OnPause	暂停事件回调
  OnStop	停止事件回调

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

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

OHOS::AudioPlayerService

音频播放服务类，提供播放列表管理、播放控制、循环模式设置及音频焦点管理能力。

• 构造： 无

• 成员函数：

  接口名称	功能简述
  GetInstance	获取 AudioPlayerService 单例实例
  SetPlayListSource	设置播放列表源及起始播放索引
  SetPlaySource	设置单个播放源
  SetAudioStreamType	设置音频流类型
  SetBackgroundMode	设置后台播放模式
  SetQuitTime	设置定时退出时间
  SetDecryptLibraryPath	设置解密库路径
  IsBackgroundMode	查询是否处于后台播放模式
  SetAudioPlayerCallback	注册播放服务回调
  Start	启动音频播放
  Stop	停止音频播放
  Pause	暂停音频播放
  Resume	恢复音频播放
  Reset	重置播放服务状态
  Seek	跳转到指定播放位置
  PlayNext	播放下一个音频源
  PlayPrev	播放上一个音频源
  GetDumpInfo	获取播放调试信息
  GetCurrentTime	获取当前播放位置
  GetPlayStatus	获取当前播放状态
  SetPlayLoopMode	设置播放循环模式
  IsSingleLooping	查询是否单曲循环模式
  IsPlayListLooping	查询是否列表循环模式
  IsPlaying	查询是否正在播放
  GetCurrentPlaySource	获取当前播放源路径
  GetDuration	获取音频总时长
  GetAlbumInfo	获取专辑信息
  HasM3U8	判断源路径是否为 M3U8 格式

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

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

Functions

OHOS::AudioPlayerServiceCallback

OnInterrupt

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

功能说明

• 核心用途：接收音频中断事件通知
• 设计目的：当音频播放被其他音频流中断时，通过此回调通知调用方中断类型和中断提示
• 使用场景：电话来电、其他应用抢占音频焦点等中断场景

入参

名称	参数类型	详细说明	约束取值范围
type	int32_t	中断类型，入参只读	INTERRUPT_TYPE_BEGIN / INTERRUPT_TYPE_END
hint	int32_t	中断提示，入参只读	INTERRUPT_HINT_PAUSE / INTERRUPT_HINT_RESUME / INTERRUPT_HINT_STOP

OnError

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

功能说明

• 核心用途：接收播放错误事件通知
• 设计目的：当音频播放过程中发生错误时，通过此回调通知调用方错误类型和错误码
• 使用场景：播放文件损坏、解码失败等错误场景

入参

名称	参数类型	详细说明	约束取值范围
errorType	int32_t	错误类型，入参只读	PlayerErrorType 枚举值
errorCode	int32_t	错误码，入参只读	PlayerErrorCode 枚举值

OnPlaybackComplete

virtual void OnPlaybackComplete() = 0

功能说明

• 核心用途：接收播放完成事件通知
• 设计目的：当前音频源播放结束时，通过此回调通知调用方
• 使用场景：音频文件播放至末尾、流媒体播放完成

OnPlay

virtual void OnPlay() = 0

功能说明

• 核心用途：接收播放开始事件通知
• 设计目的：音频开始播放时，通过此回调通知调用方
• 使用场景：调用 Start 成功后播放开始、恢复播放后重新开始

OnPause

virtual void OnPause() = 0

功能说明

• 核心用途：接收暂停事件通知
• 设计目的：音频暂停时，通过此回调通知调用方
• 使用场景：调用 Pause 成功后、音频焦点中断导致暂停

OnStop

virtual void OnStop() = 0

功能说明

• 核心用途：接收停止事件通知
• 设计目的：音频停止时，通过此回调通知调用方
• 使用场景：调用 Stop 成功后、播放结束自动停止

OHOS::AudioPlayerService

GetInstance

static std::shared_ptr<AudioPlayerService> GetInstance()

功能说明

• 核心用途：获取 AudioPlayerService 单例实例
• 设计目的：提供全局唯一的音频播放服务实例访问入口
• 使用场景：任何需要使用音频播放服务功能前的实例获取

返回值

• 返回类型：std::shared_ptr<AudioPlayerService>

返回 AudioPlayerService 单例的共享指针

返回值	触发场景
非 nullptr	单例实例获取成功
nullptr	单例未创建

SetPlayListSource

int32_t SetPlayListSource(std::vector<std::string> playlist, uint32_t index = 0)

功能说明

• 核心用途：设置播放列表及起始播放索引
• 设计目的：支持多音频源批量设置，指定从列表中哪个位置开始播放
• 使用场景：批量加载播放列表、指定起始播放位置

前置条件

• 当前状态为 AUDIO_PLAYER_IDLE，非 IDLE 状态调用返回错误
• 入参 index 须小于 playlist 的大小

入参

名称	参数类型	详细说明	约束取值范围
playlist	std::vector	播放列表，入参只读	列表非空，每个元素为合法音频源路径
index	uint32_t	起始播放索引，入参只读，缺省值为 0	0 ~ playlist.size() - 1

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	设置成功
MEDIA_ERR	当前状态非 IDLE 或索引越界

SetPlaySource

int32_t SetPlaySource(std::string src)

功能说明

• 核心用途：设置单个播放源
• 设计目的：若源已在播放列表中则定位到对应索引，否则追加到列表末尾并定位
• 使用场景：单文件播放、动态添加播放源

前置条件

• 当前状态为 AUDIO_PLAYER_IDLE

入参

名称	参数类型	详细说明	约束取值范围
src	std::string	音频源路径，入参只读	合法音频源路径字符串

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	设置成功
MEDIA_ERR	当前状态非 IDLE

SetAudioStreamType

int32_t SetAudioStreamType(AudioStreamType type)

功能说明

• 核心用途：设置音频流类型
• 设计目的：指定音频流类型以参与音频焦点管理策略
• 使用场景：播放前设置流类型（如音乐、提示音等）

前置条件

• 当前状态为 AUDIO_PLAYER_IDLE

入参

名称	参数类型	详细说明	约束取值范围
type	AudioStreamType	音频流类型，入参只读	AudioStreamType 枚举值（如 AUDIO_STREAM_MUSIC）

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	设置成功
MEDIA_ERR	当前状态非 IDLE

SetBackgroundMode

int32_t SetBackgroundMode(bool isBackground)

功能说明

• 核心用途：设置后台播放模式
• 设计目的：启用后台模式后，中断事件由服务内部处理而非通过回调通知调用方
• 使用场景：应用退至后台仍需保持音频播放

入参

名称	参数类型	详细说明	约束取值范围
isBackground	bool	是否启用后台播放模式，入参只读	true / false

返回值

• 返回类型：int32_t

返回操作结果

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

SetQuitTime

void SetQuitTime(int64_t time)

功能说明

• 核心用途：设置定时退出时间
• 设计目的：到时后暂停或退出播放列表，用于定时关闭场景
• 使用场景：睡眠定时、限时播放

入参

名称	参数类型	详细说明	约束取值范围
time	int64_t	定时时长，单位为分钟，入参只读	0 表示取消定时；正值设定定时时长

SetDecryptLibraryPath

void SetDecryptLibraryPath(char *path, uint32_t len)

功能说明

• 核心用途：设置解密库路径
• 设计目的：为加密音频文件提供解密库加载路径
• 使用场景：播放加密音频前设置解密库路径

入参

名称	参数类型	详细说明	约束取值范围
path	char *	解密库路径，入参指针	非 nullptr
len	uint32_t	路径字符串长度（含终止符），入参只读	大于 0

Kconfig 配置

配置项	说明	默认值
HMF_DECRYPT_DATA_ENABLE	启用解密数据功能	n

IsBackgroundMode

bool IsBackgroundMode(void)

功能说明

• 核心用途：查询当前是否处于后台播放模式
• 设计目的：供调用方判断服务当前播放模式
• 使用场景：UI 层判断是否显示播放控制界面

返回值

• 返回类型：bool

返回后台播放模式状态

返回值	触发场景
true(1)	处于后台播放模式
false(0)	处于前台播放模式

SetAudioPlayerCallback

void SetAudioPlayerCallback(const std::shared_ptr<AudioPlayerServiceCallback> &cb)

功能说明

• 核心用途：注册播放服务回调
• 设计目的：设置回调对象以接收播放状态变化事件（中断、错误、完成等）
• 使用场景：播放前注册回调以监听播放事件

入参

名称	参数类型	详细说明	约束取值范围
cb	const std::shared_ptr &	回调对象共享指针，入参共享所有权	非 nullptr

Start

int32_t Start(void)

功能说明

• 核心用途：启动音频播放
• 设计目的：创建播放线程并开始播放当前播放列表中的音频源
• 使用场景：设置完播放源和参数后启动播放

前置条件

• 当前状态为 AUDIO_PLAYER_IDLE
• 已通过 SetPlayListSource 或 SetPlaySource 设置播放源

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	启动成功或非 IDLE 状态
MEDIA_ERR	创建线程失败或资源初始化失败

Stop

int32_t Stop(void)

功能说明

• 核心用途：停止音频播放
• 设计目的：停止当前播放并等待播放线程退出
• 使用场景：用户主动停止播放、切换播放列表前停止

前置条件

• 当前状态在 AUDIO_PLAYER_ENTERED 至 AUDIO_PLAYER_PLAYED 范围内

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	停止成功
MEDIA_ERR	当前状态不允许停止

Pause

int32_t Pause(void)

功能说明

• 核心用途：暂停音频播放
• 设计目的：暂停当前正在播放的音频，可通过 Resume 恢复
• 使用场景：用户主动暂停、音频焦点中断导致暂停

前置条件

• 当前状态为 AUDIO_PLAYER_PLAYED 或 AUDIO_PLAYER_ENTERED
• 播放未完成且未被停止

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	暂停成功
MEDIA_ERR	当前状态不允许暂停

Resume

int32_t Resume(void)

功能说明

• 核心用途：恢复音频播放
• 设计目的：从暂停状态恢复播放，通知播放线程继续
• 使用场景：用户主动恢复播放、音频焦点恢复

前置条件

• 当前状态为 AUDIO_PLAYER_PAUSED
• 播放未完成且未被停止

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	恢复成功
MEDIA_ERR	当前状态不允许恢复

Reset

int32_t Reset(void)

功能说明

• 核心用途：重置播放服务状态
• 设计目的：清除播放列表、重置所有状态标志为初始值，释放同步资源
• 使用场景：播放结束需要重新配置、切换播放场景

返回值

• 返回类型：int32_t

返回操作结果

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

Seek

int32_t Seek(int64_t mSeconds)

功能说明

• 核心用途：跳转到指定播放位置
• 设计目的：支持播放进度跳转，跳转完成后触发 OnRewindToComplete 回调
• 使用场景：拖动进度条、快进/快退

前置条件

• 当前状态为 AUDIO_PLAYER_PLAYED 或 AUDIO_PLAYER_PAUSED
• 播放器对象有效

入参

名称	参数类型	详细说明	约束取值范围
mSeconds	int64_t	目标播放位置，单位为毫秒，入参只读	0 ~ 音频总时长（毫秒）

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	跳转成功
MEDIA_ERR	当前状态不允许跳转或播放器对象无效

PlayNext

int32_t PlayNext(void)

功能说明

• 核心用途：播放下一个音频源
• 设计目的：切换播放列表中的下一首，到达末尾后循环到第一首
• 使用场景：用户主动切换下一首

前置条件

• 当前状态在 AUDIO_PLAYER_ENTERED 至 AUDIO_PLAYER_PLAYED 范围内

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	切换成功
MEDIA_ERR	当前状态不允许切换

PlayPrev

int32_t PlayPrev(void)

功能说明

• 核心用途：播放上一个音频源
• 设计目的：切换播放列表中的上一首，到达开头后循环到最后一首
• 使用场景：用户主动切换上一首

前置条件

• 当前状态在 AUDIO_PLAYER_ENTERED 至 AUDIO_PLAYER_PLAYED 范围内

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	切换成功
MEDIA_ERR	当前状态不允许切换

GetDumpInfo

int32_t GetDumpInfo(PlayerDebugInfo *playerInfo)

功能说明

• 核心用途：获取播放器调试信息
• 设计目的：用于问题定位和运行状态排查
• 使用场景：调试排障、运行状态监控

前置条件

• 播放器对象有效（已启动播放）

入参

名称	参数类型	详细说明	约束取值范围
playerInfo	PlayerDebugInfo *	调试信息输出指针，出参指针	非 nullptr

出参

名称	数据类型	输出说明
playerInfo	PlayerDebugInfo *	出参指针，由被调用方写入播放器调试信息

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	获取成功
MEDIA_ERR	播放器对象无效或获取失败

GetCurrentTime

int32_t GetCurrentTime(int64_t &time)

功能说明

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

前置条件

• 播放器对象有效（已启动播放）

入参

名称	参数类型	详细说明	约束取值范围
time	int64_t &	出参引用，由被调用方写入	-

出参

名称	数据类型	输出说明
time	int64_t &	出参引用，当前播放位置（毫秒）

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	获取成功
MEDIA_ERR	播放器对象无效或获取失败

GetPlayStatus

int32_t GetPlayStatus(void)

功能说明

• 核心用途：获取当前播放状态
• 设计目的：查询播放服务当前状态值
• 使用场景：UI 层状态显示、播放控制逻辑判断

返回值

• 返回类型：int32_t

返回当前播放状态

返回值	触发场景
0	AUDIO_PLAYER_IDLE
1	AUDIO_PLAYER_ENTERED
2	AUDIO_PLAYER_PAUSED
3	AUDIO_PLAYER_RESUMEING
4	AUDIO_PLAYER_PLAYED
5	AUDIO_PLAYER_STOPED
6	AUDIO_PLAYER_EXITED

SetPlayLoopMode

int32_t SetPlayLoopMode(AudioPlayerLoopMode loopMode)

功能说明

• 核心用途：设置播放循环模式
• 设计目的：控制播放列表循环策略（列表循环、单曲循环、列表顺序播放）
• 使用场景：用户切换循环模式

入参

名称	参数类型	详细说明	约束取值范围
loopMode	AudioPlayerLoopMode	循环模式，入参只读	AudioPlayerLoopMode 枚举值

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	设置成功
MEDIA_ERR	无效循环模式

IsSingleLooping

bool IsSingleLooping(void)

功能说明

• 核心用途：查询是否为单曲循环模式
• 设计目的：判断当前循环模式是否为单曲循环
• 使用场景：UI 层显示循环模式图标

返回值

• 返回类型：bool

返回单曲循环状态

返回值	触发场景
true(1)	当前为单曲循环模式
false(0)	当前非单曲循环模式

IsPlayListLooping

bool IsPlayListLooping(void)

功能说明

• 核心用途：查询是否为列表循环模式
• 设计目的：判断当前循环模式是否为列表循环
• 使用场景：UI 层显示循环模式图标

返回值

• 返回类型：bool

返回列表循环状态

返回值	触发场景
true(1)	当前为列表循环模式
false(0)	当前非列表循环模式

IsPlaying

bool IsPlaying(void)

功能说明

• 核心用途：查询是否正在播放
• 设计目的：查询底层播放器的实际播放状态
• 使用场景：UI 层播放状态判断

返回值

• 返回类型：bool

返回播放状态

返回值	触发场景
true(1)	正在播放
false(0)	未在播放或播放器对象无效

GetCurrentPlaySource

std::string GetCurrentPlaySource(void)

功能说明

• 核心用途：获取当前播放源路径
• 设计目的：查询当前正在播放的音频源 URI
• 使用场景：UI 层显示当前曲目信息

返回值

• 返回类型：std::string

返回当前播放源路径

返回值	触发场景
非空字符串	索引有效，返回源路径
空字符串	索引无效

GetDuration

int32_t GetDuration(int64_t &durationMs)

功能说明

• 核心用途：获取音频总时长
• 设计目的：查询当前音频文件的总播放时长
• 使用场景：进度条总长度设置、时长显示

前置条件

• 播放器对象有效（已启动播放）

入参

名称	参数类型	详细说明	约束取值范围
durationMs	int64_t &	出参引用，由被调用方写入	-

出参

名称	数据类型	输出说明
durationMs	int64_t &	出参引用，音频总时长（毫秒）

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
MEDIA_OK(0)	获取成功
MEDIA_ERR	播放器对象无效

GetAlbumInfo

void GetAlbumInfo(AudioPlayerAlbumInfo &albumInfo, const char *src)

功能说明

• 核心用途：获取指定音频源的专辑信息
• 设计目的：解析音频文件元数据，提取标题、艺术家、时长等专辑信息
• 使用场景：显示曲目详情、专辑封面信息

前置条件

• src 不为 nullptr
• src 非 http 远程路径（仅支持本地文件）

入参

名称	参数类型	详细说明	约束取值范围
albumInfo	AudioPlayerAlbumInfo &	出参引用，由被调用方写入	-
src	const char *	音频源路径，入参只读指针	非 nullptr，非 http 前缀

出参

名称	数据类型	输出说明
albumInfo	AudioPlayerAlbumInfo &	出参引用，写入专辑信息（src、title、artist、duration）

Kconfig 配置

配置项	说明	默认值
SUPPORT_BIKE	启用骑行模式，增加 duration 字段输出	n

HasM3U8

bool HasM3U8(const std::string& str)

功能说明

• 核心用途：判断源路径是否为 M3U8 格式
• 设计目的：检测音频源是否为 HLS 流媒体格式
• 使用场景：播放线程栈大小决策（M3U8 需要更大栈空间）

入参

名称	参数类型	详细说明	约束取值范围
str	const std::string&	音频源路径，入参只读引用	合法字符串

返回值

• 返回类型：bool

返回是否为 M3U8 格式

返回值	触发场景
true(1)	路径包含 ".m3u8"
false(0)	路径不包含 ".m3u8"

Enumerations

AudioPlayerStates

enum class AudioPlayerStates : int32_t {
    AUDIO_PLAYER_IDLE,
    AUDIO_PLAYER_ENTERED,
    AUDIO_PLAYER_PAUSED,
    AUDIO_PLAYER_RESUMEING,
    AUDIO_PLAYER_PLAYED,
    AUDIO_PLAYER_STOPED,
    AUDIO_PLAYER_EXITED,
};

枚举成员	取值	描述
AUDIO_PLAYER_IDLE	0	空闲状态，未开始播放
AUDIO_PLAYER_ENTERED	1	已进入，播放线程已创建
AUDIO_PLAYER_PAUSED	2	暂停状态
AUDIO_PLAYER_RESUMEING	3	正在恢复播放
AUDIO_PLAYER_PLAYED	4	播放中
AUDIO_PLAYER_STOPED	5	已停止
AUDIO_PLAYER_EXITED	6	已退出，播放线程已结束

AudioPlayerLoopMode

enum class AudioPlayerLoopMode : int32_t {
    AUDIO_PLAYER_PLAYLIST_LOOP,
    AUDIO_PLAYER_PLAYLIST_PLAY,
    AUDIO_PLAYER_SINGLE_LOOP,
    AUDIO_PLAYER_INVAILD_LOOP,
};

枚举成员	取值	描述
AUDIO_PLAYER_PLAYLIST_LOOP	0	列表循环播放
AUDIO_PLAYER_PLAYLIST_PLAY	1	列表顺序播放（不循环）
AUDIO_PLAYER_SINGLE_LOOP	2	单曲循环播放
AUDIO_PLAYER_INVAILD_LOOP	3	无效循环模式

Structures

AudioPlayerAlbumInfo

typedef struct AudioPlayerAlbumInfo {
    std::string src;
    std::string title;
    std::string artist;
#ifdef SUPPORT_BIKE
    double duration;
#endif
} AudioPlayerAlbumInfo;

成员说明

成员名称	数据类型	描述
src	std::string	音频源路径
title	std::string	曲目标题
artist	std::string	艺术家名称
duration	double	音频时长（秒），仅 SUPPORT_BIKE 宏启用时可用