1# Types 2<!--Kit: Media Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @wang-haizhou6--> 5<!--Designer: @HmQQQ--> 6<!--Tester: @xchaosioda--> 7<!--Adviser: @zengyawen--> 8 9> **NOTE** 10> 11> 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. 12 13## SoundPool<sup>10+</sup> 14 15type SoundPool = _SoundPool 16 17SoundPool, which provides APIs for loading, unloading, playing, and stopping playing system sounds, setting the volume, and setting the number of loops. 18 19**System capability**: SystemCapability.Multimedia.Media.SoundPool 20 21| Type | Description | 22| -------- | ------------------------------ | 23| [_SoundPool](js-apis-inner-multimedia-soundPool.md#soundpool) | Provides APIs for loading, unloading, playing, and stopping playing system sounds, setting the volume, and setting the number of loops.| 24 25## PlayParameters<sup>10+</sup> 26 27type PlayParameters = _PlayParameters 28 29Describes the playback parameters of the sound pool. 30 31**System capability**: SystemCapability.Multimedia.Media.SoundPool 32 33| Type | Description | 34| -------- | ------------------------------ | 35| [_PlayParameters](js-apis-inner-multimedia-soundPool.md#playparameters) | Playback parameters of the sound pool.| 36 37## AVPlayerState<sup>9+</sup> 38 39type AVPlayerState = 'idle' | 'initialized' | 'prepared' | 'playing' | 'paused' | 'completed' | 'stopped' | 'released' | 'error' 40 41Describes the state of the [AVPlayer](arkts-apis-media-AVPlayer.md). Your application can proactively obtain the AVPlayer state through the **state** property or obtain the reported AVPlayer state by subscribing to the [stateChange](arkts-apis-media-AVPlayer.md#onstatechange9) event. For details about the rules for state transition, see [Audio Playback](../../media/media/using-avplayer-for-playback.md). 42 43**Atomic service API**: This API can be used in atomic services since API version 11. 44 45**System capability**: SystemCapability.Multimedia.Media.AVPlayer 46 47| Type | Description | 48| :-----------------------------: | :----------------------------------------------------------- | 49| 'idle' | The AVPlayer enters this state after [createAVPlayer()](arkts-apis-media-f.md#mediacreateavplayer9) or [reset()](arkts-apis-media-AVPlayer.md#reset9) is called.<br>In case [createAVPlayer()](arkts-apis-media-f.md#mediacreateavplayer9) is used, all properties are set to their default values.<br>In case [reset()](arkts-apis-media-AVPlayer.md#reset9) is called, the **url<sup>9+</sup>**, **fdSrc<sup>9+</sup>**, or **dataSrc<sup>10+</sup>** property and the **loop** property are reset, and other properties are retained.| 50| 'initialized' | The AVPlayer enters this state after **url<sup>9+</sup>** or **fdSrc<sup>9+</sup>** property is set in the idle state. In this case, you can configure static properties such as the window and audio.| 51| 'prepared' | The AVPlayer enters this state when [prepare()](arkts-apis-media-AVPlayer.md#prepare9) is called in the initialized state. In this case, the playback engine has prepared the resources.| 52| 'playing' | The AVPlayer enters this state when [play()](arkts-apis-media-AVPlayer.md#play9) is called in the prepared, paused, or completed state.| 53| 'paused' | The AVPlayer enters this state when **pause()** is called in the playing state.| 54| 'completed' | The AVPlayer enters this state when a media asset finishes playing and loop playback is not set (no **loop = true**). In this case, if [play()](arkts-apis-media-AVPlayer.md#play9) is called, the AVPlayer enters the playing state and replays the media asset; if [stop()](arkts-apis-media-AVPlayer.md#stop9) is called, the AVPlayer enters the stopped state.| 55| 'stopped' | The AVPlayer enters this state when [stop()](arkts-apis-media-AVPlayer.md#stop9) is called in the prepared, playing, paused, or completed state. In this case, the playback engine retains the properties but releases the memory resources. You can call [prepare()](arkts-apis-media-AVPlayer.md#prepare9) to prepare the resources again, call [reset()](arkts-apis-media-AVPlayer.md#reset9) to reset the properties, or call [release()](arkts-apis-media-AVPlayer.md#release9) to destroy the playback engine.| 56| 'released' | The AVPlayer enters this state when [release()](arkts-apis-media-AVPlayer.md#release9) is called. The playback engine associated with the AVPlayer instance is destroyed, and the playback process ends. This is the final state.| 57| 'error' | The AVPlayer enters this state when an irreversible error occurs in the playback engine. You can call [reset()](arkts-apis-media-AVPlayer.md#reset9) to reset the properties or call [release()](arkts-apis-media-AVPlayer.md#release9) to destroy the playback engine. For details about the error codes, see [Media Error Codes](errorcode-media.md).<br>**NOTE** Relationship between the error state and the [on('error')](arkts-apis-media-AVPlayer.md#onerror9) event<br>1. When the AVPlayer enters the error state, the **on('error')** event is triggered. You can obtain the detailed error information through this event.<br>2. When the AVPlayer enters the error state, the playback service stops. This requires the client to design a fault tolerance mechanism to call [reset()](arkts-apis-media-AVPlayer.md#reset9) or [release()](arkts-apis-media-AVPlayer.md#release9).<br>3. The client receives **on('error')** event but the AVPlayer does not enter the error state. This situation occurs due to either of the following reasons:<br>Cause 1: The client calls an API in an incorrect state or passes in an incorrect parameter, and the AVPlayer intercepts the call. If this is the case, the client must correct its code logic.<br>Cause 2: A stream error is detected during playback. As a result, the container and decoding are abnormal for a short period of time, but continuous playback and playback control operations are not affected. If this is the case, the client does not need to design a fault tolerance mechanism.| 58 59## OnTrackChangeHandler<sup>12+</sup> 60 61type OnTrackChangeHandler = (index: number, isSelected: boolean) => void 62 63Describes the callback invoked for the track change event. 64 65**Atomic service API**: This API can be used in atomic services since API version 12. 66 67**System capability**: SystemCapability.Multimedia.Media.AVPlayer 68 69**Parameters** 70 71| Name | Type | Mandatory| Description | 72| ------ | ------ | ------ | ---------------------------------------------------------- | 73| index | number | Yes| Index of the track that has changed. | 74| isSelected | boolean | Yes| Whether the track at the current index is selected. **true** if selected, **false** otherwise.| 75 76## OnAVPlayerStateChangeHandle<sup>12+</sup> 77 78type OnAVPlayerStateChangeHandle = (state: AVPlayerState, reason: StateChangeReason) => void 79 80Describes the callback invoked for the AVPlayer state change event. 81 82**Atomic service API**: This API can be used in atomic services since API version 12. 83 84**System capability**: SystemCapability.Multimedia.Media.AVPlayer 85 86**Parameters** 87 88| Name | Type | Mandatory| Description | 89| ------ | ------ | ------ | ---------------------------------------------------------- | 90| state | [AVPlayerState](#avplayerstate9) | Yes| State of the AVPlayer. | 91| reason | [StateChangeReason](arkts-apis-media-e.md#statechangereason9) | Yes| Reason for the state change.| 92 93## OnBufferingUpdateHandler<sup>12+</sup> 94 95type OnBufferingUpdateHandler = (infoType: BufferingInfoType, value: number) => void 96 97Describes the callback invoked for the buffering update event. 98 99**Atomic service API**: This API can be used in atomic services since API version 12. 100 101**System capability**: SystemCapability.Multimedia.Media.AVPlayer 102 103**Parameters** 104 105| Name | Type | Mandatory| Description | 106| ------ | ------ | ------ | ------------------------------------------------------------ | 107| infoType | [BufferingInfoType](arkts-apis-media-e.md#bufferinginfotype8) | Yes| Buffering information type. | 108| value | number | Yes| Value of the buffering information type. | 109 110## OnVideoSizeChangeHandler<sup>12+</sup> 111 112type OnVideoSizeChangeHandler = (width: number, height: number) => void 113 114Describes the callback invoked for the video size change event. 115 116**Atomic service API**: This API can be used in atomic services since API version 12. 117 118**System capability**: SystemCapability.Multimedia.Media.AVPlayer 119 120**Parameters** 121 122| Name | Type | Mandatory| Description | 123| ------ | ------ | ------ | ------------------------------------------------------------ | 124| width | number | Yes| Video width, in px.| 125| height | number | Yes| Video height, in px.| 126 127## OnSuperResolutionChanged <sup>18+</sup> 128 129type OnSuperResolutionChanged = (enabled: boolean) => void 130 131Describes the callback used to listen for video super resolution status changes. If super resolution is enabled by using [PlaybackStrategy](arkts-apis-media-i.md#playbackstrategy12), this callback is invoked to report the super resolution status changes. It is also invoked to report the initial status when the video starts. However, this callback is not invoked when super resolution is not enabled. 132 133Super resolution is automatically disabled in either of the following cases: 134* The current super resolution algorithm only works with videos that have a frame rate of 30 fps or lower. If the video frame rate exceeds 30 fps, or if the input frame rate exceeds the processing capability of the super resolution algorithm in scenarios such as fast playback, super resolution is automatically disabled. 135* The current super resolution algorithm supports input resolutions from 320 x 320 to 1920 x 1080, in px. If the input video resolution exceeds the range during playback, super resolution is automatically disabled. 136 137**Atomic service API**: This API can be used in atomic services since API version 18. 138 139**System capability**: SystemCapability.Multimedia.Media.AVPlayer 140 141**Parameters** 142 143| Name | Type | Mandatory| Description | 144| ------ | ------ | ------ | ------------------------------------------------------------ | 145| enabled | boolean | Yes| Whether super resolution is enabled. **true** if enabled, **false** otherwise. | 146 147## OnSeiMessageHandle<sup>18+</sup> 148 149type OnSeiMessageHandle = (messages: Array\<SeiMessage>, playbackPosition?: number) => void 150 151Describes the handle used to obtain SEI messages. This is used when in subscriptions to SEI message events, and the callback returns detailed SEI information. 152 153**Atomic service API**: This API can be used in atomic services since API version 18. 154 155**System capability**: SystemCapability.Multimedia.Media.AVPlayer 156 157**Parameters** 158 159| Name | Type | Mandatory| Description | 160| ------ | ------ | ---- | ------------------------------------------------------------ | 161| messages | Array\<[SeiMessage](arkts-apis-media-i.md#seimessage18)> | Yes | Array of SEI messages.| 162| playbackPosition | number | No | Current playback position, in milliseconds.| 163 164## OnPlaybackRateDone<sup>20+</sup> 165 166type OnPlaybackRateDone = (rate: number) => void 167 168Describes the callback invoked for the event indicating that the playback rate setting is complete. 169 170**Atomic service API**: This API can be used in atomic services since API version 20. 171 172**System capability**: SystemCapability.Multimedia.Media.AVPlayer 173 174**Parameters** 175 176| Name | Type | Mandatory| Description | 177| ------ | ------ | ------ | ------------------------------------------------------------ | 178| rate | number | Yes| Playback rate.| 179 180## AVRecorderState<sup>9+</sup> 181 182type AVRecorderState = 'idle' | 'prepared' | 'started' | 'paused' | 'stopped' | 'released' | 'error' 183 184Enumerates the AVRecorder states. You can obtain the state through the **state** property. 185 186**Atomic service API**: This API can be used in atomic services since API version 12. 187 188**System capability**: SystemCapability.Multimedia.Media.AVRecorder 189 190| Type | Description | 191| -------- | ------------------------------------------------------------ | 192| 'idle' | The AVRecorder enters this state after it is just created or the [AVRecorder.reset()](arkts-apis-media-AVRecorder.md#reset9) API is called when the AVRecorder is in any state except released. In this state, you can call [AVRecorder.prepare()](arkts-apis-media-AVRecorder.md#prepare9) to set recording parameters. The AVRecorder enters this state after it is just created or the [AVRecorder.reset()](arkts-apis-media-AVRecorder.md#reset9) API is called when the AVRecorder is in any state except released.| 193| 'prepared' | The AVRecorder enters this state when the parameters are set. In this state, you can call [AVRecorder.start()](arkts-apis-media-AVRecorder.md#start9) to start recording.| 194| 'started' | The AVRecorder enters this state when the recording starts. In this state, you can call [AVRecorder.pause()](arkts-apis-media-AVRecorder.md#pause9) to pause recording or call [AVRecorder.stop()](arkts-apis-media-AVRecorder.md#stop9) to stop recording.| 195| 'paused' | The AVRecorder enters this state when the recording is paused. In this state, you can call [AVRecorder.resume()](arkts-apis-media-AVRecorder.md#resume9) to continue recording or call [AVRecorder.stop()](arkts-apis-media-AVRecorder.md#stop9) to stop recording.| 196| 'stopped' | The AVRecorder enters this state when the recording stops. In this state, you can call [AVRecorder.prepare()](arkts-apis-media-AVRecorder.md#prepare9) to set recording parameters so that the AVRecorder enters the prepared state again.| 197| 'released' | The AVRecorder enters this state when the recording resources are released. In this state, no operation can be performed. In any other state, you can call [AVRecorder.release()](arkts-apis-media-AVRecorder.md#release9) to enter the released state.| 198| 'error' | The AVRecorder enters this state when an irreversible error occurs in the AVRecorder instance. In this state, the [AVRecorder.on('error') event](arkts-apis-media-AVRecorder.md#onerror9) is reported, with the detailed error cause. In the error state, you must call [AVRecorder.reset()](arkts-apis-media-AVRecorder.md#reset9) to reset the AVRecorder instance or call [AVRecorder.release()](arkts-apis-media-AVRecorder.md#release9) to release the resources.| 199 200## OnAVRecorderStateChangeHandler<sup>12+</sup> 201 202type OnAVRecorderStateChangeHandler = (state: AVRecorderState, reason: StateChangeReason) => void 203 204Describes the callback invoked for the AVRecorder state change event. 205 206**Atomic service API**: This API can be used in atomic services since API version 12. 207 208**System capability**: SystemCapability.Multimedia.Media.AVRecorder 209 210**Parameters** 211 212| Name | Type | Mandatory| Description | 213| ------ | ------ | ------ | ------------------------------------------------------------ | 214| state | [AVRecorderState](#avrecorderstate9) | Yes| AVRecorder state. | 215| reason | [StateChangeReason](arkts-apis-media-e.md#statechangereason9) | Yes| Reason for the state change.| 216 217## SourceOpenCallback<sup>18+</sup> 218 219type SourceOpenCallback = (request: MediaSourceLoadingRequest) => number 220 221This callback function is implemented by applications to handle resource open requests and return a unique handle for the opened resource. 222 223> **NOTE** 224> 225> The client must return the handle immediately after processing the request. 226 227**Atomic service API**: This API can be used in atomic services since API version 18. 228 229**System capability**: SystemCapability.Multimedia.Media.Core 230 231**Parameters** 232 233| Name | Type | Mandatory| Description | 234| -------- | -------- | ---- | -------------------- | 235| request | [MediaSourceLoadingRequest](arkts-apis-media-MediaSourceLoadingRequest.md) | Yes | Parameters for the resource open request, including detailed information about the requested resource and the data push method.| 236 237**Return value** 238 239| Type | Description | 240| -------- | -------------------- | 241| number | Handle for the current resource open request. A value greater than 0 means the request is successful, whereas a value less than or equal to 0 means it fails.<br> - The handle for the request object is unique.| 242 243**Example** 244 245```ts 246import { HashMap } from '@kit.ArkTS'; 247import { media } from '@kit.MediaKit'; 248 249let uuid: number = 1; 250let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 251 252let sourceOpenCallback: media.SourceOpenCallback = (request: media.MediaSourceLoadingRequest) => { 253 console.log(`Opening resource: ${request.url}`); 254 // Open the resource and return a unique handle, ensuring the mapping between the UUID and request. 255 uuid += 1; 256 requests.set(uuid, request); 257 return uuid; 258}; 259``` 260 261## SourceReadCallback<sup>18+</sup> 262 263type SourceReadCallback = (uuid: number, requestedOffset: number, requestedLength: number) => void 264 265This callback function is implemented by applications to handle resource read requests. When data is available, applications should push it to the player using the [respondData](arkts-apis-media-MediaSourceLoadingRequest.md#responddata18) API of the corresponding MediaSourceLoadingRequest object. 266 267> **NOTE** 268> 269> The client must return the handle immediately after processing the request. 270 271**Atomic service API**: This API can be used in atomic services since API version 18. 272 273**System capability**: SystemCapability.Multimedia.Media.Core 274 275**Parameters** 276 277| Name | Type | Mandatory| Description | 278| -------- | -------- | ---- | -------------------- | 279| uuid | number | Yes | ID for the resource handle.| 280| requestedOffset | number | Yes | Offset of the current media data relative to the start of the resource.| 281| requestedLength | number | Yes | Length of the current request. The value **-1** indicates reaching the end of the resource. After pushing the data, call [finishLoading](arkts-apis-media-MediaSourceLoadingRequest.md#finishloading18) to notify the player that the push is complete.| 282 283**Example** 284 285```ts 286let sourceReadCallback: media.SourceReadCallback = (uuid: number, requestedOffset: number, requestedLength: number) => { 287 console.log(`Reading resource with handle ${uuid}, offset: ${requestedOffset}, length: ${requestedLength}`); 288 // Check whether the UUID is valid and store the read request. Avoid blocking the request while pushing data and header information. 289}; 290``` 291 292## SourceCloseCallback<sup>18+</sup> 293 294type SourceCloseCallback = (uuid: number) => void 295 296This callback function is implemented by applications to release related resources. 297 298> **NOTE** 299> 300> The client must return the handle immediately after processing the request. 301 302**Atomic service API**: This API can be used in atomic services since API version 18. 303 304**System capability**: SystemCapability.Multimedia.Media.Core 305 306**Parameters** 307 308| Name | Type | Mandatory| Description | 309| -------- | -------- | ---- | -------------------- | 310| uuid | number | Yes | ID for the resource handle.| 311 312**Example** 313 314```ts 315import HashMap from '@ohos.util.HashMap'; 316 317let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 318 319let sourceCloseCallback: media.SourceCloseCallback = (uuid: number) => { 320 console.log(`Closing resource with handle ${uuid}`); 321 // Clear resources related to the current UUID. 322 requests.remove(uuid); 323}; 324``` 325 326## AudioState<sup>(deprecated)</sup> 327 328type AudioState = 'idle' | 'playing' | 'paused' | 'stopped' | 'error' 329 330Describes the audio playback state. You can obtain the state through the **state** property. 331 332> **NOTE** 333> 334> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [AVPlayerState](#avplayerstate9) instead. 335 336**System capability**: SystemCapability.Multimedia.Media.AudioPlayer 337 338| Type | Description | 339| ------- | ---------------------------------------------- | 340| 'idle' | No audio playback is in progress. The audio player is in this state after the **'dataload'** or **'reset'** event is triggered.| 341| 'playing' | Audio playback is in progress. The audio player is in this state after the **'play'** event is triggered. | 342| 'paused' | Audio playback is paused. The audio player is in this state after the **'pause'** event is triggered. | 343| 'stopped' | Audio playback is stopped. The audio player is in this state after the **'stop'** event is triggered. | 344| 'error' | Audio playback is in the error state. | 345 346## VideoPlayState<sup>(deprecated)</sup> 347 348type VideoPlayState = 'idle' | 'prepared' | 'playing' | 'paused' | 'stopped' | 'error' 349 350Describes the video playback state. You can obtain the state through the **state** property. 351 352> **NOTE** 353> 354> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [AVPlayerState](#avplayerstate9) instead. 355 356**System capability**: SystemCapability.Multimedia.Media.VideoPlayer 357 358| Type | Description | 359| -------- | -------------- | 360| 'idle' | The video player is idle.| 361| 'prepared' | Video playback is being prepared.| 362| 'playing' | Video playback is in progress.| 363| 'paused' | Video playback is paused.| 364| 'stopped' | Video playback is stopped.| 365| 'error' | Video playback is in the error state. | 366