HarmonyOS API:@ohos.multimedia.media (媒体服务)

joytrian
发布于 2023-4-4 16:02
浏览
0收藏

版本:v3.1 Beta

@ohos.multimedia.media (媒体服务)

更新时间: 2023-02-24 16:50


说明

本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。


媒体子系统为开发者提供一套简单且易于理解的接口,使得开发者能够方便接入系统并使用系统的媒体资源。


媒体子系统包含了音视频相关媒体业务,提供以下常用功能:

导入模块

import media from '@ohos.multimedia.media';

media.createAudioPlayer

createAudioPlayer(): ​​AudioPlayer​

同步方式创建音频播放实例。


系统能力: SystemCapability.Multimedia.Media.AudioPlayer


返回值:

类型

说明

​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​

返回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

HarmonyOS API:@ohos.multimedia.media (媒体服务)-鸿蒙开发者社区

2. http网络播放: ​​http://xx​

3. https网络播放: ​​https://xx​

4. hls网络播放路径:​​http://xx或者https://xx​

需要权限: ohos.permission.READ_MEDIA 或 ohos.permission.INTERNET。

fdSrc9+

​AVFileDescriptor​

音频媒体文件描述,使用场景:应用中的音频资源被连续存储在同一个文件中。

使用示例

假设一个连续存储的音乐文件:

音乐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

​AudioState​

可以查询音频播放的状态,该状态不可作为调用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

资源长度,需要基于预置资源的信息输入,非法值会造成音视频资源解析错误


文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-media-0000001427902672-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001427902672__导入模块​

已于2023-4-4 16:02:09修改
收藏
回复
举报
回复
    相关推荐