HarmonyOS API:@ohos.multimedia.media (媒体服务)
版本:v3.1 Beta
@ohos.multimedia.media (媒体服务)
更新时间: 2023-02-24 16:50
说明
本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
媒体子系统为开发者提供一套简单且易于理解的接口,使得开发者能够方便接入系统并使用系统的媒体资源。
媒体子系统包含了音视频相关媒体业务,提供以下常用功能:
- 音频播放(AudioPlayer)
- 视频播放(VideoPlayer)
- 音频录制(AudioRecorder)
导入模块
import media from '@ohos.multimedia.media';
media.createAudioPlayer
createAudioPlayer(): AudioPlayer
同步方式创建音频播放实例。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
返回值:
类型 | 说明 |
返回AudioPlayer类实例,失败时返回null。可用于音频播放、暂停、停止等操作。 |
示例:
let audioPlayer = media.createAudioPlayer();
media.createVideoPlayer8+
createVideoPlayer(callback: AsyncCallback<VideoPlayer>): void
异步方式创建视频播放实例,通过注册回调函数获取返回值。
系统能力: SystemCapability.Multimedia.Media.VideoPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
callback | AsyncCallback<VideoPlayer> | 是 | 回调函数。异步返回VideoPlayer实例,失败时返回null。可用于管理和播放视频媒体。 |
示例:
let videoPlayer
media.createVideoPlayer((error, video) => {
if (video != null) {
videoPlayer = video;
console.info('video createVideoPlayer success');
} else {
console.info(`video createVideoPlayer fail, error:${error}`);
}
});
media.createVideoPlayer8+
createVideoPlayer(): Promise<VideoPlayer>
异步方式创建视频播放实例,通过Promise获取返回值。
系统能力: SystemCapability.Multimedia.Media.VideoPlayer
返回值:
类型 | 说明 |
Promise<VideoPlayer> | Promise对象。异步返回VideoPlayer实例,失败时返回null。可用于管理和播放视频媒体。 |
示例:
let videoPlayer
media.createVideoPlayer().then((video) => {
if (video != null) {
videoPlayer = video;
console.info('video createVideoPlayer success');
} else {
console.info('video createVideoPlayer fail');
}
}).catch((error) => {
console.info(`video catchCallback, error:${error}`);
});
media.createAudioRecorder
createAudioRecorder(): AudioRecorder
创建音频录制的实例来控制音频的录制。
一台设备只允许创建一个录制实例。
系统能力: SystemCapability.Multimedia.Media.AudioRecorder
返回值:
类型 | 说明 |
返回AudioRecorder类实例,失败时返回null。可用于录制音频媒体。 |
示例:
let audioRecorder = media.createAudioRecorder();
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
示例:
audioPlayer.on('play', () => { //设置'play'事件回调
console.log('audio play success');
});
audioPlayer.play();
pause
pause(): void
暂停播放音频资源。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
示例:
audioPlayer.on('pause', () => { //设置'pause'事件回调
console.log('audio pause success');
});
audioPlayer.pause();
stop
stop(): void
停止播放音频资源。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
示例:
audioPlayer.on('stop', () => { //设置'stop'事件回调
console.log('audio stop success');
});
audioPlayer.stop();
reset7+
reset(): void
重置播放音频资源。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
示例:
audioPlayer.on('reset', () => { //设置'reset'事件回调
console.log('audio reset success');
});
audioPlayer.reset();
seek
seek(timeMs: number): void
跳转到指定播放位置。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
timeMs | number | 是 | 指定的跳转时间节点,单位毫秒(ms),取值范围[0, duration]。 |
示例:
audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调
if (seekDoneTime == null) {
console.info('audio seek fail');
return;
}
console.log('audio seek success. seekDoneTime: ' + seekDoneTime);
});
audioPlayer.seek(30000); //seek到30000ms的位置
setVolume
setVolume(vol: number): void
设置音量。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
vol | number | 是 | 指定的相对音量大小,取值范围为[0.00-1.00],1表示最大音量,即100%。 |
示例:
audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调
console.log('audio volumeChange success');
});
audioPlayer.setVolume(1); //设置音量到100%
release
release(): void
释放音频资源。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
示例:
audioPlayer.release();
audioPlayer = undefined;
getTrackDescription8+
getTrackDescription(callback: AsyncCallback<Array<MediaDescription>>): void
通过回调方式获取音频轨道信息。需在dataLoad事件成功触发后,才能调用。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
callback | AsyncCallback<Array<MediaDescription>> | 是 | 音频轨道信息MediaDescription数组回调方法。 |
示例:
function printfDescription(obj) {
for (let item in obj) {
let property = obj[item];
console.info('audio key is ' + item);
console.info('audio value is ' + property);
}
}
audioPlayer.getTrackDescription((error, arrList) => {
if (arrList != null) {
for (let i = 0; i < arrList.length; i++) {
printfDescription(arrList[i]);
}
} else {
console.log(`audio getTrackDescription fail, error:${error}`);
}
});
getTrackDescription8+
getTrackDescription(): Promise<Array<MediaDescription>>
通过Promise方式获取音频轨道信息。需在dataLoad事件成功触发后,才能调用
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
返回值:
类型 | 说明 |
Promise<Array<MediaDescription>> | 音频轨道信息MediaDescription数组Promise返回值。 |
示例:
function printfDescription(obj) {
for (let item in obj) {
let property = obj[item];
console.info('audio key is ' + item);
console.info('audio value is ' + property);
}
}
let arrayDescription = null
audioPlayer.getTrackDescription().then((arrList) => {
if (arrList != null) {
arrayDescription = arrList;
} else {
console.log('audio getTrackDescription fail');
}
}).catch((error) => {
console.info(`audio catchCallback, error:${error}`);
});
for (let i = 0; i < arrayDescription.length; i++) {
printfDescription(arrayDescription[i]);
}
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。 |
示例:
audioPlayer.on('bufferingUpdate', (infoType, value) => {
console.log('audio bufferingInfo type: ' + infoType);
console.log('audio bufferingInfo value: ' + value);
});
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 | 是 | 播放事件回调方法。 |
示例:
import fileio from '@ohos.fileio'
let audioPlayer = media.createAudioPlayer(); //创建一个音频播放实例
audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调,src属性设置成功后,触发此回调
console.info('audio set source success');
audioPlayer.play(); //开始播放,并触发'play'事件回调
});
audioPlayer.on('play', () => { //设置'play'事件回调
console.info('audio play success');
audioPlayer.seek(30000); //调用seek方法,并触发'timeUpdate'事件回调
});
audioPlayer.on('pause', () => { //设置'pause'事件回调
console.info('audio pause success');
audioPlayer.stop(); //停止播放,并触发'stop'事件回调
});
audioPlayer.on('reset', () => { //设置'reset'事件回调
console.info('audio reset success');
audioPlayer.release(); //释放播放实例资源
audioPlayer = undefined;
});
audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调
if (seekDoneTime == null) {
console.info('audio seek fail');
return;
}
console.info('audio seek success, and seek time is ' + seekDoneTime);
audioPlayer.setVolume(0.5); //设置音量为50%,并触发'volumeChange'事件回调
});
audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调
console.info('audio volumeChange success');
audioPlayer.pause(); //暂停播放,并触发'pause'事件回调
});
audioPlayer.on('finish', () => { //设置'finish'事件回调
console.info('audio play finish');
audioPlayer.stop(); //停止播放,并触发'stop'事件回调
});
audioPlayer.on('error', (error) => { //设置'error'事件回调
console.info(`audio error called, error: ${error}`);
});
// 用户选择音频设置fd(本地播放)
let fdPath = 'fd://';
// path路径的码流可通过"hdc file send D:\xxx\01.mp3 /data/accounts/account_0/appdata" 命令,将其推送到设备上
let path = '/data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3';
fileio.open(path).then((fdValue) => {
fdPath = fdPath + '' + fdValue;
console.info('open fd success fd is' + fdPath);
}, (err) => {
console.info('open fd failed err is' + err);
}).catch((err) => {
console.info('open fd failed err is' + err);
});
audioPlayer.src = fdPath; //设置src属性,并触发'dataLoad'事件回调
on('timeUpdate')
on(type: 'timeUpdate', callback: Callback<number>): void
开始订阅音频播放时间更新事件。处于播放状态时,每隔1s上报一次该事件。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 播放事件回调类型,支持的事件包括:'timeUpdate'。 - 'timeUpdate':音频播放时间戳更新,开始播放后自动触发该事件。 |
callback | Callback<number> | 是 | 播放事件回调方法。回调方法入参为更新后的时间戳。 |
示例:
audioPlayer.on('timeUpdate', (newTime) => { //设置'timeUpdate'事件回调
if (newTime == null) {
console.info('audio timeUpadate fail');
return;
}
console.log('audio timeUpadate success. seekDoneTime: ' + newTime);
});
audioPlayer.play(); //开始播放后,自动触发时间戳更新事件
on('error')
on(type: 'error', callback: ErrorCallback): void
开始订阅音频播放错误事件,当上报error错误事件后,用户需处理error事件,退出播放操作。
系统能力: SystemCapability.Multimedia.Media.AudioPlayer
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 播放错误事件回调类型,支持的事件包括:'error'。 - 'error':音频播放中发生错误,触发该事件。 |
callback | ErrorCallback | 是 | 播放错误事件回调方法。 |
示例:
audioPlayer.on('error', (error) => { //设置'error'事件回调
console.info(`audio error called, error: ${error}`);
});
audioPlayer.setVolume(3); //设置volume为无效值,触发'error'事件
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 | 是 | 资源长度,需要基于预置资源的信息输入,非法值会造成音视频资源解析错误 |