
HarmonyOS API:@ohos.multimedia.media (媒体服务)
版本:v3.1 Beta
@ohos.multimedia.media (媒体服务)
更新时间: 2023-02-24 16:50
说明
本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
媒体子系统为开发者提供一套简单且易于理解的接口,使得开发者能够方便接入系统并使用系统的媒体资源。
媒体子系统包含了音视频相关媒体业务,提供以下常用功能:
- 音频播放(AudioPlayer)
- 视频播放(VideoPlayer)
- 音频录制(AudioRecorder)
导入模块
media.createAudioPlayer
createAudioPlayer(): AudioPlayer
同步方式创建音频播放实例。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
返回值:
类型 | 说明 |
返回AudioPlayer类实例,失败时返回null。可用于音频播放、暂停、停止等操作。 |
示例:
media.createVideoPlayer8+
createVideoPlayer(callback: AsyncCallback<VideoPlayer>): void
异步方式创建视频播放实例,通过注册回调函数获取返回值。
系统能力: SystemCapability.Multimedia.Media.VideoPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
callback | AsyncCallback<VideoPlayer> | 是 | 回调函数。异步返回VideoPlayer实例,失败时返回null。可用于管理和播放视频媒体。 |
示例:
media.createVideoPlayer8+
createVideoPlayer(): Promise<VideoPlayer>
异步方式创建视频播放实例,通过Promise获取返回值。
系统能力: SystemCapability.Multimedia.Media.VideoPlayer
返回值:
类型 | 说明 |
Promise<VideoPlayer> | Promise对象。异步返回VideoPlayer实例,失败时返回null。可用于管理和播放视频媒体。 |
示例:
media.createAudioRecorder
createAudioRecorder(): AudioRecorder
创建音频录制的实例来控制音频的录制。
一台设备只允许创建一个录制实例。
系统能力: SystemCapability.Multimedia.Media.AudioRecorder
返回值:
类型 | 说明 |
返回AudioRecorder类实例,失败时返回null。可用于录制音频媒体。 |
示例:
MediaErrorCode8+
媒体服务错误类型枚举。
系统能力: SystemCapability.Multimedia.Media.Core
名称 | 值 | 说明 |
MSERR_OK | 0 | 表示操作成功。 |
MSERR_NO_MEMORY | 1 | 表示申请内存失败,系统可能无可用内存。 |
MSERR_OPERATION_NOT_PERMIT | 2 | 表示无权限执行此操作。 |
MSERR_INVALID_VAL | 3 | 表示传入入参无效。 |
MSERR_IO | 4 | 表示发生IO错误。 |
MSERR_TIMEOUT | 5 | 表示操作超时。 |
MSERR_UNKNOWN | 6 | 表示未知错误。 |
MSERR_SERVICE_DIED | 7 | 表示服务端失效。 |
MSERR_INVALID_STATE | 8 | 表示在当前状态下,不允许执行此操作。 |
MSERR_UNSUPPORTED | 9 | 表示在当前版本下,不支持此操作。 |
MediaType8+
媒体类型枚举。
系统能力: SystemCapability.Multimedia.Media.Core
名称 | 值 | 说明 |
MEDIA_TYPE_AUD | 0 | 表示音频。 |
MEDIA_TYPE_VID | 1 | 表示视频。 |
CodecMimeType8+
Codec MIME类型枚举。
系统能力: SystemCapability.Multimedia.Media.Core
名称 | 值 | 说明 |
VIDEO_H263 | 'video/h263' | 表示视频/h263类型。 |
VIDEO_AVC | 'video/avc' | 表示视频/avc类型。 |
VIDEO_MPEG2 | 'video/mpeg2' | 表示视频/mpeg2类型。 |
VIDEO_MPEG4 | 'video/mp4v-es' | 表示视频/mpeg4类型。 |
VIDEO_VP8 | 'video/x-vnd.on2.vp8' | 表示视频/vp8类型。 |
AUDIO_AAC | 'audio/mp4a-latm' | 表示音频/mp4a-latm类型。 |
AUDIO_VORBIS | 'audio/vorbis' | 表示音频/vorbis类型。 |
AUDIO_FLAC | 'audio/flac' | 表示音频/flac类型。 |
MediaDescriptionKey8+
媒体信息描述枚举。
系统能力: SystemCapability.Multimedia.Media.Core
名称 | 值 | 说明 |
MD_KEY_TRACK_INDEX | 'track_index' | 表示轨道序号,其对应键值类型为number。 |
MD_KEY_TRACK_TYPE | 'track_type' | 表示轨道类型,其对应键值类型为number,参考MediaType。 |
MD_KEY_CODEC_MIME | 'codec_mime' | 表示codec_mime类型,其对应键值类型为string。 |
MD_KEY_DURATION | 'duration' | 表示媒体时长,其对应键值类型为number,单位为毫秒(ms)。 |
MD_KEY_BITRATE | 'bitrate' | 表示比特率,其对应键值类型为number,单位为比特率(bps)。 |
MD_KEY_WIDTH | 'width' | 表示视频宽度,其对应键值类型为number,单位为像素(px)。 |
MD_KEY_HEIGHT | 'height' | 表示视频高度,其对应键值类型为number,单位为像素(px)。 |
MD_KEY_FRAME_RATE | 'frame_rate' | 表示视频帧率,其对应键值类型为number,单位为100帧每秒(100fps)。 |
MD_KEY_AUD_CHANNEL_COUNT | 'channel_count' | 表示声道数,其对应键值类型为number。 |
MD_KEY_AUD_SAMPLE_RATE | 'sample_rate' | 表示采样率,其对应键值类型为number,单位为赫兹(Hz)。 |
BufferingInfoType8+
缓存事件类型枚举。
系统能力: SystemCapability.Multimedia.Media.Core
名称 | 值 | 说明 |
BUFFERING_START | 1 | 表示开始缓存。 |
BUFFERING_END | 2 | 表示结束缓存。 |
BUFFERING_PERCENT | 3 | 表示缓存百分比。 |
AudioPlayer
音频播放管理类,用于管理和播放音频媒体。在调用AudioPlayer的方法前,需要先通过createAudioPlayer()构建一个AudioPlayer实例。
音频播放demo可参考:音频播放开发指导
属性
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
名称 | 类型 | 可读 | 可写 | 说明 |
src | string | 是 | 是 | 音频媒体URI,支持当前主流的音频格式(m4a、aac、mp3、ogg、wav)。 支持路径示例: 1. fd类型播放:fd://xx 2. http网络播放: http://xx 3. https网络播放: https://xx 4. hls网络播放路径:http://xx或者https://xx 需要权限: ohos.permission.READ_MEDIA 或 ohos.permission.INTERNET。 |
fdSrc9+ | 是 | 是 | 音频媒体文件描述,使用场景:应用中的音频资源被连续存储在同一个文件中。 使用示例: 假设一个连续存储的音乐文件: 音乐1(地址偏移:0,字节长度:100) 音乐2(地址偏移:101,字节长度:50) 音乐3(地址偏移:151,字节长度:150) 1. 播放音乐1:AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; } 2. 播放音乐2:AVFileDescriptor { fd = 资源句柄; offset = 101; length = 50; } 3. 播放音乐3:AVFileDescriptor { fd = 资源句柄; offset = 151; length = 150; } 假设是一个独立的音乐文件: 请使用src=fd://xx | |
loop | boolean | 是 | 是 | 音频循环播放属性,设置为'true'表示循环播放。 |
currentTime | number | 是 | 否 | 音频的当前播放位置,单位为毫秒(ms)。 |
duration | number | 是 | 否 | 音频时长,单位为毫秒(ms)。 |
state | 是 | 否 | 可以查询音频播放的状态,该状态不可作为调用play/pause/stop等状态切换的触发条件。 |
play
play(): void
开始播放音频资源,需在dataLoad事件成功触发后,才能调用。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
示例:
pause
pause(): void
暂停播放音频资源。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
示例:
stop
stop(): void
停止播放音频资源。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
示例:
reset7+
reset(): void
重置播放音频资源。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
示例:
seek
seek(timeMs: number): void
跳转到指定播放位置。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
timeMs | number | 是 | 指定的跳转时间节点,单位毫秒(ms),取值范围[0, duration]。 |
示例:
setVolume
setVolume(vol: number): void
设置音量。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
vol | number | 是 | 指定的相对音量大小,取值范围为[0.00-1.00],1表示最大音量,即100%。 |
示例:
release
release(): void
释放音频资源。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
示例:
getTrackDescription8+
getTrackDescription(callback: AsyncCallback<Array<MediaDescription>>): void
通过回调方式获取音频轨道信息。需在dataLoad事件成功触发后,才能调用。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
callback | AsyncCallback<Array<MediaDescription>> | 是 | 音频轨道信息MediaDescription数组回调方法。 |
示例:
getTrackDescription8+
getTrackDescription(): Promise<Array<MediaDescription>>
通过Promise方式获取音频轨道信息。需在dataLoad事件成功触发后,才能调用
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
返回值:
类型 | 说明 |
Promise<Array<MediaDescription>> | 音频轨道信息MediaDescription数组Promise返回值。 |
示例:
on('bufferingUpdate')8+
on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void
开始订阅音频缓存更新事件。仅网络播放支持该订阅事件。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 音频缓存事件回调类型,支持的事件:'bufferingUpdate'。 |
callback | function | 是 | 音频缓存事件回调方法。 BufferingInfoType为BUFFERING_PERCENT时,value值有效,否则固定为0。 |
示例:
on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')
on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void): void
开始订阅音频播放事件。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 播放事件回调类型,支持的事件包括:'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange'。 - 'play':完成play()调用,音频开始播放,触发该事件。 - 'pause':完成pause()调用,音频暂停播放,触发该事件。 - 'stop':完成stop()调用,音频停止播放,触发该事件。 - 'reset':完成reset()调用,播放器重置,触发该事件。 - 'dataLoad':完成音频数据加载后触发该事件,即src属性设置完成后触发该事件。 - 'finish':完成音频播放后触发该事件。 - 'volumeChange':完成setVolume()调用,播放音量改变后触发该事件。 |
callback | () => void | 是 | 播放事件回调方法。 |
示例:
on('timeUpdate')
on(type: 'timeUpdate', callback: Callback<number>): void
开始订阅音频播放时间更新事件。处于播放状态时,每隔1s上报一次该事件。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 播放事件回调类型,支持的事件包括:'timeUpdate'。 - 'timeUpdate':音频播放时间戳更新,开始播放后自动触发该事件。 |
callback | Callback<number> | 是 | 播放事件回调方法。回调方法入参为更新后的时间戳。 |
示例:
on('error')
on(type: 'error', callback: ErrorCallback): void
开始订阅音频播放错误事件,当上报error错误事件后,用户需处理error事件,退出播放操作。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 播放错误事件回调类型,支持的事件包括:'error'。 - 'error':音频播放中发生错误,触发该事件。 |
callback | ErrorCallback | 是 | 播放错误事件回调方法。 |
示例:
AudioState
音频播放的状态机。可通过state属性获取当前状态。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
名称 | 类型 | 说明 |
idle | string | 音频播放空闲,dataload/reset成功后处于此状态。 |
playing | string | 音频正在播放,play成功后处于此状态。 |
paused | string | 音频暂停播放,pause成功后处于此状态。 |
stopped | string | 音频播放停止,stop/播放结束后处于此状态。 |
error | string | 错误状态。 |
AVFileDescriptor9+
音视频文件资源描述,一种特殊资源的播放方式,使用场景:应用中的音频资源被连续存储在同一个文件中,需要根据偏移量和长度进行播放。
系统能力: SystemCapability.Multimedia.Media.Core
名称 | 类型 | 必填 | 说明 |
fd | number | 是 | 资源句柄,通过resourceManager.getRawFileDescriptor获取 |
offset | number | 是 | 资源偏移量,需要基于预置资源的信息输入,非法值会造成音视频资源解析错误 |
length | number | 是 | 资源长度,需要基于预置资源的信息输入,非法值会造成音视频资源解析错误 |
