diff --git a/en/application-dev/reference/apis/js-apis-image.md b/en/application-dev/reference/apis/js-apis-image.md index c675e395d694b58c2d79bbc152344f98b2505e75..3b3c16a565cca24d717a7843b08ccbb615b18c7a 100644 --- a/en/application-dev/reference/apis/js-apis-image.md +++ b/en/application-dev/reference/apis/js-apis-image.md @@ -948,8 +948,18 @@ Creates an **ImageSource** instance based on the URI. **Example** ```js -let context = featureAbility.getContext(); -let path = context.getCacheDir() + "test.jpg"; +// Stage model +const context = getContext(this); +const path = context.getCacheDir() + "/test.jpg"; +const imageSourceApi = image.createImageSource(path); +``` + +```js +// FA model +import featureAbility from '@ohos.ability.featureAbility'; + +const context = featureAbility.getContext(); +const path = context.getCacheDir() + "/test.jpg"; const imageSourceApi = image.createImageSource(path); ``` @@ -1479,8 +1489,8 @@ Creates a **PixelMap** object based on the default parameters. This API uses an ```js imageSourceApi.createPixelMap((err, pixelmap) => { - console.info('Succeeded in creating pixelmap object.'); - }) + console.info('Succeeded in creating pixelmap object.'); +}) ``` ### createPixelMap7+ @@ -1515,6 +1525,177 @@ imageSourceApi.createPixelMap(decodingOptions, pixelmap => { }) ``` +### createPixelMapList10+ + +createPixelMapList(options?: DecodingOptions): Promise>; + +Creates an array of **PixelMap** objects based on image decoding parameters. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageSource + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------- | ---- | -------------------------- | +| options | [DecodingOptions](#decodingoptions7) | No | Image decoding parameters. | + +**Return value** + +| Type | Description | +| -------------------------------- | --------------------- | +| Promise> | Promise used to return an array of **PixeMap** objects.| + +**Example** + +```js +let decodeOpts = { + sampleSize: 1, + editable: true, + desiredSize: { width: 198, height: 202 }, + rotate: 0, + desiredPixelFormat: RGBA_8888, + index: 0, +}; +let pixelmaplist = await imageSourceApi.createPixelMapList(decodeOpts); +``` + +### createPixelMapList10+ + +createPixelMapList(callback: AsyncCallback>): void + +Creates an array of **PixelMap** objects based on the default parameters. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageSource + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------- | ---- | -------------------------- | +| callback | AsyncCallback> | Yes | Callback used to return an array of **PixeMap** objects.| + +**Example** + +```js +imageSourceApi.createPixelMap( pixelmaplist => { + console.info('Succeeded in creating pixelmaplist object.'); +}) +``` + +### createPixelMapList10+ + +createPixelMapList(options: DecodingOptions, callback: AsyncCallback>): void; + +Creates an array of **PixelMap** objects based on image decoding parameters. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageSource + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------------------------------- | +| options | [DecodingOptions](#decodingoptions7) | Yes| Image decoding parameters.| +| callback | AsyncCallback> | Yes | Callback used to return an array of **PixeMap** objects.| + +**Example** + +```js +let decodeOpts = { + sampleSize: 1, + editable: true, + desiredSize: { width: 198, height: 202 }, + rotate: 0, + desiredPixelFormat: RGBA_8888, + index: 0, +}; +imageSourceApi.createPixelMap(decodeOpts, pixelmaplist => { + console.log('Succeeded in creating pixelmaplist object.'); +}) +``` + +### getDelayTime10+ + +getDelayTime(callback: AsyncCallback>): void; + +Obtains an array of delay times. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageSource + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------------------------------- | +| callback | AsyncCallback> | Yes | Callback used to return an array of delay times.| + +**Example** + +```js +imageSourceApi.getDelayTime( delayTimes => { + console.log('Succeeded in getting delay time.'); +}); +``` + +### getDelayTime10+ + +getDelayTime(): Promise>; + +Obtains an array of delay times. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageSource + +**Return value** + +| Type | Description | +| -------------- | --------------------------- | +| Promise> | Promise used to return an array of delay times.| + +**Example** + +```js +let delayTimes = await imageSourceApi.getDelayTime(); +``` + +### getFrameCount10+ + +getFrameCount(callback: AsyncCallback): void; + +Obtains the number of frames. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageSource + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------------------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the number of frames.| + +**Example** + +```js +imageSourceApi.getFrameCount( frameCount => { + console.log('Succeeded in getting frame count.'); +}); +``` + +### getFrameCount10+ + +getFrameCount(): Promise\; + +Obtains the number of frames. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.Image.ImageSource + +**Return value** + +| Type | Description | +| -------------- | --------------------------- | +| Promise\ | Promise used to return the number of frames.| + +**Example** + +```js +let frameCount = await imageSourceApi.getFrameCount(); +``` + ### release release(callback: AsyncCallback\): void diff --git a/en/application-dev/reference/apis/js-apis-media.md b/en/application-dev/reference/apis/js-apis-media.md index 3d29422be8cb7f4c363d3272fa1d00dae4019bc9..70e5b8141e0072a84640e6f3b27f94e345e96264 100644 --- a/en/application-dev/reference/apis/js-apis-media.md +++ b/en/application-dev/reference/apis/js-apis-media.md @@ -357,20 +357,25 @@ For details about the AVPlayer demo, see [AVPlayer Development](../../media/avpl **System capability**: SystemCapability.Multimedia.Media.AVPlayer -| Name | Type | Readable| Writable| Description | -| --------------------------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | -| url9+ | string | Yes | Yes | URL of the media asset. It is a static attribute and can be set only when the AVPlayer is in the idle state.
The video formats MP4, MPEG-TS, WebM, and MKV are supported.
The audio formats M4A, AAC, MP3, OGG, and WAV are supported.
**Examples of supported URLs**:
1. FD: fd://xx
![](figures/en-us_image_url.png)
2. HTTP: http://xx
3. HTTPS: https://xx
4. HLS: http://xx or https://xx| -| fdSrc9+ | [AVFileDescriptor](#avfiledescriptor9) | Yes | Yes | FD of the media asset. It is a static attribute and can be set only when the AVPlayer is in the idle state.
This attribute is required when media assets of an application are continuously stored in a file.
**Example:**
Assume that a media file that stores continuous assets consists of the following:
Video 1 (address offset: 0, byte length: 100)
Video 2 (address offset: 101; byte length: 50)
Video 3 (address offset: 151, byte length: 150)
1. To play video 1: AVFileDescriptor {fd = resource handle; offset = 0; length = 100; }
2. To play video 2: AVFileDescriptor {fd = resource handle; offset = 101; length = 50; }
3. To play video 3: AVFileDescriptor {fd = resource handle; offset = 151; length = 150; }
To play an independent media file, use **src=fd://xx**.| -| surfaceId9+ | string | Yes | Yes | Video window ID. By default, there is no video window. It is a static attribute and can be set only when the AVPlayer is in the initialized state.
It is used to render the window for video playback and therefore is not required in audio-only playback scenarios.
**Example:**
[Create a surface ID through XComponent](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid).| -| loop9+ | boolean | Yes | Yes | Whether to loop playback. The value **true** means to loop playback, and **false** (default) means the opposite. It is a dynamic attribute
and can be set only when the AVPlayer is in the prepared, playing, paused, or completed state.| -| videoScaleType9+ | [VideoScaleType](#videoscaletype9) | Yes | Yes | Video scaling type. The default value is **VIDEO_SCALE_TYPE_FIT_CROP**. It is a dynamic attribute
and can be set only when the AVPlayer is in the prepared, playing, paused, or completed state.| -| audioInterruptMode9+ | [audio.InterruptMode](js-apis-audio.md#interruptmode9) | Yes | Yes | Audio interruption mode. The default value is **SHARE_MODE**. It is a dynamic attribute
and can be set only when the AVPlayer is in the prepared, playing, paused, or completed state.| +| Name | Type | Readable| Writable| Description | +| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | +| url9+ | string | Yes | Yes | URL of the media asset. It is a static attribute and can be set only when the AVPlayer is in the idle state.
The video formats MP4, MPEG-TS, WebM, and MKV are supported.
The audio formats M4A, AAC, MP3, OGG, and WAV are supported.
**Examples of supported URLs**:
1. FD: fd://xx
![](figures/en-us_image_url.png)
2. HTTP: http://xx
3. HTTPS: https://xx
4. HLS: http://xx or https://xx| +| fdSrc9+ | [AVFileDescriptor](#avfiledescriptor9) | Yes | Yes | FD of the media asset. It is a static attribute and can be set only when the AVPlayer is in the idle state.
This attribute is required when media assets of an application are continuously stored in a file.
**Example:**
Assume that a media file that stores continuous assets consists of the following:
Video 1 (address offset: 0, byte length: 100)
Video 2 (address offset: 101; byte length: 50)
Video 3 (address offset: 151, byte length: 150)
1. To play video 1: AVFileDescriptor {fd = resource handle; offset = 0; length = 100; }
2. To play video 2: AVFileDescriptor {fd = resource handle; offset = 101; length = 50; }
3. To play video 3: AVFileDescriptor {fd = resource handle; offset = 151; length = 150; }
To play an independent media file, use **src=fd://xx**.| +| dataSrc10+ | [AVDataSrcDescriptor](#avdatasrcdescriptor10) | Yes | Yes | Descriptor of a streaming media asset. It is a static attribute and can be set only when the AVPlayer is in the idle state.
Use scenario: An application starts playing a media file while the file is still being downloaded from the remote to the local host.
**Example:**
A user is obtaining an audio and video file from a remote server and wants to play the downloaded file content. To implement this scenario, do as follows:
1. Obtain the total file size, in bytes. If the total size cannot be obtained or the live mode is expected, set **fileSize** to **-1**.
2. Implement the **func** callback to fill in data. If **fileSize** is **-1**, the format of **func** is **func(buffer: ArrayBuffer, length: number)**; otherwise, the format is **func(buffer: ArrayBuffer, length: number, pos: number)**.
3. Set **AVDataSrcDescriptor {fileSize = size, callback = func}**.| +| surfaceId9+ | string | Yes | Yes | Video window ID. By default, there is no video window. It is a static attribute and can be set only when the AVPlayer is in the initialized state.
It is used to render the window for video playback and therefore is not required in audio-only playback scenarios.
**Example:**
[Create a surface ID through XComponent](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid).| +| loop9+ | boolean | Yes | Yes | Whether to loop playback. The value **true** means to loop playback, and **false** (default) means the opposite. It is a dynamic attribute
and can be set only when the AVPlayer is in the prepared, playing, paused, or completed state.| +| videoScaleType9+ | [VideoScaleType](#videoscaletype9) | Yes | Yes | Video scaling type. The default value is **VIDEO_SCALE_TYPE_FIT_CROP**. It is a dynamic attribute
and can be set only when the AVPlayer is in the prepared, playing, paused, or completed state.| +| audioInterruptMode9+ | [audio.InterruptMode](js-apis-audio.md#interruptmode9) | Yes | Yes | Audio interruption mode. The default value is **SHARE_MODE**. It is a dynamic attribute
and can be set only when the AVPlayer is in the prepared, playing, paused, or completed state.| | audioRendererInfo10+ | [audio.AudioRendererInfo](js-apis-audio.md#audiorendererinfo8) | Yes | Yes | Audio renderer information. The default value of **contentType** is **CONTENT_TYPE_MUSIC**, and the default value of **streamUsage** is **STREAM_USAGE_MEDIA**.
It can be set only when the AVPlayer is in the initialized state.| -| state9+ | [AVPlayerState](#avplayerstate9) | Yes | No | AVPlayer state. It can be used as a query parameter when the AVPlayer is in any state. | -| currentTime9+ | number | Yes | No | Current video playback position, in ms. It can be used as a query parameter when the AVPlayer is in the prepared, playing, paused, or completed state.
The value **-1** indicates an invalid value.| -| duration9+ | number | Yes | No | Video duration, in ms. It can be used as a query parameter when the AVPlayer is in the prepared, playing, paused, or completed state.
The value **-1** indicates an invalid value.
In live streaming scenarios, **-1** is returned by default.| -| width9+ | number | Yes | No | Video width, in pixels. It can be used as a query parameter when the AVPlayer is in the prepared, playing, paused, or completed state.
The value **0** indicates an invalid value.| -| height9+ | number | Yes | No | Video height, in pixels. It can be used as a query parameter when the AVPlayer is in the prepared, playing, paused, or completed state.
The value **0** indicates an invalid value.| +| state9+ | [AVPlayerState](#avplayerstate9) | Yes | No | AVPlayer state. It can be used as a query parameter when the AVPlayer is in any state. | +| currentTime9+ | number | Yes | No | Current video playback position, in ms. It can be used as a query parameter when the AVPlayer is in the prepared, playing, paused, or completed state.
The value **-1** indicates an invalid value.| +| duration9+ | number | Yes | No | Video duration, in ms. It can be used as a query parameter when the AVPlayer is in the prepared, playing, paused, or completed state.
The value **-1** indicates an invalid value.
In live streaming scenarios, **-1** is returned by default.| +| width9+ | number | Yes | No | Video width, in pixels. It can be used as a query parameter when the AVPlayer is in the prepared, playing, paused, or completed state.
The value **0** indicates an invalid value.| +| height9+ | number | Yes | No | Video height, in pixels. It can be used as a query parameter when the AVPlayer is in the prepared, playing, paused, or completed state.
The value **0** indicates an invalid value.| + +**NOTE** + +After the resource handle (FD) is transferred to the AVPlayer, do not use the resource handle to perform read and write operations, including but not limited to transferring it to multiple AVPlayers. Competition occurs when multiple AVPlayers use the same resource handle to read and write files at the same time, resulting in playback errors. ### on('stateChange')9+ @@ -1060,7 +1065,7 @@ Sets the playback speed. This API can be called only when the AVPlayer is in the **Example** ```js -avPlayer.setSpeed(media.AVPlayerSpeed.SPEED_FORWARD_2_00_X) +avPlayer.setSpeed(media.PlaybackSpeed.SPEED_FORWARD_2_00_X) ``` ### on('speedDone')9+ @@ -1586,7 +1591,7 @@ Enumerates the states of the [AVPlayer](#avplayer9). Your application can proact | Name | Type | Description | | :-----------------------------: | :----: | :----------------------------------------------------------- | -| idle | string | The AVPlayer enters this state after [createAVPlayer()](#mediacreateavplayer9) or **reset()** is called.
In case **createAVPlayer()** is used, all attributes are set to their default values.
In case **reset()** is invoked, the **url9+** or **fdSrc9+** attribute is reset, and other attributes set by the application are retained.| +| idle | string | The AVPlayer enters this state after [createAVPlayer()](#mediacreateavplayer9) or **reset()** is called.
In case **createAVPlayer()** is used, all attributes are set to their default values.
In case **reset()** is called, the **url9+**, **fdSrc9+**, or **dataSrc10+** attribute and the **loop** attribute are reset, and other attributes are retained.| | initialized | string | The AVPlayer enters this state after **url9+** or **fdSrc9+** attribute is set in the idle state. In this case, you can configure static attributes such as the window and audio.| | prepared | string | The AVPlayer enters this state when **prepare()** is called in the initialized state. In this case, the playback engine has prepared the resources.| | playing | string | The AVPlayer enters this state when **play()** is called in the prepared, paused, or completed state.| @@ -1608,6 +1613,18 @@ Describes an audio and video file asset. It is used to specify a particular asse | offset | number | Yes | Resource offset, which needs to be entered based on the preset asset information. An invalid value causes a failure to parse audio and video assets.| | length | number | Yes | Resource length, which needs to be entered based on the preset asset information. An invalid value causes a failure to parse audio and video assets.| +## AVDataSrcDescriptor10+ + +Defines the descriptor of an audio and video file, which is used in DataSource playback mode.
Use scenario: An application can create a playback instance and start playback before it finishes downloading the audio and video resources. + +**System capability**: SystemCapability.Multimedia.Media.AVPlayer + +| Name | Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| fileSize | number | Yes | Size of the file to play, in bytes. The value **-1** indicates that the size is unknown. If **fileSize** is set to **-1**, the playback mode is similar to the live mode. In this mode, the **seek** and **setSpeed** operations cannot be performed, and the **loop** attribute cannot be set, indicating that loop playback is unavailable.| +| callback | function | Yes | Callback used to fill in data.
- **buffer**: memory to be filled. The value is of the ArrayBuffer type. This parameter is mandatory.
- **length**: maximum length of the memory to be filled. The value is of the number type. This parameter is mandatory.
- **pos**: position of the data to be filled in the file. The value is of the number type. This parameter is optional. When **fileSize** is set to **-1**, this parameter cannot be used.| + + ## SeekMode8+ Enumerates the video playback seek modes, which can be passed in the **seek** API. @@ -2486,7 +2503,7 @@ Describes the audio and video recording parameters. | audioSourceType | [AudioSourceType](#audiosourcetype9) | No | Type of the audio source to record. This parameter is mandatory for audio recording. | | videoSourceType | [VideoSourceType](#videosourcetype9) | No | Type of the video source to record. This parameter is mandatory for video recording. | | profile | [AVRecorderProfile](#avrecorderprofile9) | Yes | Recording profile. This parameter is mandatory. | -| url | string | Yes | Recording output URL: fd://xx (fd number).
![img](figures/en-us_image_url.png)
This parameter is mandatory. | +| url | string | Yes | Recording output URL: fd://xx (fd number).
![img](figures/en-us_image_url.png)
This parameter is mandatory.| | rotation | number | No | Rotation angle of the recorded video. The value can only be 0, 90, 180, or 270. | | location | [Location](#location) | No | Geographical location of the recorded video. | @@ -3759,7 +3776,7 @@ Subscribes to the audio playback events. | Name | Type | Mandatory| Description | | -------- | ---------- | ---- | ------------------------------------------------------------ | -| 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. | +| 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** @@ -4874,7 +4891,7 @@ Subscribes to the audio recording events. | Name | Type | Mandatory| Description | | -------- | -------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type. The following events are supported:
- 'prepare': triggered when the [prepare](#audiorecorder_prepare) API is called and the audio recording parameters are set.
- 'start': triggered when the [start](#audiorecorder_start) API is called and audio recording starts.
- 'pause': triggered when the [pause](#audiorecorder_pause) API is called and audio recording is paused.
- 'resume': triggered when the [resume](#audiorecorder_resume) API is called and audio recording is resumed.
- 'stop': triggered when the [stop](#audiorecorder_stop) API is called and audio recording stops.
- 'release': triggered when the [release](#audiorecorder_release) API is called and the recording resources are released.
- 'reset': 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': triggered when the [prepare](#audiorecorder_prepare) API is called and the audio recording parameters are set.
- 'start': triggered when the [start](#audiorecorder_start) API is called and audio recording starts.
- 'pause': triggered when the [pause](#audiorecorder_pause) API is called and audio recording is paused.
- 'resume': triggered when the [resume](#audiorecorder_resume) API is called and audio recording is resumed.
- 'stop': triggered when the [stop](#audiorecorder_stop) API is called and audio recording stops.
- 'release': triggered when the [release](#audiorecorder_release) API is called and the recording resources are released.
- 'reset': 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**