> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> **NOTE**
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
媒体子系统为开发者提供一套简单且易于理解的接口，使得开发者能够方便接入系统并使用系统的媒体资源。
The multimedia subsystem provides a set of simple and easy-to-use APIs for you to access the system and use media resources.
媒体子系统包含了音视频相关媒体业务，提供以下常用功能：
This subsystem offers various media services covering audio and video, which provide the following capabilities:
The following capabilities will be provided in later versions: data source audio/video playback, audio/video encoding and decoding, container encapsulation and decapsulation, and media capability query.
## 导入模块
## Modules to Import
```js
importmediafrom'@ohos.multimedia.media';
...
...
@@ -24,17 +24,17 @@ import media from '@ohos.multimedia.media';
createAudioPlayer(): [AudioPlayer](#audioplayer)
同步方式创建音频播放实例。
Creates an **AudioPlayer** instance in synchronous mode.
| [AudioPlayer](#audioplayer) | Returns the **AudioPlayer** instance if the operation is successful; returns **null** otherwise. After the instance is created, you can start, pause, or stop audio playback.|
**示例：**
**Example**
```js
letaudioPlayer=media.createAudioPlayer();
...
...
@@ -44,17 +44,17 @@ let audioPlayer = media.createAudioPlayer();
| MSERR_OK | 0 | The operation is successful.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MSERR_NO_MEMORY | 1 | Failed to allocate memory. The system may have no available memory.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MSERR_OPERATION_NOT_PERMIT | 2 | No permission to perform this operation.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MD_KEY_TRACK_INDEX | "track_index" | Track index, which is a number.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MD_KEY_TRACK_TYPE | "track_type" | Track type, which is a number. For details, see [MediaType](#mediatype8).<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MD_KEY_CODEC_MIME | "codec_mime" | Codec MIME type, which is a string.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MD_KEY_DURATION | "duration" | Media duration, which is a number, in units of ms.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MD_KEY_BITRATE | "bitrate" | Bit rate, which is a number, in units of bit/s.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MD_KEY_WIDTH | "width" | Video width, which is a number, in units of pixel.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MD_KEY_HEIGHT | "height" | Video height, which is a number, in units of pixel.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MD_KEY_FRAME_RATE | "frame_rate" | Video frame rate, which is a number, in units of 100 fps.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MD_KEY_AUD_CHANNEL_COUNT | "channel_count" | Number of audio channels, which is a number.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| MD_KEY_AUD_SAMPLE_RATE | "sample_rate" | Sampling rate, which is a number, in units of Hz.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
Provides methods to manage and play audio. Before calling a method of **AudioPlayer**, you must use [createAudioPlayer()](#mediacreateaudioplayer) to create an **AudioPlayer** instance.
### 属性<a name=audioplayer_属性></a>
For details about the audio playback demo, see [Audio Playback Development](../../media/audio-playback.md).
| src | string | Yes | Yes | Audio media URI. The mainstream audio formats (MP4, AAC, MP3, and OGG) are supported.<br>**Example of supported URIs**:<br>1. FD playback: fd://xxx<br><br>2. HTTP network playback path (under development)<br>3. HLS network playback path (under development)<br>**Note**:<br>To use media materials, you must declare the read permission. Otherwise, the media materials cannot be played properly.<br>**System capability**: SystemCapability.Multimedia.Media.AudioPlayer|
| loop | boolean | Yes | Yes | Whether to loop audio playback. The value **true** means to loop audio playback, and **false** means the opposite.<br>**System capability**: SystemCapability.Multimedia.Media.AudioPlayer|
| currentTime | number | Yes | No | Current audio playback position.<br>**System capability**: SystemCapability.Multimedia.Media.AudioPlayer|
| duration | number | Yes | No | Audio duration.<br>**System capability**: SystemCapability.Multimedia.Media.AudioPlayer|
| state | [AudioState](#audiostate) | Yes | No | Audio playback state.<br>**System capability**: SystemCapability.Multimedia.Media.AudioPlayer|
Starts to play audio resources. This method can be called only after the [dataLoad](#on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')) event is triggered.
| type | string | Yes | Type of the event to subscribe to, which is 'bufferingUpdate' in this example. |
| callback | (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void | Yes | Callback invoked when the event is triggered.<br>When [BufferingInfoType](#bufferinginfotype8) is set to **BUFFERING_PERCENT** or **CACHED_DURATION**, **value** is valid. Otherwise, **value** is fixed at **0**.|
| type | string | Yes | Type of the event to subscribe to. The following events are supported: 'play' \| 'pause' \| 'stop' \| 'reset' \| 'dataLoad' \| 'finish' \| 'volumeChange'<br>- The 'play' event is triggered when the [play()](#play) method is called and audio playback starts.<br>- The 'pause' event is triggered when the [pause()](#pause) method is called and audio playback is paused.<br>- The 'stop' event is triggered when the [stop()](#stop) method is called and audio playback stops.<br>- The 'reset' event is triggered when the [reset()](#reset7) method is called and audio playback is reset.<br>- The 'dataLoad' event is triggered when the audio data is loaded, that is, when the **src** attribute is configured.<br>- The 'finish' event is triggered when the audio playback is finished.<br>- The 'volumeChange' event is triggered when the [setVolume()](#setvolume) method is called and the playback volume is changed.|
| callback | () => void | Yes | Callback invoked when the event is triggered. |
| type | string | Yes | Type of the event to subscribe to, which is 'timeUpdate' in this method.<br>The 'timeUpdate' event is triggered when the [seek()](#seek) method is called.|
| callback | Callback\<number> | Yes | Callback invoked when the event is triggered. The input parameter of the callback is the time when the seek operation is successful. |
| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：音频播放中发生错误，触发该事件。 |
| callback | ErrorCallback | 是 | 播放错误事件回调方法。 |
| type | string | Yes | Type of the event to subscribe to, which is 'error' in this method.<br>The 'error' event is triggered when an error occurs during audio playback.|
| callback | ErrorCallback | Yes | Callback invoked when the event is triggered. |
**示例：**
**Example**
```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.on('error',(error)=>{// Set the error event callback.
console.info(`audio error called, errName is ${error.name}`);// Print the error name.
console.info(`audio error called, errCode is ${error.code}`);// Print the error code.
console.info(`audio error called, errMessage is ${error.message}`);// Print the detailed description of the error type.
Provides methods to manage and play video. Before calling a method of the **VideoPlayer** class, you must call [createVideoPlayer()](#media.createvideoplayer8) to create a [VideoPlayer](#videoplayer8) instance.
### 属性<a name=videoplayer_属性></a>
For details about the video playback demo, see [Video Playback Development](../../media/video-playback.md).
| url<sup>8+</sup> | string | Yes | Yes | Video media URL. The mainstream video formats (MPEG-4, MPEG-TS, WebM, and MKV) are supported.<br>**Example of supported URIs**:<br>1. FD playback: fd://xxx<br><br>**Note**:<br>To use media materials, you must declare the read permission. Otherwise, the media materials cannot be played properly.<br>**System capability**: SystemCapability.Multimedia.Media.VideoPlayer|
| loop<sup>8+</sup> | boolean | Yes | Yes | Whether to loop video playback. The value **true** means to loop video playback, and **false** means the opposite.<br>**System capability**: SystemCapability.Multimedia.Media.VideoPlayer|
| currentTime<sup>8+</sup> | number | Yes | No | Current video playback position.<br>**System capability**: SystemCapability.Multimedia.Media.VideoPlayer|
| duration<sup>8+</sup> | number | Yes | No | Video duration. The value **-1** indicates the live streaming mode.<br>**System capability**: SystemCapability.Multimedia.Media.VideoPlayer|
| state<sup>8+</sup> | [VideoPlayState](#videoplaystate8) | Yes | No | Video playback state.<br>**System capability**: SystemCapability.Multimedia.Media.VideoPlayer|
| width<sup>8+</sup> | number | Yes | No | Video width.<br>**System capability**: SystemCapability.Multimedia.Media.VideoPlayer|
| height<sup>8+</sup> | number | Yes | No | Video height.<br>**System capability**: SystemCapability.Multimedia.Media.VideoPlayer|
Seeks to the specified playback position. If **mode** is not specified, the next key frame at the specified position is played. This API uses a promise to return the result.
| type | string | 是 | 视频缓存事件回调类型，支持的事件：'bufferingUpdate'。 |
| callback | function | 是 | 视频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时，value值有效，否则固定为0。 |
| type | string | Yes | Type of the event to subscribe to, which is 'bufferingUpdate' in this example. |
| callback | function | Yes | Callback invoked when the event is triggered.<br>When [BufferingInfoType](#bufferinginfotype8) is set to **BUFFERING_PERCENT** or **CACHED_DURATION**, **value** is valid. Otherwise, **value** is fixed at **0**.|
| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChanged'。 |
| callback | function | 是 | 视频播放宽高变化事件回调方法，width表示宽，height表示高。 |
| type | string | Yes | Type of the event to subscribe to, which is 'videoSizeChanged' in this example.|
| callback | function | Yes | Callback invoked when the event is triggered. **width** indicates the video width, and **height** indicates the video height. |
| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：视频播放中发生错误，触发该事件。 |
| callback | function | 是 | 播放错误事件回调方法。 |
| type | string | Yes | Type of the event to subscribe to, which is 'error' in this method.<br>The 'error' event is triggered when an error occurs during video playback.|
| callback | function | Yes | Callback invoked when the event is triggered. |
**示例：**
**Example**
```js
videoPlayer.on('error',(error)=>{// 设置'error'事件回调
console.info(`video error called, errName is ${error.name}`);// 打印错误类型名称
console.info(`video error called, errCode is ${error.code}`);// 打印错误码
console.info(`video error called, errMessage is ${error.message}`);// 打印错误类型详细描述
videoPlayer.on('error',(error)=>{// Set the 'error' event callback.
console.info(`video error called, errName is ${error.name}`);// Print the error name.
console.info(`video error called, errCode is ${error.code}`);// Print the error code.
console.info(`video error called, errMessage is ${error.message}`);// Print the detailed description of the error type.
| SEEK_NEXT_SYNC | 0 | Seeks to the next key frame at the specified position. You are advised to use this value for the rewind operation.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| SEEK_PREV_SYNC | 1 | Seeks to the previous key frame at the specified position. You are advised to use this value for the fast-forward operation.<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| value | any | 对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[MediaDescriptionKey](#mediadescriptionkey8)的描述信息。 |
| key | string | Key of the media information. For details about the keys, see [MediaDescriptionKey](#mediadescriptionkey8).<br>**System capability**: SystemCapability.Multimedia.Media.Core|
| value | any | Value of the key. For details about the values, see [MediaDescriptionKey](#mediadescriptionkey8).<br>**System capability**: SystemCapability.Multimedia.Media.Core|
**示例：**
**Example**
```js
functionprintfItemDescription(obj,key){
...
...
@@ -1541,7 +1517,7 @@ function printfItemDescription(obj, key) {
Implements audio recording. Before calling a method of the **AudioRecorder** class, you must call [createAudioRecorder()](#media.createaudiorecorder) to create an [AudioRecorder](#audiorecorder) instance.
Before resetting audio recording, you must call [stop()](#audiorecorder_stop) to stop recording. After audio recording is reset, you must call [prepare()](#audiorecorder_prepare) to set the recording parameters for another recording.
| type | string | Yes | Type of the event to subscribe to. The following events are supported: 'prepare'\|'start'\| 'pause' \| 'resume' \|'stop'\|'release'\|'reset'<br>- The 'prepare' event is triggered when the [prepare](#audiorecorder_prepare) method is called and the audio recording parameters are set.<br>- The 'start' event is triggered when the [start](#audiorecorder_start) method is called and audio recording starts.<br>- The 'pause' event is triggered when the [pause](#audiorecorder_pause) method is called and audio recording is paused.<br>- The 'resume' event is triggered when the [resume](#audiorecorder_resume) method is called and audio recording is resumed.<br>- The 'stop' event is triggered when the [stop](#audiorecorder_stop) method is called and audio recording stops.<br>- The 'release' event is triggered when the [release](#audiorecorder_release) method is called and the recording resource is released.<br>- The 'reset' event is triggered when the [reset](#audiorecorder_reset) method is called and audio recording is reset.|
| callback | ()=>void | Yes | Callback invoked when the event is triggered. |
| type | string | 是 | 录制错误事件回调类型'error'。<br/>- 'error'：音频录制过程中发生错误，触发该事件。 |
| callback | ErrorCallback | 是 | 录制错误事件回调方法。 |
| type | string | Yes | Type of the event to subscribe to, which is 'error' in this method.<br>The 'error' event is triggered when an error occurs during audio recording.|
| callback | ErrorCallback | Yes | Callback invoked when the event is triggered. |
| uri | string | 是 | 视频输出URI：fd://xx (fd number)<br/><br/>文件需要由调用者创建，并赋予适当的权限。 |
| audioEncoder | [AudioEncoder](#audioencoder) | No | Audio encoding format. The default value is **AAC_LC**.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| audioEncodeBitRate | number | No | Audio encoding bit rate. The default value is **48000**.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| audioSampleRate | number | No | Audio sampling rate. The default value is **48000**.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| numberOfChannels | number | No | Number of audio channels. The default value is **2**.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| format | [AudioOutputFormat](#audiooutputformat) | No | Audio output format. The default value is **MPEG_4**.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| location<sup>8+</sup> | [Location](#location8) | No | Geographical location of the recorded audio.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| uri | string | Yes | Audio output URI. Supported: fd://xx (fd number)<br><br>The file must be created by the caller and granted with proper permissions.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| DEFAULT | 0 | Default audio encoding format, which is Adaptive Multi Rate-Narrow Band Speech Codec (AMR-NB).<br>This API is merely defined in OpenHarmony 3.1 Release and cannot be used currently. It can be used in OpenHarmony 3.1 MR.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| AMR_NB | 1 | AMR-NB.<br>This API is merely defined in OpenHarmony 3.1 Release and cannot be used currently. It can be used in OpenHarmony 3.1 MR.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| AMR_WB | 2 | Adaptive Multi Rate-Wide Band Speech Codec (AMR-WB).<br>This API is merely defined in OpenHarmony 3.1 Release and cannot be used currently. It can be used in OpenHarmony 3.1 MR.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| HE_AAC | 4 | High-Efficiency Advanced Audio Coding (HE_AAC).<br>This API is merely defined in OpenHarmony 3.1 Release and cannot be used currently. It can be used in OpenHarmony 3.1 MR.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| DEFAULT | 0 | Default encapsulation format, which is MPEG-4.<br>This API is merely defined in OpenHarmony 3.1 Release and cannot be used currently. It can be used in OpenHarmony 3.1 MR.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| AMR_NB | 3 | AMR_NB.<br>This API is merely defined in OpenHarmony 3.1 Release and cannot be used currently. It can be used in OpenHarmony 3.1 MR.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| AMR_WB | 4 | AMR_WB.<br>This API is merely defined in OpenHarmony 3.1 Release and cannot be used currently. It can be used in OpenHarmony 3.1 MR.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
| AAC_ADTS | 6 | Audio Data Transport Stream (ADTS), which is a transport stream format of AAC-based audio.<br>**System capability**: SystemCapability.Multimedia.Media.AudioRecorder|
Implements video recording. Before calling a method of the **VideoRecorder** class, you must call [createVideoRecorder()](#media.createvideorecorder8) to create a [VideoRecorder](#videorecorder8) instance.
Obtains the surface required for recording in asynchronous mode. This surface is provided for the caller. The caller obtains the **surfaceBuffer** from this surface and fills in the corresponding data.
Obtains the surface required for recording in asynchronous mode. This surface is provided for the caller. The caller obtains the **surfaceBuffer** from this surface and fills in the corresponding data.
This method can be called only after [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) are called, because the data source must pass data to the surface first.
This method can be called only after [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) are called, because the data source must pass data to the surface first.
This method can be called only after [start()](#videorecorder_start1) is called. You can resume recording by calling [resume()](#videorecorder_resume1).
This method can be called only after [start()](#videorecorder_start1) is called. You can resume recording by calling [resume()](#videorecorder_resume1).
| type | string | 是 | 录制错误事件回调类型'error'。<br/>- 'error'：音频录制过程中发生错误，触发该事件。 |
| callback | ErrorCallback | 是 | 录制错误事件回调方法。 |
| type | string | Yes | Type of the event to subscribe to, which is 'error' in this method.<br>The 'error' event is triggered when an error occurs during video recording.|
| callback | ErrorCallback | Yes | Callback invoked when the event is triggered. |
| audioSourceType | [AudioSourceType](#audiosourcetype<sup>8+</sup>) | Yes | Type of the audio source for video recording.<br>**System capability**: SystemCapability.Multimedia.Media.VideoRecorder|
| videoSourceType | [VideoSourceType](#videosourcetype<sup>8+</sup>) | Yes | Type of the video source for video recording.<br>**System capability**: SystemCapability.Multimedia.Media.VideoRecorder|
| orientationHint | number | No | Rotation angle of the recorded video.<br>**System capability**: SystemCapability.Multimedia.Media.VideoRecorder|
| location | [Location](#location8) | No | Geographical location of the recorded video.<br>**System capability**: SystemCapability.Multimedia.Media.VideoRecorder|
| url | string | Yes | Video output URL. Supported: fd://xx (fd number)<br><br>The file must be created by the caller and granted with proper permissions.<br>**System capability**: SystemCapability.Multimedia.Media.VideoRecorder|
## AudioSourceType<sup>8+</sup>
表示视频录制中音频源类型的枚举。
Enumerates the audio source types for video recording.
| fileFormat | [ContainerFormatType](#containerformattype8) | Yes | Container format of a file.<br>**System capability**: SystemCapability.Multimedia.Media.VideoRecorder|
