# 媒体服务媒体子系统为开发者提供一套简单且易于理解的接口，使得开发者能够方便接入系统并使用系统的媒体资源。媒体子系统包含了音视频相关媒体业务，提供以下常用功能： - 音频播放（[AudioPlayer](#audioplayer)） - 音频录制（[AudioRecorder](#audiorecorder)）后续将提供以下功能：视频播放、视频录制、DataSource音视频播放、音视频编解码、容器封装解封装、媒体能力查询等功能。 ## 导入模块 ```js import media from '@ohos.multimedia.media'; ``` ## media.createAudioPlayer createAudioPlayer(): [AudioPlayer](#audioplayer) 同步方式创建音频播放实例。 **返回值：** | 类型 | 说明 | | --------------------------- | ------------------------------------------------------------ | | [AudioPlayer](#audioplayer) | 返回AudioPlayer类实例，失败时返回null。可用于音频播放、暂停、停止等操作。 | **示例：** ```js var audioPlayer = media.createAudioPlayer(); ``` ## media.createAudioPlayerAsync⁸⁺ createAudioPlayerAsync(callback: AsyncCallback\<[AudioPlayer](#audioplayer)>): void 异步方式创建音频播放实例。通过注册回调函数获取返回值。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------ | ---- | ------------------------------ | | callback | AsyncCallback<[AudioPlayer](#audioplayer)> | 是 | 异步创建音频播放实例回调方法。 | **示例：** ```js media.createAudioPlayerAsync((error, audio) => { if (typeof(audio) != 'undefined') { audioPlayer = audio; console.info('audio createAudioPlayerAsync success'); } else { console.info(`audio createAudioPlayerAsync fail, error:${error.message}`); } }); ``` ## media.createAudioPlayerAsync⁸⁺ createAudioPlayerAsync: Promise<[AudioPlayer](#audioplayer)> 异步方式创建音频播放实例。通过Promise获取返回值。 **返回值：** | 类型 | 说明 | | ------------------------------------ | ----------------------------------- | | Promise<[AudioPlayer](#audioplayer)> | 异步创建音频播放实例Promise返回值。 | **示例：** ```js function failureCallback(error) { console.info(`audio failureCallback, error:${error.message}`); } function catchCallback(error) { console.info(`audio catchCallback, error:${error.message}`); } await media.createAudioPlayerAsync.then((audio) => { if (typeof(audio) != 'undefined') { audioPlayer = audio; console.info('audio createAudioPlayerAsync success'); } else { console.info('audio createAudioPlayerAsync fail'); } }, failureCallback).catch(catchCallback); ``` ## media.createAudioRecorder createAudioRecorder(): AudioRecorder 创建音频录制的实例来控制音频的录制。 **返回值:** | 类型 | 说明 | | ------------------------------- | ----------------------------------------- | | [AudioRecorder](#audiorecorder) | 返回AudioRecorder类实例，失败时返回null。 | **示例：** ``` var audiorecorder = media.createAudioRecorder(); ``` ## MediaErrorCode⁸⁺ 媒体服务错误类型枚举 | 名称 | 值 | 说明 | | -------------------------- | ---- | -------------------------------------- | | 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 | 表示在当前版本下，不支持此操作。 | ## MediaType⁸⁺ 媒体类型枚举 | 名称 | 值 | 说明 | | ------------------- | ---- | ------------------ | | MEDIA_TYPE_AUD | 0 | 表示音频。 | | MEDIA_TYPE_VID | 1 | 表示视频。 | | MEDIA_TYPE_SUBTITLE | 2 | 表示字幕：开发中。 | ## CodecMimeType⁸⁺ Codec MIME类型枚举 | 名称 | 值 | 说明 | | ------------ | ----------------- | ------------------------ | | AUDIO_MPEG | "audio/mpeg" | 表示音频/mpeg类型。 | | AUDIO_AAC | "audio/mp4a-latm" | 表示音频/mp4a-latm类型。 | | AUDIO_VORBIS | "audio/vorbis" | 表示音频/vorbis类型。 | | AUDIO_FLAC | "audio/flac" | 表示音频/flac类型。 | ## MediaDescriptionKey⁸⁺ 媒体信息描述枚举 | 名称 | 值 | 说明 | | ------------------------ | --------------- | ------------------------------------------------------------ | | MD_KEY_TRACK_INDEX | "track_index" | 表示轨道序号，其对应键值类型为number。 | | MD_KEY_TRACK_TYPE | "track_type" | 表示轨道类型，其对应键值类型为number，参考[MediaType](#mediatype8)。 | | 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，单位为像素。 | | MD_KEY_HEIGHT | "height" | 表示视频高度，其对应键值类型为number，单位为像素。 | | MD_KEY_FRAME_RATE | "frame_rate" | 表示视频帧率，其对应键值类型为number，单位为100fps。 | | MD_KEY_AUD_CHANNEL_COUNT | "channel_count" | 表示声道数，其对应键值类型为number。 | | MD_KEY_AUD_SAMPLE_RATE | "sample_rate" | 表示采样率，其对应键值类型为number，单位为HZ。 | ## BufferingInfoType⁸⁺ 缓存事件类型枚举 | 名称 | 值 | 说明 | | ----------------- | ---- | -------------------------- | | BUFFERING_START | 1 | 表示开始缓存。 | | BUFFERING_END | 2 | 表示结束缓存。 | | BUFFERING_PERCENT | 3 | 表示缓存百分比。 | | CACHED_DURATION | 4 | 表示缓存时长，单位为毫秒。 | ## AudioPlayer 音频播放管理类，用于管理和播放音频媒体。在调用AudioPlayer的方法前，需要先通过[createAudioPlayer()](#media.createaudioplayer)或[createAudioPlayerAsync()](#media.createaudioplayerasync8)构建一个[AudioPlayer](#audioplayer)实例。音频播放demo可参考：[音频播放开发指导](../../media/audio-playback.md) ### 属性 | 名称 | 类型 | 可读 | 可写 | 说明 | | ----------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ | | src | string | 是 | 是 | 音频媒体URI，支持当前主流的音频格式(mp4、aac、mp3、ogg)。
**支持路径示例**：
1、本地绝对路径：file:///data/data/ohos.xxx.xxx/files/test.mp4
![zh-cn_image_0000001164217678](figures/zh-cn_image_0000001164217678.png)
2、http网络播放路径：开发中
3、hls网络播放路径：开发中
4、fd类型播放：开发中
**注意事项**：
媒体素材需至少赋予读权限后，才可正常播放 | | loop | boolean | 是 | 是 | 音频循环播放属性，设置为'true'表示循环播放。 | | currentTime | number | 是 | 否 | 音频的当前播放位置。 | | duration | number | 是 | 否 | 音频时长。 | | state | [AudioState](#audiostate) | 是 | 否 | 音频播放的状态。 | ### play play(): void 开始播放音频资源，需在[dataLoad](#on('play' | 'pause' | 'stop' | 'reset' | 'dataload' | 'finish' | 'volumechange'))事件成功触发后，才能调用play方法。 **示例：** ```js audioPlayer.on('play', () => { //设置'play'事件回调 console.log('audio play success'); }); audioPlayer.play(); ``` ### pause pause(): void 暂停播放音频资源。 **示例：** ```js audioPlayer.on('pause', () => { //设置'pause'事件回调 console.log('audio pause success'); }); audioPlayer.pause(); ``` ### stop stop(): void 停止播放音频资源。 **示例：** ```js audioPlayer.on('stop', () => { //设置'stop'事件回调 console.log('audio stop success'); }); audioPlayer.stop(); ``` ### reset⁷⁺ reset(): void 切换播放音频资源。 **示例：** ```js audioPlayer.on('reset', () => { //设置'reset'事件回调 console.log('audio reset success'); }); audioPlayer.reset(); ``` ### seek seek(timeMs: number): void 跳转到指定播放位置。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------------------ | | timeMs | number | 是 | 指定的跳转时间节点，单位毫秒。 | **示例：** ```js audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调 if (typeof (seekDoneTime) == 'undefined') { console.info('audio seek fail'); return; } console.log('audio seek success. seekDoneTime: ' + seekDoneTime); }); audioPlayer.seek(30000); //seek到30000ms的位置 ``` ### setVolume setVolume(vol: number): void 设置音量。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------------------------------------------------ | | vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | **示例：** ```js audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调 console.log('audio volumeChange success'); }); audioPlayer.setVolume(1); //设置音量到100% ``` ### release release(): void 释放音频资源。 **示例：** ```js audioPlayer.release(); audioPlayer = undefined; ``` ### getTrackDescription⁸⁺ getTrackDescription(callback: AsyncCallback>): void 通过回调方式获取音频轨道信息。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | -------------------------- | | callback | AsyncCallback> | 是 | 获取音频轨道信息回调方法。 | **示例：** ```js 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 (typeof (arrlist) != 'undefined') { for (let i = 0; i < arrlist.length; i++) { printfDescription(arrlist[i]); } } else { console.log(`audio getTrackDescription fail, error:${error.message}`); } }); ``` ### getTrackDescription⁸⁺ getTrackDescription(): Promise> 通过Promise方式获取音频轨道信息。 **返回值：** | 类型 | 说明 | | ------------------------------------------------------ | ------------------------------- | | Promise> | 获取音频轨道信息Promise返回值。 | **示例：** ```js function printfDescription(obj) { for (let item in obj) { let property = obj[item]; console.info('audio key is ' + item); console.info('audio value is ' + property); } } function failureCallback(error) { console.info(`audio failureCallback, error:${error.message}`); } function catchCallback(error) { console.info(`audio catchCallback, error:${error.message}`); } await audioPlayer.getTrackDescription.then((arrlist) => { if (typeof (arrlist) != 'undefined') { arrayDescription = arrlist; } else { console.log('audio getTrackDescription fail'); } }, failureCallback).catch(catchCallback); for (let i = 0; i < arrayDescription.length; i++) { printfDescription(arrayDescription[i]); } ``` ### on('bufferingUpdate')⁸⁺ on(type: 'bufferingUpdate', callback: (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void): void 开始订阅音频缓存更新事件。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 音频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | | callback | (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void | 是 | 音频缓存事件回调方法。
[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时，value值有效，否则固定为0。 | **示例：** ```js 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 开始订阅音频播放事件。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 播放事件回调类型，支持的事件包括：'play' \| 'pause' \| 'stop' \| 'reset' \| 'dataLoad' \| 'finish' \| 'volumeChange'。
- 'play'：完成[play()](#play)调用，音频开始播放，触发该事件。
- 'pause'：完成[pause()](#pause)调用，音频暂停播放，触发该事件。
- 'stop'：完成[stop()](#stop)调用，音频停止播放，触发该事件。
- 'reset'：完成[reset()](#reset7)调用，播放器重置，触发该事件。
- 'dataLoad'：完成音频数据加载后触发该事件，即src属性设置完成后触发该事件。
- 'finish'：完成音频播放后触发该事件。
- 'volumeChange'：完成[setVolume()](#setvolume)调用，播放音量改变后触发该事件。 | | callback | () => void | 是 | 播放事件回调方法。 | **示例：** ```js 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 (typeof(seekDoneTime) == "undefined") { 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, errName is ${error.name}`); console.info(`audio error called, errCode is ${error.code}`); console.info(`audio error called, errMessage is ${error.message}`); }); audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp4'; //设置src属性，并触发'dataLoad'事件回调 ``` ### on('timeUpdate') on(type: 'timeUpdate', callback: Callback\): void 开始订阅音频播放[seek()](#seek)时间更新事件。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 播放事件回调类型，支持的事件包括：'timeUpdate'。
- 'timeUpdate'：[seek()](#seek)调用完成，触发该事件。 | | callback | Callback\ | 是 | 播放事件回调方法。回调方法入参为成功seek的时间。 | **示例：** ```js audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调 if (typeof (seekDoneTime) == 'undefined') { console.info('audio seek fail'); return; } console.log('audio seek success. seekDoneTime: ' + seekDoneTime); }); audioPlayer.seek(30000); //seek到30000ms的位置 ``` ### on('error') on(type: 'error', callback: ErrorCallback): void 开始订阅音频播放错误事件。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。
- 'error'：音频播放中发生错误，触发该事件。 | | callback | ErrorCallback | 是 | 播放错误事件回调方法。 | **示例：** ```js audioPlayer.on('error', (error) => { //设置'error'事件回调 console.info(`audio error called, errName is ${error.name}`); //打印错误类型名称 console.info(`audio error called, errCode is ${error.code}`); //打印错误码 console.info(`audio error called, errMessage is ${error.message}`);//打印错误类型详细描述 }); audioPlayer.setVolume(3); //设置volume为无效值，触发'error'事件 ``` ## AudioState 音频播放的状态机。可通过state属性获取当前状态。 | 名称 | 类型 | 描述 | | ------------------ | ------ | -------------- | | idle | string | 音频播放空闲。 | | playing | string | 音频正在播放。 | | paused | string | 音频暂停播放。 | | stopped | string | 音频播放停止。 | | error⁸⁺ | string | 错误状态。 | ## MediaDescription⁸⁺ ### [key : string] : any 通过key-value方式获取媒体信息 | 名称 | 类型 | 说明 | | ----- | ------ | ------------------------------------------------------------ | | key | string | 通过key值获取对应的value。key值具体可见[MediaDescriptionKey](#mediadescriptionkey8)。 | | value | any | 对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[MediaDescriptionKey](#mediadescriptionkey8)的描述信息。 | **示例：** ```js function printfItemDescription(obj, key) { let property = obj[key]; console.info('audio key is ' + key); console.info('audio value is ' + property); } audioPlayer.getTrackDescription((error, arrlist) => { if (typeof (arrlist) != 'undefined') { for (let i = 0; i < arrlist.length; i++) { printfItemDescription(arrlist[i], MD_KEY_TRACK_TYPE); //打印出每条轨道MD_KEY_TRACK_TYPE的值 } } else { console.log(`audio getTrackDescription fail, error:${error.message}`); } }); ``` ## AudioRecorder 音频录制管理类，用于录制音频媒体。在调用AudioRecorder的方法前，需要先通过[createAudioRecorder()](#mediacreateaudiorecorder)构建一个AudioRecorder实例。 ### prepare prepare(config: AudioRecorderConfig): void 录音准备。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ | | config | [AudioRecorderConfig](#audiorecorderconfig) | 是 | 配置录音的相关参数，包括音频输出URI、编码格式、采样率、声道数等。 | **示例：** ``` var audiorecorder = media.createAudioRecorder(); let audioRecorderConfig = { audioEncoder : AAC_LC , audioEncodeBitRate : 22050, audioSampleRate : 22050, numberOfChannels : 2, format : AAC_ADTS, uri : 'file:///data/accounts/account_0/appdata/appdata/recorder/test.m4a', } audiorecorder.prepare(audioRecorderConfig) ``` ### start start(): void 开始录音。 **示例：** ``` var audiorecorder = media.createAudioRecorder(); audiorecorder.start(); ``` ### stop stop(): void 停止录音。 **示例：** ``` var audiorecorder = media.createAudioRecorder(); audiorecorder.stop(); ``` ### release release(): void 释放录音资源。 **示例：** ``` var audiorecorder = media.createAudioRecorder(); audiorecorder.release(); ``` ### reset reset(): void 重置录音。进行重置录音之前，需要先调用stop()停止录音。重置录音之后，需要调用prepare()设置录音配置项，才能再次进行录音。 **示例：** ``` var audiorecorder = media.createAudioRecorder(); audiorecorder.reset(); ``` ### on('prepare' | 'start' | 'stop' | 'release' | 'reset') on(type: 'prepare' | 'start' | 'stop' | 'release' | 'reset', callback: () => void): void 开始订阅音频录制事件。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 录制事件回调类型，支持的事件包括：'prepare' \| 'start' \| 'stop' \| 'release' \| 'reset'。
- 'prepare' ：音频录制准备完成后，触发该事件。
- 'start' ：音频录制开始后，触发该事件。
- 'stop' ：音频录制停止后，触发该事件。
- 'release' ：音频录制相关资源释放后，触发该事件。
- 'reset'：音频录制重置后，触发该事件。 | | callback | function | 是 | 录制事件回调方法。 | **示例：** ``` var audiorecorder = media.createAudioRecorder(); audiorecorder.on('prepare', () => { console.log('Preparation succeeded.'); audiorecorder.start(); }); ``` ### on('error') on(type: 'error', callback: ErrorCallback): void 开始订阅音频录制错误事件。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 录制错误事件回调类型'error'。
- 'error'：音频录制过程中发生错误，触发该事件。 | | callback | ErrorCallback | 是 | 录制错误事件回调方法。 | ## AudioRecorderConfig 表示音频的录音配置。 | 名称 | 参数类型 | 必填 | 说明 | | ------------------ | --------------------------------------- | ---- | ------------------------------------------------------------ | | audioEncoder | [AudioEncoder](#audioencoder) | 否 | 音频编码格式，默认设置为AAC_LC。 | | audioEncodeBitRate | number | 否 | 音频编码比特率，默认值为48000。 | | audioSampleRate | number | 否 | 音频采集采样率，默认值为48000。 | | numberOfChannels | number | 否 | 音频采集声道数，默认值为2。 | | format | [AudioOutputFormat](#audiooutputformat) | 否 | 音量输出封装格式，默认设置为MPEG_4。 | | uri | string | 是 | 音频输出URI。支持：
1. 文件的绝对路径：file:///data/data/ohos.xxx.xxx/cache/test.mp4![zh-cn_image_0000001164217678](figures/zh-cn_image_0000001164217678.png)
2. 文件的fd路径：file://1 (fd number) | ## AudioEncoder 表示音频编码格式的枚举。 | 名称 | 默认值 | 说明 | | ------ | ------ | ------------------------------------------------------------ | | AAC_LC | 3 | AAC-LC（Advanced Audio Coding Low Complexity）编码格式。 | ## AudioOutputFormat 表示音频封装格式的枚举。 | 名称 | 默认值 | 说明 | | -------- | ------ | ------------------------------------------------------------ | | MPEG_4 | 2 | 封装为MPEG-4格式。 | | AAC_ADTS | 6 | 封装为ADTS（Audio Data Transport Stream）格式，是AAC音频的传输流格式。 |