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  | 是  | 资源长度,需要基于预置资源的信息输入,非法值会造成音视频资源解析错误  | 





















