diff --git a/en/application-dev/reference/apis/js-apis-media.md b/en/application-dev/reference/apis/js-apis-media.md index 778a22b5bbcac7ce661ed3cdf3c9601a8778e171..896d2a51bf31d8c0cddaecbfb08ac2f82b93cf5c 100644 --- a/en/application-dev/reference/apis/js-apis-media.md +++ b/en/application-dev/reference/apis/js-apis-media.md @@ -3,8 +3,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. -> -> API version 9 is a canary release for trial use. The APIs of this version may be unstable. The multimedia subsystem provides a set of simple and easy-to-use APIs for you to access the system and use media resources. @@ -13,7 +11,6 @@ This subsystem offers various media services covering audio and video, which pro - Audio playback ([AudioPlayer](#audioplayer)) - Video playback ([VideoPlayer](#videoplayer8)) - Audio recording ([AudioRecorder](#audiorecorder)) -- Video recording ([VideoRecorder](#videorecorder9)) 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. @@ -123,65 +120,6 @@ Creates an **AudioRecorder** instance to control audio recording. let audioRecorder = media.createAudioRecorder(); ``` -## media.createVideoRecorder9+ - -createVideoRecorder(callback: AsyncCallback\<[VideoRecorder](#videorecorder9)>): void - -Creates a **VideoRecorder** instance in asynchronous mode. This API uses a callback to return the result. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | ----------------------------------------------- | ---- | ------------------------------ | -| callback | AsyncCallback<[VideoRecorder](#videorecorder9)> | Yes | Callback used to return the **VideoRecorder** instance created.| - -**Example** - -```js -let videoRecorder - -media.createVideoRecorder((error, video) => { - if (typeof(video) != 'undefined') { - videoRecorder = video; - console.info('video createVideoRecorder success'); - } else { - console.info(`video createVideoRecorder fail, error:${error.message}`); - } -}); -``` - -## media.createVideoRecorder9+ - -createVideoRecorder(): Promise<[VideoRecorder](#videorecorder9)> - -Creates a **VideoRecorder** instance in asynchronous mode. This API uses a promise to return the result. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Return value** - -| Type | Description | -| ----------------------------------------- | ----------------------------------- | -| Promise<[VideoRecorder](#videorecorder9)> | Promise used to return the **VideoRecorder** instance created.| - -**Example** - -```js -let videoRecorder - -media.createVideoRecorder().then((video) => { - if (typeof(video) != 'undefined') { - videoRecorder = video; - console.info('video createVideoRecorder success'); - } else { - console.info('video createVideoRecorder fail'); - } -}).catch((error) => { - console.info(`video catchCallback, error:${error.message}`); -}); -``` @@ -276,7 +214,7 @@ For details about the audio playback demo, see [Audio Playback Development](../. | Name | Type | Readable| Writable| Description | | ----------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ | -| src | string | Yes | Yes | Audio media URI. The mainstream audio formats (MPEG-4, AAC, MPEG-3, OGG, and WAV) are supported.
**Example of supported URIs**:
1. FD playback: fd://xx
![](figures/en-us_image_url.png)
2. HTTP network playback: http://xx
3. HLS network playback path (under development)
**Note**:
To use media materials, you must declare the read permission. Otherwise, the media materials cannot be played properly.| +| src | string | Yes | Yes | Audio media URI. The mainstream audio formats (MPEG-4, AAC, MPEG-3, OGG, and WAV) are supported.
**Example of supported URIs**:
1. FD playback: fd://xx
![](figures/en-us_image_url.png)
2. HTTP network playback: http://xx
3. HLS network playback: under development
**Note**:
To use media materials, you must declare the read permission. Otherwise, the media materials cannot be played properly. | | 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. | @@ -503,7 +441,7 @@ Subscribes to the audio buffering update event. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of the event to subscribe to, which is 'bufferingUpdate' in this example. | +| type | string | Yes | Event type, which is 'bufferingUpdate' in this case. | | callback | function | 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** @@ -527,7 +465,7 @@ Subscribes to the audio playback events. | 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) API is called and audio playback starts.
- The 'pause' event is triggered when the [pause()](#audioplayer_pause) API is called and audio playback is paused.
- The 'stop' event is triggered when the [stop()](#audioplayer_stop) API is called and audio playback stops.
- The 'reset' event is triggered when the [reset()](#audioplayer_reset) API 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) API is called and the playback volume is changed.| +| type | string | Yes | Event type. The following events are supported:
- 'play': triggered when the [play()](#audioplayer_play) API is called and audio playback starts.
- 'pause': triggered when the [pause()](#audioplayer_pause) API is called and audio playback is paused.
- 'stop': triggered when the [stop()](#audioplayer_stop) API is called and audio playback stops.
- 'reset': triggered when the [reset()](#audioplayer_reset) API is called and audio playback is reset.
- 'dataLoad': triggered when the audio data is loaded, that is, when the **src** attribute is configured.
- 'finish': triggered when the audio playback is finished.
- 'volumeChange': triggered when the [setVolume()](#audioplayer_setvolume) API is called and the playback volume is changed. | | callback | () => void | Yes | Callback invoked when the event is triggered. | **Example** @@ -600,7 +538,7 @@ Subscribes to the 'timeUpdate' event. | Name | Type | Mandatory| Description | | -------- | ----------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of the event to subscribe to, which is 'timeUpdate' in this API.
The 'timeUpdate' event is triggered when the [seek()](#audioplayer_seek) API is called.| +| type | string | Yes | Event type, which is 'timeUpdate' in this case.
The 'timeUpdate' event is triggered when the [seek()](#audioplayer_seek) API 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** @@ -628,7 +566,7 @@ Subscribes to the audio playback error event. | Name | Type | Mandatory| Description | | -------- | ------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of the event to subscribe to, which is 'error' in this API.
The 'error' event is triggered when an error occurs during audio playback.| +| type | string | Yes | Event type, which is 'error' in this case.
The 'error' event is triggered when an error occurs during audio playback.| | callback | ErrorCallback | Yes | Callback invoked when the event is triggered. | **Example** @@ -658,7 +596,7 @@ Enumerates the audio playback states. You can obtain the state through the **sta ## VideoPlayer8+ -Provides APIs to manage and play video. Before calling an API of the **VideoPlayer** class, you must call [createVideoPlayer()](#mediacreatevideoplayer8) to create a [VideoPlayer](#videoplayer8) instance. +Provides APIs to manage and play video. Before calling an API of **VideoPlayer**, you must call [createVideoPlayer()](#mediacreatevideoplayer8) to create a [VideoPlayer](#videoplayer8) instance. For details about the video playback demo, see [Video Playback Development](../../media/video-playback.md). @@ -668,7 +606,7 @@ For details about the video playback demo, see [Video Playback Development](../. | Name | Type | Readable| Writable| Description | | ------------------------ | ---------------------------------- | ---- | ---- | ------------------------------------------------------------ | -| url8+ | string | Yes | Yes | Video media URL. The mainstream video formats (MPEG-4, MPEG-TS, WebM, and MKV) are supported.
**Example of supported URIs**:
1. FD playback: fd://xx
![](figures/en-us_image_url.png)
2. HTTP network playback: http://xx
3. HLS network playback path (under development)
**Note**:
To use media materials, you must declare the read permission. Otherwise, the media materials cannot be played properly.| +| url8+ | string | Yes | Yes | Video media URL. The mainstream video formats (MPEG-4, MPEG-TS, WebM, and MKV) are supported.
**Example of supported URIs**:
1. FD playback: fd://xx
![](figures/en-us_image_url.png)
2. HTTP network playback: http://xx
3. HLS network playback: under development
**Note**:
To use media materials, you must declare the read permission. Otherwise, the media materials cannot be played properly. | | loop8+ | boolean | Yes | Yes | Whether to loop video playback. The value **true** means to loop video playback, and **false** means the opposite. | | currentTime8+ | number | Yes | No | Current video playback position. | | duration8+ | number | Yes | No | Video duration. The value **-1** indicates the live streaming mode. | @@ -719,8 +657,8 @@ Sets **SurfaceId**. This API uses a promise to return the result. **Return value** -| Type | Description | -| ------------- | ------------------------------ | +| Type | Description | +| -------------- | ------------------------------ | | Promise\ | Promise used to return the result.| **Example** @@ -1327,7 +1265,7 @@ Subscribes to the video playback completion event. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ----------------------------------------------------------- | -| type | string | Yes | Type of the event to subscribe to, which is 'playbackCompleted' in this example.| +| type | string | Yes | Event type, which is 'playbackCompleted' in this case.| | callback | function | Yes | Callback invoked when the event is triggered. | **Example** @@ -1350,7 +1288,7 @@ Subscribes to the video buffering update event. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of the event to subscribe to, which is 'bufferingUpdate' in this example. | +| type | string | Yes | Event type, which is 'bufferingUpdate' in this case. | | callback | function | 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** @@ -1374,7 +1312,7 @@ Subscribes to the frame rendering start event. | Name | Type | Mandatory| Description | | -------- | --------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of the event to subscribe to, which is 'startRenderFrame' in this example.| +| type | string | Yes | Event type, which is 'startRenderFrame' in this case.| | callback | Callback\ | Yes | Callback invoked when the event is triggered. | **Example** @@ -1397,7 +1335,7 @@ Subscribes to the video width and height change event. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of the event to subscribe to, which is 'videoSizeChanged' in this example.| +| type | string | Yes | Event type, which is 'videoSizeChanged' in this case.| | callback | function | Yes | Callback invoked when the event is triggered. **width** indicates the video width, and **height** indicates the video height. | **Example** @@ -1421,7 +1359,7 @@ Subscribes to the video playback error event. | Name | Type | Mandatory| Description | | -------- | ------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of the event to subscribe to, which is 'error' in this API.
The 'error' event is triggered when an error occurs during video playback.| +| type | string | Yes | Event type, which is 'error' in this case.
The 'error' event is triggered when an error occurs during video playback.| | callback | ErrorCallback | Yes | Callback invoked when the event is triggered. | **Example** @@ -1510,7 +1448,7 @@ audioPlayer.getTrackDescription((error, arrlist) => { ## AudioRecorder -Implements audio recording. Before calling an API of the **AudioRecorder** class, you must call [createAudioRecorder()](#mediacreateaudiorecorder) to create an [AudioRecorder](#audiorecorder) instance. +Implements audio recording. Before calling an API of **AudioRecorder**, you must call [createAudioRecorder()](#mediacreateaudiorecorder) to create an [AudioRecorder](#audiorecorder) instance. For details about the audio recording demo, see [Audio Recording Development](../../media/audio-recorder.md). @@ -1528,7 +1466,7 @@ Prepares for recording. | Name| Type | Mandatory| Description | | ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ | -| config | [AudioRecorderConfig](#audiorecorderconfig) | Yes | Audio recording parameters, including the audio output URI, [encoding format](#audioencoder), sampling rate, number of audio channels, and [output format](#audiooutputformat).| +| config | [AudioRecorderConfig](#audiorecorderconfig) | Yes | Audio recording parameters, including the audio output URI, encoding format, sampling rate, number of audio channels, and output format.| **Example** @@ -1666,7 +1604,7 @@ Subscribes to the audio recording events. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of the event to subscribe to. The following events are supported: 'prepare'\|'start'\| 'pause' \| 'resume' \|'stop'\|'release'\|'reset'
- The 'prepare' event is triggered when the [prepare](#audiorecorder_prepare) API is called and the audio recording parameters are set.
- The 'start' event is triggered when the [start](#audiorecorder_start) API is called and audio recording starts.
- The 'pause' event is triggered when the [pause](#audiorecorder_pause) API is called and audio recording is paused.
- The 'resume' event is triggered when the [resume](#audiorecorder_resume) API is called and audio recording is resumed.
- The 'stop' event is triggered when the [stop](#audiorecorder_stop) API is called and audio recording stops.
- The 'release' event is triggered when the [release](#audiorecorder_release) API is called and the recording resource is released.
- The 'reset' event is triggered when the [reset](#audiorecorder_reset) API is called and audio recording is reset.| +| type | string | Yes | Event type. The following events are supported: 'prepare'\|'start'\| 'pause' \| 'resume' \|'stop'\|'release'\|'reset'
- The 'prepare' event is triggered when the [prepare](#audiorecorder_prepare) API is called and the audio recording parameters are set.
- The 'start' event is triggered when the [start](#audiorecorder_start) API is called and audio recording starts.
- The 'pause' event is triggered when the [pause](#audiorecorder_pause) API is called and audio recording is paused.
- The 'resume' event is triggered when the [resume](#audiorecorder_resume) API is called and audio recording is resumed.
- The 'stop' event is triggered when the [stop](#audiorecorder_stop) API is called and audio recording stops.
- The 'release' event is triggered when the [release](#audiorecorder_release) API is called and the recording resource is released.
- The 'reset' event is triggered when the [reset](#audiorecorder_reset) API is called and audio recording is reset.| | callback | ()=>void | Yes | Callback invoked when the event is triggered. | **Example** @@ -1682,34 +1620,34 @@ let audioRecorderConfig = { uri : 'fd://xx', // The file must be created by the caller and granted with proper permissions. location : { latitude : 30, longitude : 130}, } -audioRecorder.on('error', (error) => { // Set the 'error' event callback. +audioRecorder.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}`); }); -audioRecorder.on('prepare', () => { // Set the 'prepare' event callback. +audioRecorder.on('prepare', () => { // Set the prepare event callback. console.log('prepare success'); - audioRecorder.start(); // Start recording and trigger the 'start' event callback. + audioRecorder.start(); // Start recording and trigger the start event callback. }); -audioRecorder.on('start', () => { // Set the 'start' event callback. +audioRecorder.on('start', () => { // Set the start event callback. console.log('audio recorder start success'); }); -audioRecorder.on('pause', () => { // Set the 'pause' event callback. +audioRecorder.on('pause', () => { // Set the pause event callback. console.log('audio recorder pause success'); }); -audioRecorder.on('resume', () => { // Set the 'resume' event callback. +audioRecorder.on('resume', () => { // Set the resume event callback. console.log('audio recorder resume success'); }); -audioRecorder.on('stop', () => { // Set the 'stop' event callback. +audioRecorder.on('stop', () => { // Set the stop event callback. console.log('audio recorder stop success'); }); -audioRecorder.on('release', () => { // Set the 'release' event callback. +audioRecorder.on('release', () => { // Set the release event callback. console.log('audio recorder release success'); }); -audioRecorder.on('reset', () => { // Set the 'reset' event callback. +audioRecorder.on('reset', () => { // Set the reset event callback. console.log('audio recorder reset success'); }); -audioRecorder.prepare(audioRecorderConfig) // Set recording parameters and trigger the 'prepare' event callback. +audioRecorder.prepare(audioRecorderConfig) // Set recording parameters and trigger the prepare event callback. ``` ### on('error') @@ -1724,18 +1662,18 @@ Subscribes to the audio recording error event. | Name | Type | Mandatory| Description | | -------- | ------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of the event to subscribe to, which is 'error' in this API.
The 'error' event is triggered when an error occurs during audio recording.| +| type | string | Yes | Event type, which is 'error' in this case.
The 'error' event is triggered when an error occurs during audio recording.| | callback | ErrorCallback | Yes | Callback invoked when the event is triggered. | **Example** ```js -audioRecorder.on('error', (error) => { // Set the 'error' event callback. +audioRecorder.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. }); -audioRecorder.prepare(); // Do no set any parameter in prepare and trigger the 'error' event callback. +audioRecorder.prepare(); // Do no set any parameter in prepare and trigger the error event callback. ``` ## AudioRecorderConfig @@ -1746,14 +1684,15 @@ Describes audio recording configurations. | Name | Type | Mandatory| Description | | --------------------- | --------------------------------------- | ---- | ------------------------------------------------------------ | -| audioEncoder | [AudioEncoder](#audioencoder) | No | Audio encoding format. The default value is **AAC_LC**. | +| audioEncoder(deprecated) | [AudioEncoder](#audioencoder) | No | Audio encoding format. The default value is **AAC_LC**.
**Note**: This parameter is deprecated since API version 8. Use **audioEncoderMime** instead. | | 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**. | +| format(deprecated) | [AudioOutputFormat](#audiooutputformat) | No | Audio output format. The default value is **MPEG_4**.
**Note**: This parameter is deprecated since API version 8. Use **fileFormat** instead. | | location | [Location](#location) | No | Geographical location of the recorded audio. | -| uri | string | Yes | Audio output URI. Supported: fd://xx (fd number)
![en-us_image_0000001164217678](figures/en-us_image_url.png)
The file must be created by the caller and granted with proper permissions.| -| audioEncoderMime | [CodecMimeType](#codecmimetype8) | No | Audio encoding format. | +| uri | string | Yes | Audio output URI. Supported: fd://xx (fd number)
![](figures/en-us_image_url.png)
The file must be created by the caller and granted with proper permissions.| +| audioEncoderMime8+ | [CodecMimeType](#codecmimetype8) | No | Audio encoding format. | +| fileFormat8+ | [ContainerFormatType](#containerformattype8) | No | Audio encoding format. | ## AudioEncoder(deprecated) @@ -1771,13 +1710,13 @@ Enumerates the audio encoding formats. | AMR_NB | 1 | AMR-NB.
This API is defined but not implemented yet.| | AMR_WB | 2 | Adaptive Multi Rate-Wide Band Speech Codec (AMR-WB).
This API is defined but not implemented yet.| | AAC_LC | 3 | Advanced Audio Coding Low Complexity (AAC-LC).| -| HE_AAC | 4 | High-Efficiency Advanced Audio Coding (HE_AAC).
This API is defined but not implemented yet.| +| HE_AAC | 4 | High-Efficiency Advanced Audio Coding (HE_AAC).
This API is defined but not implemented yet.| ## AudioOutputFormat(deprecated) > **NOTE** -> This API is deprecated since API version 8. You are advised to use [ContainerFormatType ](#containerformattype8) instead. +> This API is deprecated since API version 8. You are advised to use [ContainerFormatType](#containerformattype8) instead. Enumerates the audio output formats. @@ -1791,643 +1730,6 @@ Enumerates the audio output formats. | AMR_WB | 4 | AMR_WB.
This API is defined but not implemented yet.| | AAC_ADTS | 6 | Audio Data Transport Stream (ADTS), which is a transport stream format of AAC-based audio.| -## VideoRecorder9+ - -Implements video recording. Before calling an API of the **VideoRecorder** class, you must call [createVideoRecorder()](#mediacreatevideorecorder9) to create a [VideoRecorder](#videorecorder9) instance. - -For details about the video recording demo, see [Video Recording Development](../../media/video-recorder.md). - -### Attributes - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -| Name | Type | Readable| Writable| Description | -| ------------------ | -------------------------------------- | ---- | ---- | ---------------- | -| state8+ | [VideoRecordState](#videorecordstate9) | Yes | No | Video recording state.| - -### prepare9+ - -prepare(config: VideoRecorderConfig, callback: AsyncCallback\): void; - -Sets video recording parameters in asynchronous mode. This API uses a callback to return the result. - -**Required permissions:** ohos.permission.MICROPHONE - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | -------------------------------------------- | ---- | ----------------------------------- | -| config | [VideoRecorderConfig](#videorecorderconfig9) | Yes | Video recording parameters to set. | -| callback | AsyncCallback\ | Yes | Callback used to return the result.| - -**Example** - -```js -let videoProfile = { - audioBitrate : 48000, - audioChannels : 2, - audioCodec : 'audio/mp4a-latm', - audioSampleRate : 48000, - fileFormat : 'mp4', - videoBitrate : 48000, - videoCodec : 'video/mp4v-es', - videoFrameWidth : 640, - videoFrameHeight : 480, - videoFrameRate : 30 -} - -let videoConfig = { - audioSourceType : 1, - videoSourceType : 0, - profile : videoProfile, - url : 'fd://xx', // The file must be created by the caller and granted with proper permissions. - orientationHint : 0, - location : { latitude : 30, longitude : 130 }, -} - -// asyncallback -let videoRecorder = null; -let events = require('events'); -let eventEmitter = new events.EventEmitter(); - -eventEmitter.on('prepare', () => { - videoRecorder.prepare(videoConfig, (err) => { - if (typeof (err) == 'undefined') { - console.info('prepare success'); - } else { - console.info('prepare failed and error is ' + err.message); - } - }); -}); - -media.createVideoRecorder((err, recorder) => { - if (typeof (err) == 'undefined' && typeof (recorder) != 'undefined') { - videoRecorder = recorder; - console.info('createVideoRecorder success'); - eventEmitter.emit('prepare'); // Trigger the 'prepare' event. - } else { - console.info('createVideoRecorder failed and error is ' + err.message); - } -}); -``` - -### prepare9+ - -prepare(config: VideoRecorderConfig): Promise\; - -Sets video recording parameters in asynchronous mode. This API uses a promise to return the result. - -**Required permissions:** ohos.permission.MICROPHONE and ohos.permission.CAMERA - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | -------------------------------------------- | ---- | ------------------------ | -| config | [VideoRecorderConfig](#videorecorderconfig9) | Yes | Video recording parameters to set.| - -**Return value** - -| Type | Description | -| -------------- | ---------------------------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - -```js -let videoProfile = { - audioBitrate : 48000, - audioChannels : 2, - audioCodec : 'audio/mp4a-latm', - audioSampleRate : 48000, - fileFormat : 'mp4', - videoBitrate : 48000, - videoCodec : 'video/mp4v-es', - videoFrameWidth : 640, - videoFrameHeight : 480, - videoFrameRate : 30 -} - -let videoConfig = { - audioSourceType : 1, - videoSourceType : 0, - profile : videoProfile, - url : 'fd://xx', // The file must be created by the caller and granted with proper permissions. - orientationHint : 0, - location : { latitude : 30, longitude : 130 }, -} - -// promise -let videoRecorder = null; -media.createVideoRecorder().then((recorder) => { - if (typeof (recorder) != 'undefined') { - videoRecorder = recorder; - console.info('createVideoRecorder success'); - } else { - console.info('createVideoRecorder failed'); - } -}).catch((err) => { - console.info('catch err error message is ' + err.message); -}); - -videoRecorder.prepare(videoConfig).then(() => { - console.info('prepare success'); -}).catch((err) => { - console.info('prepare failed and catch error is ' + err.message); -}); -``` - -### getInputSurface9+ - -getInputSurface(callback: AsyncCallback\): void; - -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. - -Note that the video data must carry the timestamp (in ns) and buffer size, and the start time of the timestamp is based on the system startup time. - -This API can be called only after [prepare()](#videorecorder_prepare1) is called. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | --------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to obtain the result.| - -**Example** - -```js -// asyncallback -let surfaceID = null; // Surface ID passed to the external system. -videoRecorder.getInputSurface((err, surfaceId) => { - if (typeof (err) == 'undefined') { - console.info('getInputSurface success'); - surfaceID = surfaceId; - } else { - console.info('getInputSurface failed and error is ' + err.message); - } -}); -``` - -### getInputSurface9+ - -getInputSurface(): Promise\; - - 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. - -Note that the video data must carry the timestamp (in ns) and buffer size, and the start time of the timestamp is based on the system startup time. - -This API can be called only after [prepare()](#videorecorder_prepare1) is called. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Return value** - -| Type | Description | -| ---------------- | -------------------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - -```js -// promise -let surfaceID = null; // Surface ID passed to the external system. -videoRecorder.getInputSurface().then((surfaceId) => { - console.info('getInputSurface success'); - surfaceID = surfaceId; -}).catch((err) => { - console.info('getInputSurface failed and catch error is ' + err.message); -}); -``` - -### start9+ - -start(callback: AsyncCallback\): void; - -Starts video recording in asynchronous mode. This API uses a callback to return the result. - -This API can be called only after [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) are called, because the data source must pass data to the surface first. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ---------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result.| - -**Example** - -```js -// asyncallback -videoRecorder.start((err) => { - if (typeof (err) == 'undefined') { - console.info('start videorecorder success'); - } else { - console.info('start videorecorder failed and error is ' + err.message); - } -}); -``` - -### start9+ - -start(): Promise\; - -Starts video recording in asynchronous mode. This API uses a promise to return the result. - -This API can be called only after [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) are called, because the data source must pass data to the surface first. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Return value** - -| Type | Description | -| -------------- | ------------------------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - -```js -// promise -videoRecorder.start().then(() => { - console.info('start videorecorder success'); -}).catch((err) => { - console.info('start videorecorder failed and catch error is ' + err.message); -}); -``` - -### pause9+ - -pause(callback: AsyncCallback\): void; - -Pauses video recording in asynchronous mode. This API uses a callback to return the result. - -This API can be called only after [start()](#videorecorder_start1) is called. You can resume recording by calling [resume()](#videorecorder_resume1). - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ---------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result.| - -**Example** - -```js -// asyncallback -videoRecorder.pause((err) => { - if (typeof (err) == 'undefined') { - console.info('pause videorecorder success'); - } else { - console.info('pause videorecorder failed and error is ' + err.message); - } -}); -``` - -### pause9+ - -pause(): Promise\; - -Pauses video recording in asynchronous mode. This API uses a promise to return the result. - -This API can be called only after [start()](#videorecorder_start1) is called. You can resume recording by calling [resume()](#videorecorder_resume1). - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Return value** - -| Type | Description | -| -------------- | ------------------------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - -```js -// promise -videoRecorder.pause().then(() => { - console.info('pause videorecorder success'); -}).catch((err) => { - console.info('pause videorecorder failed and catch error is ' + err.message); -}); -``` - -### resume9+ - -resume(callback: AsyncCallback\): void; - -Resumes video recording in asynchronous mode. This API uses a callback to return the result. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ---------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result.| - -**Example** - -```js -// asyncallback -videoRecorder.resume((err) => { - if (typeof (err) == 'undefined') { - console.info('resume videorecorder success'); - } else { - console.info('resume videorecorder failed and error is ' + err.message); - } -}); -``` - -### resume9+ - -resume(): Promise\; - -Resumes video recording in asynchronous mode. This API uses a promise to return the result. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Return value** - -| Type | Description | -| -------------- | ------------------------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - -```js -// promise -videoRecorder.resume().then(() => { - console.info('resume videorecorder success'); -}).catch((err) => { - console.info('resume videorecorder failed and catch error is ' + err.message); -}); -``` - -### stop9+ - -stop(callback: AsyncCallback\): void; - -Stops video recording in asynchronous mode. This API uses a callback to return the result. - -To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) again. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ---------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result.| - -**Example** - -```js -// asyncallback -videoRecorder.stop((err) => { - if (typeof (err) == 'undefined') { - console.info('stop videorecorder success'); - } else { - console.info('stop videorecorder failed and error is ' + err.message); - } -}); -``` - -### stop9+ - -stop(): Promise\; - -Stops video recording in asynchronous mode. This API uses a promise to return the result. - -To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) again. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Return value** - -| Type | Description | -| -------------- | ------------------------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - -```js -// promise -videoRecorder.stop().then(() => { - console.info('stop videorecorder success'); -}).catch((err) => { - console.info('stop videorecorder failed and catch error is ' + err.message); -}); -``` - -### release9+ - -release(callback: AsyncCallback\): void; - -Releases the video recording resource in asynchronous mode. This API uses a callback to return the result. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | -------------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result.| - -**Example** - -```js -// asyncallback -videoRecorder.release((err) => { - if (typeof (err) == 'undefined') { - console.info('release videorecorder success'); - } else { - console.info('release videorecorder failed and error is ' + err.message); - } -}); -``` - -### release9+ - -release(): Promise\; - -Releases the video recording resource in asynchronous mode. This API uses a promise to return the result. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Return value** - -| Type | Description | -| -------------- | ----------------------------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - -```js -// promise -videoRecorder.release().then(() => { - console.info('release videorecorder success'); -}).catch((err) => { - console.info('release videorecorder failed and catch error is ' + err.message); -}); -``` - -### reset9+ - -reset(callback: AsyncCallback\): void; - -Resets video recording in asynchronous mode. This API uses a callback to return the result. - -To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) again. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ---------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result.| - -**Example** - -```js -// asyncallback -videoRecorder.reset((err) => { - if (typeof (err) == 'undefined') { - console.info('reset videorecorder success'); - } else { - console.info('reset videorecorder failed and error is ' + err.message); - } -}); -``` - -### reset9+ - -reset(): Promise\; - -Resets video recording in asynchronous mode. This API uses a promise to return the result. - -To start another recording, you must call [prepare()](#videorecorder_prepare1) and [getInputSurface()](#getinputsurface8) again. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Return value** - -| Type | Description | -| -------------- | ------------------------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - -```js -// promise -videoRecorder.reset().then(() => { - console.info('reset videorecorder success'); -}).catch((err) => { - console.info('reset videorecorder failed and catch error is ' + err.message); -}); -``` - -### on('error')9+ - -on(type: 'error', callback: ErrorCallback): void - -Subscribes to the video recording error event. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | ------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Type of the event to subscribe to, which is 'error' in this API.
The 'error' event is triggered when an error occurs during video recording.| -| callback | ErrorCallback | Yes | Callback invoked when the event is triggered. | - -**Example** - -```js -videoRecorder.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. -}); -// This event is reported when an error occurs during the retrieval of videoRecordState. -``` - -## VideoRecordState9+ - -Enumerates the video recording states. You can obtain the state through the **state** attribute. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -| Name | Type | Description | -| -------- | ------ | ---------------------- | -| idle | string | The video recorder is idle. | -| prepared | string | The video recording parameters are set.| -| playing | string | Video recording is in progress. | -| paused | string | Video recording is paused. | -| stopped | string | Video recording is stopped. | -| error | string | Video recording is in the error state. | - -## VideoRecorderConfig9+ - -Describes the video recording parameters. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -| Name | Type | Mandatory| Description | -| --------------- | ---------------------------------------------- | ---- | ------------------------------------------------------------ | -| audioSourceType | [AudioSourceType](#audiosourcetype9) | Yes | Type of the audio source for video recording. | -| videoSourceType | [VideoSourceType](#videosourcetype9) | Yes | Type of the video source for video recording. | -| profile | [VideoRecorderProfile](#videorecorderprofile9) | Yes | Video recording profile. | -| rotation | number | No | Rotation angle of the recorded video. | -| location | [Location](#location) | No | Geographical location of the recorded video. | -| url | string | Yes | Video output URL. Supported: fd://xx (fd number)
![](figures/en-us_image_url.png)
The file must be created by the caller and granted with proper permissions.| - -## AudioSourceType9+ - -Enumerates the audio source types for video recording. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -| Name | Value | Description | -| ------------------------- | ---- | ---------------------- | -| AUDIO_SOURCE_TYPE_DEFAULT | 0 | Default audio input source.| -| AUDIO_SOURCE_TYPE_MIC | 1 | Mic audio input source. | - -## VideoSourceType9+ - -Enumerates the video source types for video recording. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -| Name | Value | Description | -| ----------------------------- | ---- | ------------------------------- | -| VIDEO_SOURCE_TYPE_SURFACE_YUV | 0 | The input surface carries raw data.| -| VIDEO_SOURCE_TYPE_SURFACE_ES | 1 | The input surface carries ES data. | - -## VideoRecorderProfile9+ - -Describes the video recording profile. - -**System capability**: SystemCapability.Multimedia.Media.VideoRecorder - -| Name | Type | Mandatory| Description | -| ---------------- | -------------------------------------------- | ---- | ---------------- | -| audioBitrate | number | Yes | Audio encoding bit rate.| -| audioChannels | number | Yes | Number of audio channels.| -| audioCodec | [CodecMimeType](#codecmimetype8) | Yes | Audio encoding format. | -| audioSampleRate | number | Yes | Audio sampling rate. | -| fileFormat | [ContainerFormatType](#containerformattype8) | Yes | Container format of a file.| -| videoBitrate | number | Yes | Video encoding bit rate.| -| videoCodec | [CodecMimeType](#codecmimetype8) | Yes | Video encoding format. | -| videoFrameWidth | number | Yes | Width of the recorded video frame.| -| videoFrameHeight | number | Yes | Height of the recorded video frame.| -| videoFrameRate | number | Yes | Video frame rate. | ## ContainerFormatType8+ @@ -2437,7 +1739,7 @@ Enumerates the container format types (CFTs). | Name | Value | Description | | ----------- | ----- | --------------------- | -| CFT_MPEG_4 | "mp4" | Video container format MPEG-4 .| +| CFT_MPEG_4 | "mp4" | Video container format MPEG-4.| | CFT_MPEG_4A | "m4a" | Audio container format M4A.| ## Location