diff --git a/en/application-dev/reference/apis/js-apis-media.md b/en/application-dev/reference/apis/js-apis-media.md index 52178a666aa9ef29b878cd2b1978c3ab3ca3d163..7616a34520de90becc362cb12b6ba27ee8be0b49 100644 --- a/en/application-dev/reference/apis/js-apis-media.md +++ b/en/application-dev/reference/apis/js-apis-media.md @@ -310,18 +310,19 @@ Enumerates the media description keys. **System capability**: SystemCapability.Multimedia.Media.Core -| 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. | +| 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. | +| MD_KEY_LANGUAGE10+ | "language" | Language, which is a string. | ## BufferingInfoType8+ @@ -359,17 +360,17 @@ For details about the audio and video playback demo, see [Audio Playback](../../ | 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.
The video formats MP4, MPEG-TS, WebM, and MKV are supported.
The audio formats M4A, AAC, MP3, OGG, and WAV are supported.
**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.
The video formats MP4, MPEG-TS, WebM, and MKV are supported.
The audio formats M4A, AAC, MP3, OGG, and WAV are supported.
**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, 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)**, and the AVPlayer obtains data in sequence; otherwise, the format is **func(buffer: ArrayBuffer, length: number, pos: number)**, and the AVPlayer seeks and obtains data in the required positions.
3. Set **AVDataSrcDescriptor {fileSize = size, callback = func}**.
**Notes:**
If the media file to play is in MP4/M4A format, ensure that the **moov** field (specifying the media information) is before the **mdat** field (specifying the media data) or the fields before the **moov** field is less than 10 MB. Otherwise, the parsing fails and the media file cannot be played.| +| 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, WAV, and FLAC are supported.
**Example 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.
The video formats MP4, MPEG-TS, WebM, and MKV are supported.
The audio formats M4A, AAC, MP3, OGG, WAV, and FLAC are supported.
**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.
The video formats MP4, MPEG-TS, WebM, and MKV are supported.
The audio formats M4A, AAC, MP3, OGG, WAV, and FLAC are supported.
**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, 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)**, and the AVPlayer obtains data in sequence; otherwise, the format is **func(buffer: ArrayBuffer, length: number, pos: number)**, and the AVPlayer seeks and obtains data in the required positions.
3. Set **AVDataSrcDescriptor {fileSize = size, callback = func}**.
**Notes:**
If the media file to play is in MP4/M4A format, ensure that the **moov** field (specifying the media information) is before the **mdat** field (specifying the media data) or the fields before the **moov** field is less than 10 MB. Otherwise, the parsing fails and the media file cannot be played.| | 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.
This setting is not supported in the live mode.| +| 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.
This setting is not supported in live mode.| | 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.
In the live mode, **-1** is returned by default.| -| 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.| +| 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.
In live mode, **-1** is returned by default.| +| 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 mode, **-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.| @@ -907,7 +908,7 @@ avPlayer.release().then(() => { }) ``` -### getTrackDescription9+ +### getTrackDescription9+ getTrackDescription(callback: AsyncCallback\>): void @@ -999,12 +1000,130 @@ for (let i = 0; i < arrayDescription.length; i++) { } ``` +### selectTrack10+ + +selectTrack(index: number): void + +Selects an audio track. This API can be called only when the AVPlayer is in the prepared state. You can listen for the [trackChange event](#trackchange_on) to determine whether the API calling takes effect. + +**System capability**: SystemCapability.Multimedia.Media.AVPlayer + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| index | number | Yes | Track ID, which can be obtained by calling [getTrackDescription](#avplayer_gettrackdescription).| + +**Example** + +```js +let index = 2 +avPlayer.setBitrate(index) +``` + +### deselectTrack10+ + +deselectTrack(index: number): void + +Deselects an audio track. The default audio track will be used after the audio track is deselected. This API can be called only when the AVPlayer is in the prepared state. You can listen for the [trackChange event](#trackchange_on) to determine whether the API calling takes effect. + +**System capability**: SystemCapability.Multimedia.Media.AVPlayer + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| index | number | Yes | Track ID. You can obtain the ID of the current track by calling [getCurrentTrack](#avplayer_getcurrenttrack).| + +**Example** + +```js +let index = 2 +avPlayer.deselectTrack(index) +``` + +### getCurrentTrack10+ + +getCurrentTrack(trackType: MediaType, callback: AsyncCallback\): void + +Obtains the ID of the current track. This API uses an asynchronous callback to return the result. It can be called only when the AVPlayer is in the prepared, playing, paused, or completed state. + +**System capability**: SystemCapability.Multimedia.Media.AVPlayer + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ----------------------- | ---- | ------------------------------------------------------------ | +| trackType | [MediaType](#mediatype) | Yes | Enumerates the media types. | +| callback | AsyncCallback\ | Yes | Callback used to return the current track. If **-1** is returned, no track for the specified media type exists.| + +**Error codes** + +For details about the error codes, see [Media Error Codes](../errorcodes/errorcode-media.md). + +| ID| Error Message | +| -------- | ------------------------------------------ | +| 5400102 | Operation not allowed. Return by callback. | + +**Example** + +```js +let mediaType = media.MediaType.MEDIA_TYPE_AUD; +let trackIndex = null; + +avPlayer.getCurrentTrack(mediaType (err, index) => { + if (err == null) { + console.info('getCurrentTrack success'); + trackIndex = index; + } else { + console.error('getCurrentTrack failed and error is ' + err.message); + } +}); +``` + +### getCurrentTrack10+ + +getCurrentTrack(trackType: MediaType): Promise\ + +Obtains the ID of the current track. This API uses a promise to return the result. It can be called only when the AVPlayer is in the prepared, playing, paused, or completed state. + +**System capability**: SystemCapability.Multimedia.Media.AVPlayer + +**Return value** + +| Type | Description | +| ---------------- | ------------------------------------------------------------ | +| trackType | [MediaType](#mediatype) | +| Promise\| Promise used to return the current track. If **-1** is returned, no track for the specified media type exists.| + +**Error codes** + +For details about the error codes, see [Media Error Codes](../errorcodes/errorcode-media.md). + +| ID| Error Message | +| -------- | ----------------------------------------- | +| 5400102 | Operation not allowed. Return by promise. | + +**Example** + +```js +let mediaType = media.MediaType.MEDIA_TYPE_AUD; +let trackIndex = null; + +avPlayer.getCurrentTrack(mediaType).then((index) => { + console.info('getCurrentTrack success'); + trackIndex = index; +}).catch((err) => { + console.error('getCurrentTrack failed and catch error is ' + err.message); +}); +``` + ### seek9+ seek(timeMs: number, mode?:SeekMode): void Seeks to the specified playback position. This API can be called only when the AVPlayer is in the prepared, playing, paused, or completed state. You can check whether the seek operation takes effect by subscribing to the [seekDone](#seekDone_on) event. -This API is not supported in the live mode. +This API is not supported in live mode. **System capability**: SystemCapability.Multimedia.Media.AVPlayer @@ -1070,7 +1189,7 @@ avPlayer.off('seekDone') setSpeed(speed: PlaybackSpeed): void Sets the playback speed. This API can be called only when the AVPlayer is in the prepared, playing, paused, or completed state. You can check whether the setting takes effect by subscribing to the [speedDone](#speedDone_on) event. -This API is not supported in the live mode. +This API is not supported in live mode. **System capability**: SystemCapability.Multimedia.Media.AVPlayer @@ -1348,7 +1467,7 @@ avPlayer.off('endOfStream') on(type: 'timeUpdate', callback: Callback\): void Subscribes to playback position changes. It is used to refresh the current position of the progress bar. By default, this event is reported every 1 second. However, it is reported immediately upon a successful seek operation. -The **'timeUpdate'** event is not supported in the live mode. +The **'timeUpdate'** event is not supported in live mode. **System capability**: SystemCapability.Multimedia.Media.AVPlayer @@ -1392,7 +1511,7 @@ avPlayer.off('timeUpdate') on(type: 'durationUpdate', callback: Callback\): void Subscribes to media asset duration changes. It is used to refresh the length of the progress bar. By default, this event is reported once when the AVPlayer switches to the prepared state. However, it can be repeatedly reported for special streams that trigger duration changes. -The **'durationUpdate'** event is not supported in the live mode. +The **'durationUpdate'** event is not supported in live mode. **System capability**: SystemCapability.Multimedia.Media.AVPlayer @@ -1605,6 +1724,49 @@ Unsubscribes from the audio interruption event. avPlayer.off('audioInterrupt') ``` +### on('trackChange')10+ + +on(type: 'trackChange', callback: (index: number, isSelect: boolean) => void): void; + +Subscribes to track changes, which are triggered by calling **selectTrack** or **deselectTrack**. + +**System capability**: SystemCapability.Multimedia.Media.AVPlayer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------- | ---- | ----------------------------------------------------- | +| type | string | Yes | Event type, which is **'trackChange'** in this case.| +| callback | function | Yes | Callback invoked when the event is triggered. | + +**Example** + +```js +avPlayer.on('trackChange', (index: number, isSelect: boolean) => { + console.info('trackChange success, and index is:' + index + ', isSelect is :' + isSelect) +}) +``` + +### off('trackChange')10+ + +off(type: 'trackChange'): void + +Unsubscribes from track changes + +**System capability**: SystemCapability.Multimedia.Media.AVPlayer + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | --------------------------------------------------------- | +| type | string | Yes | Event type, which is **'trackChange'** in this case.| + +**Example** + +```js +avPlayer.off('trackChange') +``` + ## AVPlayerState9+ Enumerates the states of the [AVPlayer](#avplayer9). Your application can proactively obtain the AVPlayer state through the **state** attribute or obtain the reported AVPlayer state by subscribing to the [stateChange](#stateChange_on) event. For details about the rules for state transition, see [Audio Playback](../../media/using-avplayer-for-playback.md). @@ -3497,7 +3659,7 @@ Only one **AudioRecorder** instance can be created per device. | Type | Description | | ------------------------------- | ------------------------------------------------------------ | -| [AudioRecorder](#audiorecorderdeprecated) | If the operation is successful, the **AudioRecorder** instance is returned; otherwise, **null** is returned. The instance can be used to record audio.| +| [AudioRecorder](#audiorecorderdeprecated) | If the operation is successful, an **AudioRecorder** instance is returned; otherwise, **null** is returned. The instance can be used to record audio.| **Example** @@ -3542,7 +3704,7 @@ Provides APIs to manage and play audio. Before calling any API in **AudioPlayer* | Name | Type | Readable| Writable| Description | | ------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | -| src | string | Yes | Yes | Audio file URI. The mainstream 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
**Required permissions**: ohos.permission.READ_MEDIA or ohos.permission.INTERNET| +| src | string | Yes | Yes | Audio file URI. The mainstream audio formats (M4A, AAC, MP3, OGG, and WAV) are supported.
**Example 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
**Required permissions**: ohos.permission.READ_MEDIA or ohos.permission.INTERNET| | fdSrc9+ | [AVFileDescriptor](#avfiledescriptor9) | Yes | Yes | Description of the audio file. This attribute is required when audio assets of an application are continuously stored in a file.
**Example:**
Assume that a music file that stores continuous music assets consists of the following:
Music 1 (address offset: 0, byte length: 100)
Music 2 (address offset: 101; byte length: 50)
Music 3 (address offset: 151, byte length: 150)
1. To play music 1: AVFileDescriptor {fd = resource handle; offset = 0; length = 100; }
2. To play music 2: AVFileDescriptor {fd = resource handle; offset = 101; length = 50; }
3. To play music 3: AVFileDescriptor {fd = resource handle; offset = 151; length = 150; }
To play an independent music file, use **src=fd://xx**.
| | loop | boolean | Yes | Yes | Whether to loop audio playback. The value **true** means to loop audio playback, and **false** means the opposite. | | audioInterruptMode9+ | [audio.InterruptMode](js-apis-audio.md#interruptmode9) | Yes | Yes | Audio interruption mode. |