1# Video 2 3The **Video** component is used to play a video and control its playback. 4 5> **NOTE** 6> 7> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> The **Video** component provides only simple video playback features. For complex video playback control scenarios, consider using the [AVPlayer](../../apis-media-kit/js-apis-media.md#avplayer9) API in conjunction with the [XComponent](ts-basic-components-xcomponent.md) component. 10 11## Required Permissions 12 13To use online videos, you must apply for the ohos.permission.INTERNET permission. For details about how to apply for a permission, see [Declaring Permissions](../../../security/AccessToken/declare-permissions.md). 14 15 16## Child Components 17 18Not supported 19 20 21## APIs 22 23### Video 24 25Video(value: VideoOptions) 26 27**Atomic service API**: This API can be used in atomic services since API version 11. 28 29**System capability**: SystemCapability.ArkUI.ArkUI.Full 30 31**Parameters** 32 33| Name| Type| Mandatory| Description| 34| -------- | -------- | -------- | -------- | 35| value | [VideoOptions](#videooptions) | Yes| Video information.| 36 37## VideoOptions 38 39**Atomic service API**: This API can be used in atomic services since API version 11. 40 41**System capability**: SystemCapability.ArkUI.ArkUI.Full 42 43| Name | Type | Mandatory| Description | 44| ------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 45| src | string \| [Resource](ts-types.md#resource) | No | Video source, which can be either a local or a network video.<br>The Resource type allows cross-package and cross-module access to resource files and is commonly used for accessing local videos.<br>- Resources in the rawfile folder are supported, which means that you can reference video files with **$rawfile**.<br>The string type is used for loading local videos and, more frequently, network videos.<br>- Network video URLs are supported.<br>- Strings with the **file://** prefix, that is, [application sandbox URIs](../../apis-core-file-kit/js-apis-file-fileuri.md#constructor10): **file://\<bundleName>/\<sandboxPath>**, are supported. They are used to access resources in the application sandbox path. Ensure that the application has the read permission to the files in the specified path.<br>**NOTE**<br>The supported video formats are MP4, MKV, and TS.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 46| currentProgressRate | number \| string \| [PlaybackSpeed<sup>8+</sup>](#playbackspeed8) | No | Video playback speed.<br>**NOTE**<br>The value of the number type can only be **0.75**, **1.0**, **1.25**, **1.75**, or **2.0**.<br>Default value: 1.0 \| PlaybackSpeed.Speed_Forward_1_00_X<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 47| previewUri | string \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [Resource](ts-types.md) | No | Path of the preview image displayed before the video playback starts. By default, no preview image is displayed.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 48| controller | [VideoController](#videocontroller) | No | Video controller to control the video playback status.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 49| imageAIOptions<sup>12+</sup> | [ImageAIOptions](ts-image-common.md#imageaioptions) | No | AI image analysis options. You can configure the analysis type or bind an analyzer controller through this parameter.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 50 51## PlaybackSpeed<sup>8+</sup> 52 53**Atomic service API**: This API can be used in atomic services since API version 11. 54 55**System capability**: SystemCapability.ArkUI.ArkUI.Full 56 57| Name | Description | 58| -------------------- | -------------- | 59| Speed_Forward_0_75_X | 0.75x playback speed.| 60| Speed_Forward_1_00_X | 1x playback speed. | 61| Speed_Forward_1_25_X | 1.25x playback speed.| 62| Speed_Forward_1_75_X | 1.75x playback speed.| 63| Speed_Forward_2_00_X | 2x playback speed. | 64 65## Attributes 66 67In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 68 69### muted 70 71muted(value: boolean) 72 73Specifies whether to mute the video. 74 75**Atomic service API**: This API can be used in atomic services since API version 11. 76 77**System capability**: SystemCapability.ArkUI.ArkUI.Full 78 79**Parameters** 80 81| Name| Type | Mandatory| Description | 82| ------ | ------- | ---- | ---------------------------- | 83| value | boolean | Yes | Whether to mute the video.<br>Default value: **false**| 84 85### autoPlay 86 87autoPlay(value: boolean) 88 89Specifies whether to enable autoplay. 90 91**Atomic service API**: This API can be used in atomic services since API version 11. 92 93**System capability**: SystemCapability.ArkUI.ArkUI.Full 94 95**Parameters** 96 97| Name| Type | Mandatory| Description | 98| ------ | ------- | ---- | -------------------------------- | 99| value | boolean | Yes | Whether to enable auto play.<br>Default value: **false**| 100 101### controls 102 103controls(value: boolean) 104 105Specifies whether to display the video playback control bar. 106 107**Atomic service API**: This API can be used in atomic services since API version 11. 108 109**System capability**: SystemCapability.ArkUI.ArkUI.Full 110 111**Parameters** 112 113| Name| Type | Mandatory| Description | 114| ------ | ------- | ---- | ----------------------------------------------- | 115| value | boolean | Yes | Whether to display the video playback control bar.<br>Default value: **true**| 116 117### objectFit 118 119objectFit(value: ImageFit) 120 121Sets the video scale type. 122 123**Atomic service API**: This API can be used in atomic services since API version 11. 124 125**System capability**: SystemCapability.ArkUI.ArkUI.Full 126 127**Parameters** 128 129| Name| Type | Mandatory| Description | 130| ------ | ----------------------------------------- | ---- | -------------------------------- | 131| value | [ImageFit](ts-appendix-enums.md#imagefit) | Yes | Video scale type.<br>Default value: **Cover**| 132 133### loop 134 135loop(value: boolean) 136 137Specifies whether to repeat the video. 138 139**Atomic service API**: This API can be used in atomic services since API version 11. 140 141**System capability**: SystemCapability.ArkUI.ArkUI.Full 142 143**Parameters** 144 145| Name| Type | Mandatory| Description | 146| ------ | ------- | ---- | ---------------------------------------- | 147| value | boolean | Yes | Whether to repeat the video.<br>Default value: **false**| 148 149### enableAnalyzer<sup>12+</sup> 150 151enableAnalyzer(enable: boolean) 152 153Sets whether to enable the AI analyzer, which supports subject recognition, text recognition, and object lookup. 154After this feature is enabled, the video automatically enters an analysis state to process the current frame when playback is paused, and exits the analysis state when playback is resumed. 155 156Note that if this attribute and the [overlay](ts-universal-attributes-overlay.md) attribute are both set, [CustomBuilder](ts-types.md#custombuilder8) specified in [overlay](ts-universal-attributes-overlay.md) has no effect. 157 158**Atomic service API**: This API can be used in atomic services since API version 12. 159 160**System capability**: SystemCapability.ArkUI.ArkUI.Full 161 162**Parameters** 163 164| Name| Type| Mandatory| Description| 165| -------- | -------- | -------- | -------- | 166| enable | boolean | Yes| Whether to enable the AI analyzer.| 167 168> **NOTE** 169> 170> This feature is available only when the custom control bar is used (that is, when the [controls](#controls) attribute is set to **false**). 171> 172> This feature depends on device capabilities. 173 174### analyzerConfig<sup>12+</sup> 175 176analyzerConfig(config: ImageAnalyzerConfig) 177 178Provides AI analyzer configuration. 179 180**Atomic service API**: This API can be used in atomic services since API version 12. 181 182**System capability**: SystemCapability.ArkUI.ArkUI.Full 183 184| Name| Type| Mandatory| Description| 185| -------- | -------- | -------- | -------- | 186| config | [ImageAnalyzerConfig](ts-image-common.md#imageanalyzerconfig) | Yes| AI analysis type.| 187 188## Events 189 190In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 191 192### onStart 193 194onStart(event:() => void) 195 196Triggered when the video is played. 197 198**Atomic service API**: This API can be used in atomic services since API version 11. 199 200**System capability**: SystemCapability.ArkUI.ArkUI.Full 201 202### onPause 203 204onPause(event:() => void) 205 206Triggered when the video playback is paused. 207 208**Atomic service API**: This API can be used in atomic services since API version 11. 209 210**System capability**: SystemCapability.ArkUI.ArkUI.Full 211 212### onFinish 213 214onFinish(event:() => void) 215 216Triggered when the video playback is finished. 217 218**Atomic service API**: This API can be used in atomic services since API version 11. 219 220**System capability**: SystemCapability.ArkUI.ArkUI.Full 221 222### onError 223 224onError(event:() => void) 225 226Triggered when the video playback fails. 227 228**Atomic service API**: This API can be used in atomic services since API version 11. 229 230**System capability**: SystemCapability.ArkUI.ArkUI.Full 231 232### onStop<sup>12+</sup> 233 234onStop(event: Callback<void>) 235 236Triggered when the video playback is stopped (after **stop()** is called). 237 238**Atomic service API**: This API can be used in atomic services since API version 12. 239 240**System capability**: SystemCapability.ArkUI.ArkUI.Full 241 242### onPrepared 243 244onPrepared(callback:(event: { duration: number }) => void) 245 246Triggered when video preparation is complete. 247 248**Atomic service API**: This API can be used in atomic services since API version 11. 249 250**System capability**: SystemCapability.ArkUI.ArkUI.Full 251 252**Parameters** 253 254| Name | Type | Mandatory| Description | 255| -------- | ------ | ---- | -------------------------- | 256| duration | number | Yes | Duration of the video, in seconds.| 257 258### onSeeking 259 260onSeeking(callback:(event: { time: number }) => void) 261 262Triggered to report the time when the progress bar is being dragged. 263 264**Atomic service API**: This API can be used in atomic services since API version 11. 265 266**System capability**: SystemCapability.ArkUI.ArkUI.Full 267 268**Parameters** 269 270| Name| Type | Mandatory| Description | 271| ------ | ------ | ---- | ------------------------------ | 272| time | number | Yes | Current video playback progress, in seconds.| 273 274### onSeeked 275 276onSeeked(callback:(event: { time: number }) => void) 277 278Triggered to report the playback time when the user finishes dragging the progress bar. 279 280**Atomic service API**: This API can be used in atomic services since API version 11. 281 282**System capability**: SystemCapability.ArkUI.ArkUI.Full 283 284**Parameters** 285 286| Name| Type | Mandatory| Description | 287| ------ | ------ | ---- | ------------------------------ | 288| time | number | Yes | Current video playback progress, in seconds.| 289 290### onUpdate 291 292onUpdate(callback:(event: { time: number }) => void) 293 294Triggered when the playback progress changes. 295 296**Atomic service API**: This API can be used in atomic services since API version 11. 297 298**System capability**: SystemCapability.ArkUI.ArkUI.Full 299 300**Parameters** 301 302| Name| Type | Mandatory| Description | 303| ------ | ------ | ---- | ------------------------------ | 304| time | number | Yes | Current video playback progress, in seconds.| 305 306### onFullscreenChange 307 308onFullscreenChange(callback:(event: { fullscreen: boolean }) => void) 309 310Triggered when the playback is switched between full-screen mode and non-full-screen mode. 311 312**Atomic service API**: This API can be used in atomic services since API version 11. 313 314**System capability**: SystemCapability.ArkUI.ArkUI.Full 315 316**Parameters** 317 318| Name | Type | Mandatory| Description | 319| ---------- | ------- | ---- | ----------------------------------------------------- | 320| fullscreen | boolean | Yes | The value **true** means that the playback is in full-screen mode, and **false** means the opposite.| 321 322 323## VideoController 324 325Defines a **VideoController** object to control one or more videos. For details about available video playback examples, see [@ohos.multimedia.media](../../apis-media-kit/js-apis-media.md). 326 327**Atomic service API**: This API can be used in atomic services since API version 11. 328 329**System capability**: SystemCapability.ArkUI.ArkUI.Full 330 331### Objects to Import 332 333```ts 334let controller: VideoController = new VideoController() 335``` 336 337### constructor 338 339constructor() 340 341A constructor used to create a **VideoController** object. 342 343**Atomic service API**: This API can be used in atomic services since API version 11. 344 345**System capability**: SystemCapability.ArkUI.ArkUI.Full 346 347### start 348 349start() 350 351Starts playback. 352 353**Atomic service API**: This API can be used in atomic services since API version 11. 354 355**System capability**: SystemCapability.ArkUI.ArkUI.Full 356 357### pause 358 359pause() 360 361Pauses playback. The current frame is then displayed, and playback will be resumed from this paused position. 362 363**Atomic service API**: This API can be used in atomic services since API version 11. 364 365**System capability**: SystemCapability.ArkUI.ArkUI.Full 366 367### stop 368 369stop() 370 371Stops playback. The current frame is then displayed, and playback will restart from the very beginning. 372 373**Atomic service API**: This API can be used in atomic services since API version 11. 374 375**System capability**: SystemCapability.ArkUI.ArkUI.Full 376 377### reset<sup>12+</sup> 378 379reset(): void 380 381Resets the **AVPlayer** instance of this component, which displays the current frame and sets the playback to start from the beginning for subsequent playbacks. 382 383**Atomic service API**: This API can be used in atomic services since API version 12. 384 385**System capability**: SystemCapability.ArkUI.ArkUI.Full 386 387### setCurrentTime 388 389setCurrentTime(value: number) 390 391Sets the video playback position. 392 393**Atomic service API**: This API can be used in atomic services since API version 11. 394 395**System capability**: SystemCapability.ArkUI.ArkUI.Full 396 397**Parameters** 398 399| Name | Type | Mandatory | Description | 400| ----- | ------ | ---- | -------------- | 401| value | number | Yes | Video playback position, in seconds.| 402 403### requestFullscreen 404 405requestFullscreen(value: boolean) 406 407Requests full-screen mode. 408 409**Atomic service API**: This API can be used in atomic services since API version 11. 410 411**System capability**: SystemCapability.ArkUI.ArkUI.Full 412 413**Parameters** 414 415| Name| Type| Mandatory| Description | 416| ------ | -------- | ---- | -------------------------------- | 417| value | boolean | Yes | Whether to play the video in full screen mode within the application window.| 418 419### exitFullscreen 420 421exitFullscreen() 422 423Exits full-screen mode. 424 425**Atomic service API**: This API can be used in atomic services since API version 11. 426 427**System capability**: SystemCapability.ArkUI.ArkUI.Full 428 429### setCurrentTime<sup>8+</sup> 430 431setCurrentTime(value: number, seekMode: SeekMode) 432 433Sets the video playback position with the specified seek mode. 434 435**Atomic service API**: This API can be used in atomic services since API version 11. 436 437**System capability**: SystemCapability.ArkUI.ArkUI.Full 438 439**Parameters** 440 441| Name | Type | Mandatory | Description | 442| -------- | -------- | ---- | -------------- | 443| value | number | Yes | Video playback position, in seconds.| 444| seekMode | [SeekMode](#seekmode8) | Yes | Seek mode. | 445 446## SeekMode<sup>8+</sup> 447 448**Atomic service API**: This API can be used in atomic services since API version 11. 449 450**System capability**: SystemCapability.ArkUI.ArkUI.Full 451 452| Name | Description | 453| ---------------- | ---------------------------- | 454| PreviousKeyframe | Seeks to the nearest previous keyframe. | 455| NextKeyframe | Seeks to the nearest next keyframe. | 456| ClosestKeyframe | Seeks to the nearest keyframe. | 457| Accurate | Seeks to a specific frame, regardless of whether the frame is a keyframe.| 458 459## Example 460 461### Example 1: Implementing Basic Video Playback Features 462 463This example covers the basic aspects of video playback, including how to manage the control bar, use preview images, handle autoplay, adjust the playback speed, and operate the controller for playback control. Additionally, it demonstrates how to implement callbacks for various playback states. 464 465```ts 466// xxx.ets 467@Entry 468@Component 469struct VideoCreateComponent { 470 @State videoSrc: Resource = $rawfile('video1.mp4') 471 @State previewUri: Resource = $r('app.media.poster1') 472 @State curRate: PlaybackSpeed = PlaybackSpeed.Speed_Forward_1_00_X 473 @State isAutoPlay: boolean = false 474 @State showControls: boolean = true 475 @State isShortcutKeyEnabled: boolean = false 476 controller: VideoController = new VideoController() 477 478 build() { 479 Column() { 480 Video({ 481 src: this.videoSrc, 482 previewUri: this.previewUri, 483 currentProgressRate: this.curRate, 484 controller: this.controller 485 }) 486 .width('100%') 487 .height(600) 488 .autoPlay(this.isAutoPlay) 489 .controls(this.showControls) 490 .enableShortcutKey(this.isShortcutKeyEnabled) 491 .onStart(() => { 492 console.info('onStart') 493 }) 494 .onPause(() => { 495 console.info('onPause') 496 }) 497 .onFinish(() => { 498 console.info('onFinish') 499 }) 500 .onError(() => { 501 console.info('onError') 502 }) 503 .onStop(() => { 504 console.info('onStop') 505 }) 506 .onPrepared((e?: DurationObject) => { 507 if (e != undefined) { 508 console.info('onPrepared is ' + e.duration) 509 } 510 }) 511 .onSeeking((e?: TimeObject) => { 512 if (e != undefined) { 513 console.info('onSeeking is ' + e.time) 514 } 515 }) 516 .onSeeked((e?: TimeObject) => { 517 if (e != undefined) { 518 console.info('onSeeked is ' + e.time) 519 } 520 }) 521 .onUpdate((e?: TimeObject) => { 522 if (e != undefined) { 523 console.info('onUpdate is ' + e.time) 524 } 525 }) 526 .onFullscreenChange((e?: FullscreenObject) => { 527 if (e != undefined) { 528 console.info('onFullscreenChange is ' + e.fullscreen) 529 } 530 }) 531 532 Row() { 533 Button('src').onClick(() => { 534 this.videoSrc = $rawfile('video2.mp4') // Switch the video source. 535 }).margin(5) 536 Button('previewUri').onClick(() => { 537 this.previewUri = $r('app.media.poster2') // Switch the preview image. 538 }).margin(5) 539 Button('controls').onClick(() => { 540 this.showControls = !this.showControls // Specify whether to show the control bar. 541 }).margin(5) 542 } 543 544 Row() { 545 Button('start').onClick(() => { 546 this.controller.start() // Start playback. 547 }).margin(2) 548 Button('pause').onClick(() => { 549 this.controller.pause() // Pause playback. 550 }).margin(2) 551 Button('stop').onClick(() => { 552 this.controller.stop() // Stop playback. 553 }).margin(2) 554 Button('reset').onClick(() => { 555 this.controller.reset () // Reset the AVPlayer instance. 556 }).margin(2) 557 Button('setTime').onClick(() => { 558 this.controller.setCurrentTime(10, SeekMode.Accurate) // Seek to the 10s position of the video. 559 }).margin(2) 560 } 561 562 Row() { 563 Button('rate 0.75').onClick(() => { 564 this.curRate = PlaybackSpeed.Speed_Forward_0_75_X // Play the video at the 0.75x speed. 565 }).margin(5) 566 Button('rate 1').onClick(() => { 567 this.curRate = PlaybackSpeed.Speed_Forward_1_00_X // Play the video at the 1x speed. 568 }).margin(5) 569 Button('rate 2').onClick(() => { 570 this.curRate = PlaybackSpeed.Speed_Forward_2_00_X // Play the video at the 2x speed. 571 }).margin(5) 572 } 573 } 574 } 575} 576 577interface DurationObject { 578 duration: number; 579} 580 581interface TimeObject { 582 time: number; 583} 584 585interface FullscreenObject { 586 fullscreen: boolean; 587} 588``` 589 590### Example 2: Enabling AI Image Analyzer 591 592This example shows how to use the **enableAnalyzer** attribute to enable AI image analyzer. 593 594```ts 595// xxx.ets 596@Entry 597@Component 598struct ImageAnalyzerExample { 599 @State videoSrc: Resource = $rawfile('video1.mp4') 600 @State previewUri: Resource = $r('app.media.poster1') 601 @State showControls: boolean = true 602 controller: VideoController = new VideoController() 603 config: ImageAnalyzerConfig = { 604 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT] 605 } 606 private aiController: ImageAnalyzerController = new ImageAnalyzerController() 607 private options: ImageAIOptions = { 608 types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT], 609 aiController: this.aiController 610 } 611 612 build() { 613 Column() { 614 Video({ 615 src: this.videoSrc, 616 previewUri: this.previewUri, 617 controller: this.controller, 618 imageAIOptions: this.options 619 }) 620 .width('100%') 621 .height(600) 622 .controls(false) 623 .enableAnalyzer(true) 624 .analyzerConfig(this.config) 625 .onStart(() => { 626 console.info('onStart') 627 }) 628 .onPause(() => { 629 console.info('onPause') 630 }) 631 632 Row() { 633 Button('start').onClick(() => { 634 this.controller.start() // Start playback. 635 }).margin(5) 636 Button('pause').onClick(() => { 637 this.controller.pause() // Pause playback. 638 }).margin(5) 639 Button('getTypes').onClick(() => { 640 this.aiController.getImageAnalyzerSupportTypes() 641 }).margin(5) 642 } 643 } 644 } 645} 646``` 647