# Media
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:
- Audio playback ([AudioPlayer](#audioplayer))
- Audio recording ([AudioRecorder](#audiorecorder))
The following capabilities will be provided in the future: video playback, video recording, data source audio/video playback, audio/video encoding and decoding, container encapsulation and decapsulation, and media capability query.
## Modules to Import
```js
import media from '@ohos.multimedia.media';
```
## media.createAudioPlayer
createAudioPlayer(): [AudioPlayer](#audioplayer)
Creates an **AudioPlayer** instance in synchronous mode.
**Return values**
| Type| Description|
| --------------------------- | ------------------------------------------------------------ |
| [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
var audioPlayer = media.createAudioPlayer();
```
## media.createAudioPlayerAsync8+
createAudioPlayerAsync(callback: AsyncCallback\<[AudioPlayer](#audioplayer)>): void
Creates an **AudioPlayer** instance in asynchronous mode. This method uses a callback to return the result.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------------------------------------ | ---- | ------------------------------ |
| callback | AsyncCallback<[AudioPlayer](#audioplayer)> | Yes| Callback used to return the **AudioPlayer** instance created.|
**Example**
```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.createAudioPlayerAsync8+
createAudioPlayerAsync: Promise<[AudioPlayer](#audioplayer)>
Creates an **AudioPlayer** instance in asynchronous mode. This method uses a promise to return the result.
**Return values**
| Type| Description|
| ------------------------------------ | ----------------------------------- |
| Promise<[AudioPlayer](#audioplayer)> | Promise used to return the **AudioPlayer** instance created.|
**Example**
```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
Creates an **AudioRecorder** instance to control audio recording.
**Return values**
| Type| Description|
| ------------------------------- | ----------------------------------------- |
| [AudioRecorder](#audiorecorder) | Returns the **AudioRecorder** instance if the operation is successful; returns **null** otherwise.|
**Example**
```
var audiorecorder = media.createAudioRecorder();
```
## MediaErrorCode8+
Enumerates the media error codes.
| Name| Value| Description|
| -------------------------- | ---- | -------------------------------------- |
| MSERR_OK | 0 | The operation is successful.|
| MSERR_NO_MEMORY | 1 | Failed to allocate memory. The system may have no available memory.|
| MSERR_OPERATION_NOT_PERMIT | 2 | No permission to perform this operation.|
| MSERR_INVALID_VAL | 3 | Invalid input parameter.|
| MSERR_IO | 4 | An I/O error occurs.|
| MSERR_TIMEOUT | 5 | The operation times out.|
| MSERR_UNKNOWN | 6 | An unknown error occurs.|
| MSERR_SERVICE_DIED | 7 | Invalid server.|
| MSERR_INVALID_STATE | 8 | The operation is not allowed in the current state.|
| MSERR_UNSUPPORTED | 9 | The operation is not supported in the current version.|
## MediaType8+
Enumerates the media types.
| Name| Value| Description|
| ------------------- | ---- | ------------------ |
| MEDIA_TYPE_AUD | 0 | Media.|
| MEDIA_TYPE_VID | 1 | Video.|
| MEDIA_TYPE_SUBTITLE | 2 | Subtitle. (under development)|
## CodecMimeType8+
Enumerates the codec MIME types.
| Name| Value| Description|
| ------------ | ----------------- | ------------------------ |
| AUDIO_MPEG | "audio/mpeg" | Audio in MPEG format.|
| AUDIO_AAC | "audio/mp4a-latm" | Audio in MP4A-LATM format.|
| AUDIO_VORBIS | "audio/vorbis" | Audio in Vorbis format.|
| AUDIO_FLAC | "audio/flac" | Audio in FLAC format.|
## MediaDescriptionKey8+
Enumerates the media description keys.
| Name| Value| Description|
| ------------------------ | --------------- | ------------------------------------------------------------ |
| MD_KEY_TRACK_INDEX | "track_index" | Track index, which is a number.|
| MD_KEY_TRACK_TYPE | "track_type" | Track type, which is a number. For details, see [MediaType](#mediatype8).|
| MD_KEY_CODEC_MIME | "codec_mime" | Codec MIME type, which is a string.|
| MD_KEY_DURATION | "duration" | Media duration, which is a number, in units of ms.|
| MD_KEY_BITRATE | "bitrate" | Bit rate, which is a number, in units of bit/s.|
| MD_KEY_WIDTH | "width" | Video width, which is a number, in units of pixel.|
| MD_KEY_HEIGHT | "height" | Video height, which is a number, in units of pixel.|
| MD_KEY_FRAME_RATE | "frame_rate" | Video frame rate, which is a number, in units of 100 fps.|
| MD_KEY_AUD_CHANNEL_COUNT | "channel_count" | Number of audio channels, which is a number.|
| MD_KEY_AUD_SAMPLE_RATE | "sample_rate" | Sampling rate, which is a number, in units of Hz.|
## BufferingInfoType8+
Enumerates the buffering event types.
| Name| Value| Description|
| ----------------- | ---- | -------------------------- |
| BUFFERING_START | 1 | Buffering starts.|
| BUFFERING_END | 2 | Buffering ends.|
| BUFFERING_PERCENT | 3 | Buffering progress, in percent.|
| CACHED_DURATION | 4 | Cache duration, in milliseconds.|
## AudioPlayer
Manages and plays audio. Before calling a method of the **AudioPlayer** class, you must call [createAudioPlayer()](#media.createaudioplayer) or [createAudioPlayerAsync()](#media.createaudioplayerasync8) to create an [AudioPlayer](#audioplayer) instance.
For details about the audio playback demo, see [Audio Playback Development](.../media/audio-playback.md).
### Attributes
| Name| Type| Readable| Writable| Description|
| ----------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ |
| src | string | Yes| Yes| Audio media URI. The mainstream audio formats (MP4, AAC, MP3, and OGG) are supported.
**Examples of supported URIs**:
1. Local absolute path: file:///data/data/ohos.xxx.xxx/files/test.mp4
![en-us_image_0000001164217678](figures/en-us_image_0000001164217678.png)
2. HTTP network playback path (under development)
3. HLS network playback path (under development)
4. FD playback (under development)
**Precautions**:
Media files can be played only after the read permission is granted.|
| loop | boolean | Yes| Yes| Whether to loop audio playback. The value **true** means to loop audio playback, and **false** means the opposite.|
| currentTime | number | Yes| No| Current audio playback position.|
| duration | number | Yes| No| Audio duration.|
| state | [AudioState](#audiostate) | Yes| No| Audio playback state.|
### play
play(): void
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.
**Example**
```js
audioPlayer.on('play', () => { // Set the 'play' event callback.
console.log('audio play success');
});
audioPlayer.play();
```
### pause
pause(): void
Pauses audio playback.
**Example**
```js
audioPlayer.on('pause', () => { // Set the 'pause' event callback.
console.log('audio pause success');
});
audioPlayer.pause();
```
### stop
stop(): void
Stops audio playback.
**Example**
```js
audioPlayer.on('stop', () => { // Set the 'stop' event callback.
console.log('audio stop success');
});
audioPlayer.stop();
```
### reset7+
reset(): void
Switches the audio resource to be played.
**Example**
```js
audioPlayer.on('reset', () => { // Set the 'reset' event callback.
console.log('audio reset success');
});
audioPlayer.reset();
```
### seek
seek(timeMs: number): void
Seeks to the specified playback position.
**Parameters**
| Name| Type| Mandatory| Description|
| ------ | ------ | ---- | ------------------------------ |
| timeMs | number | Yes| Position to seek to, in milliseconds.|
**Example**
```js
audioPlayer.on('timeUpdate', (seekDoneTime) => { // Set the 'timeUpdate' event callback.
if (typeof (seekDoneTime) == 'undefined') {
console.info('audio seek fail');
return;
}
console.log('audio seek success. seekDoneTime: ' + seekDoneTime);
});
audioPlayer.seek(30000); // Seek to 30000 ms.
```
### setVolume
setVolume(vol: number): void
Sets the volume.
**Parameters**
| Name| Type| Mandatory| Description|
| ------ | ------ | ---- | ------------------------------------------------------------ |
| vol | number | Yes| Relative volume. The value ranges from 0.00 to 1.00. The value **1** indicates the maximum volume (100%).|
**Example**
```js
audioPlayer.on('volumeChange', () => { // Set the 'volumeChange' event callback.
console.log('audio volumeChange success');
});
audioPlayer.setVolume(1); // Set the volume to 100%.
```
### release
release(): void
Releases this **AudioPlayer** instance.
**Example**
```js
audioPlayer.release();
audioPlayer = undefined;
```
### getTrackDescription8+
getTrackDescription(callback: AsyncCallback>): void
Obtains the audio track information. This method uses a callback to return the result.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------------------------------------------------------ | ---- | -------------------------- |
| callback | AsyncCallback> | Yes| Callback used to return the audio track information obtained.|
**Example**
```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}`);
}
});
```
### getTrackDescription8+
getTrackDescription(): Promise>
Obtains the audio track information. This method uses a promise to return the result.
**Return values**
| Type| Description|
| ------------------------------------------------------ | ------------------------------- |
| Promise> | Promise used to return the audio track information obtained.|
**Example**
```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')8+
on(type: 'bufferingUpdate', callback: (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void): void
Subscribes to the audio buffering update event.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| 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.
When [BufferingInfoType](#bufferinginfotype8) is set to **BUFFERING_PERCENT** or **CACHED_DURATION**, **value** is valid. Otherwise, **value** is fixed at **0**.|
**Example**
```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
Subscribes to the audio playback events.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ---------- | ---- | ------------------------------------------------------------ |
| type | string | Yes| Type of the event to subscribe to. The following events are supported: 'play' \| 'pause' \| 'stop' \| 'reset' \| 'dataLoad' \| 'finish' \| 'volumeChange'
- The 'play' event is triggered when the [play()](#audioplayer_play) method is called and audio playback starts.
- The 'pause' event is triggered when the [pause()](#audioplayer_pause) method is called and audio playback is paused.
- The 'stop' event is triggered when the [stop()](#audioplayer_stop) method is called and audio playback stops.
- The 'reset' event is triggered when the [reset()](#audioplayer_reset) method is called and audio playback is reset.
- The 'dataLoad' event is triggered when the audio data is loaded, that is, when the **src** attribute is configured.
- The 'finish' event is triggered when the audio playback is finished.
- The 'volumeChange' event is triggered when the [setVolume()](#audioplayer_setvolume) method is called and the playback volume is changed.|
| callback | () => void | Yes| Callback invoked when the event is triggered.|
**Example**
```js
let audioPlayer = media.createAudioPlayer(); // Create an AudioPlayer instance.
audioPlayer.on('dataLoad', () => { // Set the 'dataLoad' event callback, which is triggered when the src attribute is set successfully.
console.info('audio set source success');
audioPlayer.play(); // Start the playback and trigger the 'play' event callback.
});
audioPlayer.on('play', () => { // Set the 'play' event callback.
console.info('audio play success');
audioPlayer.seek(30000); // Call the seek() method and trigger the 'timeUpdate' event callback.
});
audioPlayer.on('pause', () => { // Set the 'pause' event callback.
console.info('audio pause success');
audioPlayer.stop(); // Stop the playback and trigger the 'stop' event callback.
});
audioPlayer.on('reset', () => { // Set the 'reset' event callback.
console.info('audio reset success');
audioPlayer.release(); // Release the AudioPlayer instance.
audioPlayer = undefined;
});
audioPlayer.on('timeUpdate', (seekDoneTime) => { // Set the 'timeUpdate' event callback.
if (typeof(seekDoneTime) == "undefined") {
console.info('audio seek fail');
return;
}
console.info('audio seek success, and seek time is ' + seekDoneTime);
audioPlayer.setVolume(0.5); // Set the volume to 50% and trigger the 'volumeChange' event callback.
});
audioPlayer.on('volumeChange', () => { // Set the 'volumeChange' event callback.
console.info('audio volumeChange success');
audioPlayer.pause(); // Pause the playback and trigger the 'pause' event callback.
});
audioPlayer.on('finish', () => { // Set the 'finish' event callback.
console.info('audio play finish');
audioPlayer.stop(); // Stop the playback and trigger the 'stop' event callback.
});
audioPlayer.on('error', (error) => { // Set the 'error' event callback.
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'; // Set the src attribute and trigger the 'dataLoad' event callback.
```
### on('timeUpdate')
on(type: 'timeUpdate', callback: Callback\): void
Subscribes to the 'timeUpdate' event.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ----------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes| Type of the event to subscribe to, which is 'timeUpdate' in this method.
The 'timeUpdate' event is triggered when the [seek()](#audioplayer_seek) method is called.|
| callback | Callback\ | Yes| Callback invoked when the event is triggered. The input parameter of the callback is the time when the seek operation is successful.|
**Example**
```js
audioPlayer.on('timeUpdate', (seekDoneTime) => { // Set the 'timeUpdate' event callback.
if (typeof (seekDoneTime) == 'undefined') {
console.info('audio seek fail');
return;
}
console.log('audio seek success. seekDoneTime: ' + seekDoneTime);
});
audioPlayer.seek(30000); // Seek to 30000 ms.
```
### on('error')
on(type: 'error', callback: ErrorCallback): void
Subscribes to the audio playback error event.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes| Type of the event to subscribe to, which is 'error' in this method.
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) => { // 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.
});
audioPlayer.setVolume(3); // Set volume to an invalid value to trigger the 'error' event.
```
## AudioState
Describes the audio playback state. You can obtain the state through the **state** attribute.
| Name| Type| Description|
| ------------------ | ------ | -------------- |
| idle | string | Audio playback is idle.|
| playing | string | Audio playback is in progress.|
| paused | string | Audio playback is paused.|
| stopped | string | Audio playback is stopped.|
| error8+ | string | Audio playback is in the error state.|
## MediaDescription8+
### [key : string] : any
Defines media information in key-value mode.
| Name| Type| Description|
| ----- | ------ | ------------------------------------------------------------ |
| key | string | Key of the media information. For details about the keys, see [MediaDescriptionKey](#mediadescriptionkey8).|
| value | any | Value of the key. For details about the values, see [MediaDescriptionKey](#mediadescriptionkey8).|
**Example**
```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); // Print the MD_KEY_TRACK_TYPE value of each track.
}
} else {
console.log(`audio getTrackDescription fail, error:${error.message}`);
}
});
```
## AudioRecorder
Implements audio recording. Before calling a method of the **AudioRecorder** class, you must call [createAudioRecorder()](#createaudiorecorder-audiorecorder) to create an **AudioRecorder** instance.
### prepare
prepare(config: AudioRecorderConfig): void
Prepares for recording.
**Parameters**
| Name| Type| Mandatory| Description|
| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ |
| config | [AudioRecorderConfig](#audiorecorderconfig) | Yes| Recording parameters, including the audio output URI, encoding format, sampling rate, and number of audio channels.|
**Example**
```
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
Starts audio recording.
**Example**
```
audiorecorder.start();
```
### stop
stop(): void
Stops audio recording.
**Example**
```
audiorecorder.stop();
```
### release
release(): void
Releases this **AudioRecorder** instance.
**Example**
```
audiorecorder.release();
```
### reset
reset(): void
Resets audio recording.
Before resetting audio recording, you must call **stop()** to stop recording. After audio recording is reset, you must call **prepare()** to set the recording configurations for another recording.
**Example**
```
audiorecorder.reset();
```
### on('prepare' | 'start' | 'stop' | 'release' | 'reset')
on(type: 'prepare' | 'start' | 'stop' | 'release' | 'reset', callback: () => void): void
Subscribes to the audio recording events.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type | string | Yes| Type of the event to subscribe to. The following events are supported: 'prepare'\|'start'\|'stop'\|'release'\|'reset'
- The 'prepare' event is triggered when audio recording preparation is complete.
- The 'start' event is triggered when audio recording starts.
- The 'stop' event is triggered when audio recording is stopped.
- The 'release' event is triggered when the resources related to audio recording are released.
- The 'reset' event is triggered when audio recording is reset.|
| callback | function | Yes| Callback invoked when the event is triggered.|
**Example**
```
audiorecorder.on('prepare', () => {
console.log('Preparation succeeded.');
audiorecorder.start();
});
```
### on('error')
on(type: 'error', callback: ErrorCallback): void
Subscribes to the audio recording error event.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes| Type of the event to subscribe to, which is 'error' in this method.
The 'error' event is triggered when an error occurs during audio recording.|
| callback | ErrorCallback | Yes| Callback invoked when the event is triggered.|
## AudioRecorderConfig
Describes audio recording configurations.
| Name| Type| Mandatory| Description|
| ------------------ | --------------------------------------- | ---- | ------------------------------------------------------------ |
| audioEncoder | [AudioEncoder](#audioencoder) | No| Audio encoding format. The default value is **AAC_LC**.|
| audioEncodeBitRate | number | No| Audio encoding bit rate. The default value is **48000**.|
| audioSampleRate | number | No| Audio sampling rate. The default value is **48000**.|
| numberOfChannels | number | No| Number of audio channels. The default value is **2**.|
| format | [AudioOutputFormat](#audiooutputformat) | No| Audio output format. The default value is **MPEG_4**.|
| uri | string | Yes| Audio output URI. The following URI types are supported:
1. Absolute file path: file:///data/data/ohos.xxx.xxx/cache/test.mp4![en-us_image_0000001164217678](figures/en-us_image_0000001164217678.png)
2. FD path: file://1 (fd number)|
## AudioEncoder
Enumerates the audio encoding formats.
| Name| Default Value| Description|
| ------ | ------ | ------------------------------------------------------------ |
| AAC_LC | 3 | Advanced Audio Coding Low Complexity (AAC-LC).|
## AudioOutputFormat
Enumerates the audio output formats.
| Name| Default Value| Description|
| -------- | ------ | ------------------------------------------------------------ |
| MPEG_4 | 2 | MPEG-4.|
| AAC_ADTS | 6 | Audio Data Transport Stream (ADTS), which is a transport stream format of AAC-based audio.|