1# Video Playback 2 3The system provides two solutions for video playback development: 4 5- **AVPlayer** class: provides ArkTS and JS APIs to implement audio and video playback. It also supports parsing streaming media and local assets, decapsulating media assets, decoding video, and rendering video. It is applicable to end-to-end playback of media assets and can be used to play video files in MP4 and MKV formats. 6 7- **\<Video>** component: encapsulates basic video playback capabilities. It can be used to play video files after the data source and basic information are set. However, its scalability is poor. This component is provided by ArkUI. For details about how to use this component for video playback development, see [Video Component](../ui/arkts-common-components-video-player.md). 8 9In this topic, you will learn how to use the AVPlayer to develop a video playback service that plays a complete video file. If you want the application to continue playing the video in the background or when the screen is off, you must use the [AVSession](avsession-overview.md) and [continuous task](../task-management/continuous-task.md) to prevent the playback from being forcibly interrupted by the system. 10 11## Development Guidelines 12 13The full playback process includes creating an **AVPlayer** instance, setting the media asset to play and the window to display the video, setting playback parameters (volume, speed, and scale type), controlling playback (play, pause, seek, and stop), resetting the playback configuration, and releasing the instance. During application development, you can use the **state** attribute of the AVPlayer to obtain the AVPlayer state or call **on('stateChange')** to listen for state changes. If the application performs an operation when the AudioPlayer is not in the given state, the system may throw an exception or generate other undefined behavior. 14 15**Figure 1** Playback state transition 16 17 18 19For details about the state, see [AVPlayerState](../reference/apis/js-apis-media.md#avplayerstate9). When the AVPlayer is in the **prepared**, **playing**, **paused**, or **completed** state, the playback engine is working and a large amount of RAM is occupied. If your application does not need to use the AVPlayer, call **reset()** or **release()** to release the instance. 20 21### How to Develop 22 23Read [AVPlayer](../reference/apis/js-apis-media.md#avplayer9) for the API reference. 24 251. Call **createAVPlayer()** to create an **AVPlayer** instance. The AVPlayer is the **idle** state. 26 272. Set the events to listen for, which will be used in the full-process scenario. The table below lists the supported events. 28 | Event Type| Description| 29 | -------- | -------- | 30 | stateChange | Mandatory; used to listen for changes of the **state** attribute of the AVPlayer.| 31 | error | Mandatory; used to listen for AVPlayer errors.| 32 | durationUpdate | Used to listen for progress bar updates to refresh the media asset duration.| 33 | timeUpdate | Used to listen for the current position of the progress bar to refresh the current time.| 34 | seekDone | Used to listen for the completion status of the **seek()** request.<br>This event is reported when the AVPlayer seeks to the playback position specified in **seek()**.| 35 | speedDone | Used to listen for the completion status of the **setSpeed()** request.<br>This event is reported when the AVPlayer plays video at the speed specified in **setSpeed()**.| 36 | volumeChange | Used to listen for the completion status of the **setVolume()** request.<br>This event is reported when the AVPlayer plays video at the volume specified in **setVolume()**.| 37 | bitrateDone | Used to listen for the completion status of the **setBitrate()** request, which is used for HTTP Live Streaming (HLS) streams.<br>This event is reported when the AVPlayer plays video at the bit rate specified in **setBitrate()**.| 38 | availableBitrates | Used to listen for available bit rates of HLS resources. The available bit rates are provided for **setBitrate()**.| 39 | bufferingUpdate | Used to listen for network playback buffer information.| 40 | startRenderFrame | Used to listen for the rendering time of the first frame during video playback.| 41 | videoSizeChange | Used to listen for the width and height of video playback and adjust the window size and ratio.| 42 | audioInterrupt | Used to listen for audio interruption. This event is used together with the **audioInterruptMode** attribute.<br>This event is reported when the current audio playback is interrupted by another (for example, when a call is coming), so the application can process the event in time.| 43 443. Set the media asset URL. The AVPlayer enters the **initialized** state. 45 > **NOTE** 46 > 47 > The URL in the code snippet below is for reference only. You need to check the media asset validity and set the URL based on service requirements. 48 > 49 > - If local files are used for playback, ensure that the files are available and the application sandbox path is used for access. For details about how to obtain the application sandbox path, see [Obtaining Application File Paths](../application-models/application-context-stage.md#obtaining-application-file-paths). For details about the application sandbox and how to push files to the application sandbox, see [File Management](../file-management/app-sandbox-directory.md). 50 > 51 > - If a network playback path is used, you must request the ohos.permission.INTERNET [permission](../security/accesstoken-guidelines.md). 52 > 53 > - You can also use **ResourceManager.getRawFd** to obtain the file descriptor of a file packed in the HAP file. For details, see [ResourceManager API Reference](../reference/apis/js-apis-resource-manager.md#getrawfd9). 54 > 55 > - The [playback formats and protocols](avplayer-avrecorder-overview.md#supported-formats-and-protocols) in use must be those supported by the system. 56 574. Obtain and set the surface ID of the window to display the video. 58 The application obtains the surface ID from the XComponent. For details about the process, see [XComponent](../reference/arkui-ts/ts-basic-components-xcomponent.md). 59 605. Call **prepare()** to switch the AVPlayer to the **prepared** state. In this state, you can obtain the duration of the media asset to play and set the scale type and volume. 61 626. Call **play()**, **pause()**, **seek()**, and **stop()** to perform video playback control as required. 63 647. (Optional) Call **reset()** to reset the AVPlayer. The AVPlayer enters the **idle** state again and you can change the media asset URL. 65 668. Call **release()** to switch the AVPlayer to the **released** state. Now your application exits the playback. 67 68 69### Sample Code 70 71 72```ts 73import media from '@ohos.multimedia.media'; 74import fs from '@ohos.file.fs'; 75import common from '@ohos.app.ability.common'; 76import { BusinessError } from '@ohos.base'; 77 78export class AVPlayerDemo { 79 private count: number = 0; 80 private surfaceID: string = ''; // The surfaceID parameter specifies the window used to display the video. Its value is obtained through the XComponent. 81 private isSeek: boolean = true; // Specify whether the seek operation is supported. 82 private fileSize: number = -1; 83 private fd: number = 0; 84 // Set AVPlayer callback functions. 85 setAVPlayerCallback(avPlayer: media.AVPlayer) { 86 // Callback function for the seek operation. 87 avPlayer.on('seekDone', (seekDoneTime: number) => { 88 console.info(`AVPlayer seek succeeded, seek time is ${seekDoneTime}`); 89 }) 90 // Callback function for errors. If an error occurs during the operation on the AVPlayer, reset() is called to reset the AVPlayer. 91 avPlayer.on('error', (err: BusinessError) => { 92 console.error(`Invoke avPlayer failed, code is ${err.code}, message is ${err.message}`); 93 avPlayer.reset(); // Call reset() to reset the AVPlayer, which enters the idle state. 94 }) 95 // Callback function for state changes. 96 avPlayer.on('stateChange', async (state: string, reason: media.StateChangeReason) => { 97 switch (state) { 98 case 'idle': // This state is reported upon a successful callback of reset(). 99 console.info('AVPlayer state idle called.'); 100 avPlayer.release(); // Call release() to release the instance. 101 break; 102 case 'initialized': // This state is reported when the AVPlayer sets the playback source. 103 console.info('AVPlayer state initialized called.'); 104 avPlayer.surfaceId = this.surfaceID; // Set the window to display the video. This setting is not required when a pure audio asset is to be played. 105 avPlayer.prepare(); 106 break; 107 case 'prepared': // This state is reported upon a successful callback of prepare(). 108 console.info('AVPlayer state prepared called.'); 109 avPlayer.play(); // Call play() to start playback. 110 break; 111 case 'playing': // This state is reported upon a successful callback of play(). 112 console.info('AVPlayer state playing called.'); 113 if (this.count !== 0) { 114 if (this.isSeek) { 115 console.info('AVPlayer start to seek.'); 116 avPlayer.seek(avPlayer.duration); // Call seek() to seek to the end of the video clip. 117 } else { 118 // When the seek operation is not supported, the playback continues until it reaches the end. 119 console.info('AVPlayer wait to play end.'); 120 } 121 } else { 122 avPlayer.pause(); // Call pause() to pause the playback. 123 } 124 this.count++; 125 break; 126 case 'paused': // This state is reported upon a successful callback of pause(). 127 console.info('AVPlayer state paused called.'); 128 avPlayer.play(); // Call play() again to start playback. 129 break; 130 case 'completed': // This state is reported upon the completion of the playback. 131 console.info('AVPlayer state completed called.'); 132 avPlayer.stop(); // Call stop() to stop the playback. 133 break; 134 case 'stopped': // This state is reported upon a successful callback of stop(). 135 console.info('AVPlayer state stopped called.'); 136 avPlayer.reset(); // Call reset() to reset the AVPlayer state. 137 break; 138 case 'released': 139 console.info('AVPlayer state released called.'); 140 break; 141 default: 142 console.info('AVPlayer state unknown called.'); 143 break; 144 } 145 }) 146 } 147 148 // The following demo shows how to use the file system to open the sandbox address, obtain the media file address, and play the media file using the URL attribute. 149 async avPlayerUrlDemo() { 150 // Create an AVPlayer instance. 151 let avPlayer: media.AVPlayer = await media.createAVPlayer(); 152 // Set a callback function for state changes. 153 this.setAVPlayerCallback(avPlayer); 154 let fdPath = 'fd://'; 155 let context = getContext(this) as common.UIAbilityContext; 156 // Obtain the sandbox address filesDir through UIAbilityContext. The stage model is used as an example. 157 let pathDir = context.filesDir; 158 let path = pathDir + '/H264_AAC.mp4'; 159 // Open the corresponding file address to obtain the file descriptor and assign a value to the URL to trigger the reporting of the initialized state. 160 let file = await fs.open(path); 161 fdPath = fdPath + '' + file.fd; 162 this.isSeek = true; // The seek operation is supported. 163 avPlayer.url = fdPath; 164 } 165 166 // The following demo shows how to use resourceManager to obtain the media file packed in the HAP file and play the media file by using the fdSrc attribute. 167 async avPlayerFdSrcDemo() { 168 // Create an AVPlayer instance. 169 let avPlayer: media.AVPlayer = await media.createAVPlayer(); 170 // Set a callback function for state changes. 171 this.setAVPlayerCallback(avPlayer); 172 // Call getRawFd of the resourceManager member of UIAbilityContext to obtain the media asset URL. 173 // The return type is {fd,offset,length}, where fd indicates the file descriptor address of the HAP file, offset indicates the media asset offset, and length indicates the duration of the media asset to play. 174 let context = getContext(this) as common.UIAbilityContext; 175 let fileDescriptor = await context.resourceManager.getRawFd('H264_AAC.mp4'); 176 let avFileDescriptor: media.AVFileDescriptor = 177 { fd: fileDescriptor.fd, offset: fileDescriptor.offset, length: fileDescriptor.length }; 178 this.isSeek = true; // The seek operation is supported. 179 // Assign a value to fdSrc to trigger the reporting of the initialized state. 180 avPlayer.fdSrc = avFileDescriptor; 181 } 182 183 // The following demo shows how to use the file system to open the sandbox address, obtain the media file address, and play the media file with the seek operation using the dataSrc attribute. 184 async avPlayerDataSrcSeekDemo() { 185 // Create an AVPlayer instance. 186 let avPlayer: media.AVPlayer = await media.createAVPlayer(); 187 // Set a callback function for state changes. 188 this.setAVPlayerCallback(avPlayer); 189 // dataSrc indicates the playback source address. When the seek operation is supported, fileSize indicates the size of the file to be played. The following describes how to assign a value to fileSize. 190 let src: media.AVDataSrcDescriptor = { 191 fileSize: -1, 192 callback: (buf: ArrayBuffer, length: number, pos: number | undefined) => { 193 let num = 0; 194 if (buf == undefined || length == undefined || pos == undefined) { 195 return -1; 196 } 197 num = fs.readSync(this.fd, buf, { offset: pos, length: length }); 198 if (num > 0 && (this.fileSize >= pos)) { 199 return num; 200 } 201 return -1; 202 } 203 } 204 let context = getContext(this) as common.UIAbilityContext; 205 // Obtain the sandbox address filesDir through UIAbilityContext. The stage model is used as an example. 206 let pathDir = context.filesDir; 207 let path = pathDir + '/H264_AAC.mp4'; 208 await fs.open(path).then((file: fs.File) => { 209 this.fd = file.fd; 210 }) 211 // Obtain the size of the file to be played. 212 this.fileSize = fs.statSync(path).size; 213 src.fileSize = this.fileSize; 214 this.isSeek = true; // The seek operation is supported. 215 avPlayer.dataSrc = src; 216 } 217 218 // The following demo shows how to use the file system to open the sandbox address, obtain the media file address, and play the media file without the seek operation using the dataSrc attribute. 219 async avPlayerDataSrcNoSeekDemo() { 220 // Create an AVPlayer instance. 221 let avPlayer: media.AVPlayer = await media.createAVPlayer(); 222 // Set a callback function for state changes. 223 this.setAVPlayerCallback(avPlayer); 224 let context = getContext(this) as common.UIAbilityContext; 225 let src: media.AVDataSrcDescriptor = { 226 fileSize: -1, 227 callback: (buf: ArrayBuffer, length: number) => { 228 let num = 0; 229 if (buf == undefined || length == undefined) { 230 return -1; 231 } 232 num = fs.readSync(this.fd, buf); 233 if (num > 0) { 234 return num; 235 } 236 return -1; 237 } 238 } 239 // Obtain the sandbox address filesDir through UIAbilityContext. The stage model is used as an example. 240 let pathDir = context.filesDir; 241 let path = pathDir + '/H264_AAC.mp4'; 242 await fs.open(path).then((file: fs.File) => { 243 this.fd = file.fd; 244 }) 245 this.isSeek = false; // The seek operation is not supported. 246 avPlayer.dataSrc = src; 247 } 248 249 // The following demo shows how to play live streams by setting the network address through the URL. 250 async avPlayerLiveDemo() { 251 // Create an AVPlayer instance. 252 let avPlayer: media.AVPlayer = await media.createAVPlayer(); 253 // Set a callback function for state changes. 254 this.setAVPlayerCallback(avPlayer); 255 this.isSeek = false; // The seek operation is not supported. 256 avPlayer.url = 'http://xxx.xxx.xxx.xxx:xx/xx/index.m3u8'; // Play live webcasting streams using HLS. 257 } 258} 259``` 260 261
