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><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><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 auto play
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.
155This feature cannot be used together with the [overlay](ts-universal-attributes-overlay.md) attribute. If both are set, the **CustomBuilder** attribute in **overlay** has no effect.
156
157**Atomic service API**: This API can be used in atomic services since API version 12.
158
159**System capability**: SystemCapability.ArkUI.ArkUI.Full
160
161**Parameters**
162
163| Name| Type| Mandatory| Description|
164| -------- | -------- | -------- | -------- |
165| enable | boolean | Yes| Whether to enable the AI analyzer.|
166
167> **NOTE**<br>
168>
169> This feature is available only when the custom control bar is used (that is, when the [controls](#controls) attribute is set to **false**).
170> This feature depends on device capabilities.
171
172### analyzerConfig<sup>12+</sup>
173
174analyzerConfig(config: ImageAnalyzerConfig)
175
176Provides AI analyzer configuration.
177
178**Atomic service API**: This API can be used in atomic services since API version 12.
179
180**System capability**: SystemCapability.ArkUI.ArkUI.Full
181
182| Name| Type| Mandatory| Description|
183| -------- | -------- | -------- | -------- |
184| config | [ImageAnalyzerConfig](ts-image-common.md#imageanalyzerconfig) | Yes| AI analysis type.|
185
186## Events
187
188In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
189
190### onStart
191
192onStart(event:() =&gt; void)
193
194Triggered when the video is played.
195
196**Atomic service API**: This API can be used in atomic services since API version 11.
197
198**System capability**: SystemCapability.ArkUI.ArkUI.Full
199
200### onPause
201
202onPause(event:() =&gt; void)
203
204Triggered when the video playback is paused.
205
206**Atomic service API**: This API can be used in atomic services since API version 11.
207
208**System capability**: SystemCapability.ArkUI.ArkUI.Full
209
210### onFinish
211
212onFinish(event:() =&gt; void)
213
214Triggered when the video playback is finished.
215
216**Atomic service API**: This API can be used in atomic services since API version 11.
217
218**System capability**: SystemCapability.ArkUI.ArkUI.Full
219
220### onError
221
222onError(event:() =&gt; void)
223
224Triggered when the video playback fails.
225
226**Atomic service API**: This API can be used in atomic services since API version 11.
227
228**System capability**: SystemCapability.ArkUI.ArkUI.Full
229
230### onStop<sup>12+</sup>
231
232onStop(event: Callback&lt;void&gt;)
233
234Triggered when the video playback is stopped (after **stop()** is called).
235
236**Atomic service API**: This API can be used in atomic services since API version 12.
237
238**System capability**: SystemCapability.ArkUI.ArkUI.Full
239
240### onPrepared
241
242onPrepared(callback:(event: { duration: number }) =&gt; void)
243
244Triggered when video preparation is complete.
245
246**Atomic service API**: This API can be used in atomic services since API version 11.
247
248**System capability**: SystemCapability.ArkUI.ArkUI.Full
249
250**Parameters**
251
252| Name  | Type  | Mandatory| Description                      |
253| -------- | ------ | ---- | -------------------------- |
254| duration | number | Yes  | Duration of the video, in seconds.|
255
256### onSeeking
257
258onSeeking(callback:(event: { time: number }) =&gt; void)
259
260Triggered to report the time when the progress bar is being dragged.
261
262**Atomic service API**: This API can be used in atomic services since API version 11.
263
264**System capability**: SystemCapability.ArkUI.ArkUI.Full
265
266**Parameters**
267
268| Name| Type  | Mandatory| Description                          |
269| ------ | ------ | ---- | ------------------------------ |
270| time   | number | Yes  | Current video playback progress, in seconds.|
271
272### onSeeked
273
274onSeeked(callback:(event: { time: number }) =&gt; void)
275
276Triggered to report the playback time when the user finishes dragging the progress bar.
277
278**Atomic service API**: This API can be used in atomic services since API version 11.
279
280**System capability**: SystemCapability.ArkUI.ArkUI.Full
281
282**Parameters**
283
284| Name| Type  | Mandatory| Description                          |
285| ------ | ------ | ---- | ------------------------------ |
286| time   | number | Yes  | Current video playback progress, in seconds.|
287
288### onUpdate
289
290onUpdate(callback:(event: { time: number }) =&gt; void)
291
292Triggered when the playback progress changes.
293
294**Atomic service API**: This API can be used in atomic services since API version 11.
295
296**System capability**: SystemCapability.ArkUI.ArkUI.Full
297
298**Parameters**
299
300| Name| Type  | Mandatory| Description                          |
301| ------ | ------ | ---- | ------------------------------ |
302| time   | number | Yes  | Current video playback progress, in seconds.|
303
304### onFullscreenChange
305
306onFullscreenChange(callback:(event: { fullscreen: boolean }) =&gt; void)
307
308Triggered when the playback is switched between full-screen mode and non-full-screen mode.
309
310**Atomic service API**: This API can be used in atomic services since API version 11.
311
312**System capability**: SystemCapability.ArkUI.ArkUI.Full
313
314**Parameters**
315
316| Name    | Type   | Mandatory| Description                                                 |
317| ---------- | ------- | ---- | ----------------------------------------------------- |
318| fullscreen | boolean | Yes  | The value **true** means that the playback is in full-screen mode, and **false** means the opposite.|
319
320
321## VideoController
322
323Defines 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).
324
325**Atomic service API**: This API can be used in atomic services since API version 11.
326
327**System capability**: SystemCapability.ArkUI.ArkUI.Full
328
329### Objects to Import
330
331```ts
332let controller: VideoController = new VideoController()
333```
334
335### constructor
336
337constructor()
338
339A constructor used to create a **VideoController** object.
340
341**Atomic service API**: This API can be used in atomic services since API version 11.
342
343**System capability**: SystemCapability.ArkUI.ArkUI.Full
344
345### start
346
347start()
348
349Starts playback.
350
351**Atomic service API**: This API can be used in atomic services since API version 11.
352
353**System capability**: SystemCapability.ArkUI.ArkUI.Full
354
355### pause
356
357pause()
358
359Pauses playback. The current frame is then displayed, and playback will be resumed from this paused position.
360
361**Atomic service API**: This API can be used in atomic services since API version 11.
362
363**System capability**: SystemCapability.ArkUI.ArkUI.Full
364
365### stop
366
367stop()
368
369Stops playback. The current frame is then displayed, and playback will restart from the very beginning.
370
371**Atomic service API**: This API can be used in atomic services since API version 11.
372
373**System capability**: SystemCapability.ArkUI.ArkUI.Full
374
375### reset<sup>12+</sup>
376
377reset(): void
378
379Resets the **AVPlayer** instance of this component, which displays the current frame and sets the playback to start from the beginning for subsequent playbacks.
380
381**Atomic service API**: This API can be used in atomic services since API version 12.
382
383**System capability**: SystemCapability.ArkUI.ArkUI.Full
384
385### setCurrentTime
386
387setCurrentTime(value: number)
388
389Sets the video playback position.
390
391**Atomic service API**: This API can be used in atomic services since API version 11.
392
393**System capability**: SystemCapability.ArkUI.ArkUI.Full
394
395**Parameters**
396
397| Name  | Type  | Mandatory  | Description          |
398| ----- | ------ | ---- | -------------- |
399| value | number | Yes   | Video playback position, in seconds.|
400
401### requestFullscreen
402
403requestFullscreen(value: boolean)
404
405Requests full-screen mode.
406
407**Atomic service API**: This API can be used in atomic services since API version 11.
408
409**System capability**: SystemCapability.ArkUI.ArkUI.Full
410
411**Parameters**
412
413| Name| Type| Mandatory| Description                        |
414| ------ | -------- | ---- | -------------------------------- |
415| value  | boolean  | Yes  | Whether to play the video in full screen mode within the application window.|
416
417### exitFullscreen
418
419exitFullscreen()
420
421Exits full-screen mode.
422
423**Atomic service API**: This API can be used in atomic services since API version 11.
424
425**System capability**: SystemCapability.ArkUI.ArkUI.Full
426
427### setCurrentTime<sup>8+</sup>
428
429setCurrentTime(value: number, seekMode: SeekMode)
430
431Sets the video playback position with the specified seek mode.
432
433**Atomic service API**: This API can be used in atomic services since API version 11.
434
435**System capability**: SystemCapability.ArkUI.ArkUI.Full
436
437**Parameters**
438
439| Name     | Type    | Mandatory  | Description          |
440| -------- | -------- | ---- | -------------- |
441| value    | number   | Yes   | Video playback position, in seconds.|
442| seekMode | [SeekMode](#seekmode8) | Yes   | Seek mode.         |
443
444## SeekMode<sup>8+</sup>
445
446**Atomic service API**: This API can be used in atomic services since API version 11.
447
448**System capability**: SystemCapability.ArkUI.ArkUI.Full
449
450| Name            | Description                        |
451| ---------------- | ---------------------------- |
452| PreviousKeyframe | Seeks to the nearest previous keyframe.  |
453| NextKeyframe     | Seeks to the nearest next keyframe.  |
454| ClosestKeyframe  | Seeks to the nearest keyframe.        |
455| Accurate         | Seeks to a specific frame, regardless of whether the frame is a keyframe.|
456
457## Example
458
459### Example 1
460
461```ts
462// xxx.ets
463@Entry
464@Component
465struct VideoCreateComponent {
466  @State videoSrc: Resource = $rawfile('video1.mp4')
467  @State previewUri: Resource = $r('app.media.poster1')
468  @State curRate: PlaybackSpeed = PlaybackSpeed.Speed_Forward_1_00_X
469  @State isAutoPlay: boolean = false
470  @State showControls: boolean = true
471  controller: VideoController = new VideoController()
472
473  build() {
474    Column() {
475      Video({
476        src: this.videoSrc,
477        previewUri: this.previewUri,
478        currentProgressRate: this.curRate,
479        controller: this.controller
480      })
481        .width('100%')
482        .height(600)
483        .autoPlay(this.isAutoPlay)
484        .controls(this.showControls)
485        .onStart(() => {
486          console.info('onStart')
487        })
488        .onPause(() => {
489          console.info('onPause')
490        })
491        .onFinish(() => {
492          console.info('onFinish')
493        })
494        .onError(() => {
495          console.info('onError')
496        })
497        .onStop(() => {
498          console.info('onStop')
499        })
500        .onPrepared((e?: DurationObject) => {
501          if (e != undefined) {
502            console.info('onPrepared is ' + e.duration)
503          }
504        })
505        .onSeeking((e?: TimeObject) => {
506          if (e != undefined) {
507            console.info('onSeeking is ' + e.time)
508          }
509        })
510        .onSeeked((e?: TimeObject) => {
511          if (e != undefined) {
512            console.info('onSeeked is ' + e.time)
513          }
514        })
515        .onUpdate((e?: TimeObject) => {
516          if (e != undefined) {
517            console.info('onUpdate is ' + e.time)
518          }
519        })
520
521      Row() {
522        Button('src').onClick(() => {
523          this.videoSrc = $rawfile('video2.mp4') // Switch the video source.
524        }).margin(5)
525        Button('previewUri').onClick(() => {
526          this.previewUri = $r('app.media.poster2') // Switch the preview image.
527        }).margin(5)
528        Button('controls').onClick(() => {
529          this.showControls = !this.showControls // Specify whether to show the control bar.
530        }).margin(5)
531      }
532
533      Row() {
534        Button('start').onClick(() => {
535          this.controller.start() // Start playback.
536        }).margin(2)
537        Button('pause').onClick(() => {
538          this.controller.pause() // Pause playback.
539        }).margin(2)
540        Button('stop').onClick(() => {
541          this.controller.stop() // Stop playback.
542        }).margin(2)
543        Button('reset').onClick(() => {
544          this.controller.reset () // Reset the AVPlayer instance.
545        }).margin(2)
546        Button('setTime').onClick(() => {
547          this.controller.setCurrentTime(10, SeekMode.Accurate) // Seek to the 10s position of the video.
548        }).margin(2)
549      }
550
551      Row() {
552        Button('rate 0.75').onClick(() => {
553          this.curRate = PlaybackSpeed.Speed_Forward_0_75_X // Play the video at the 0.75x speed.
554        }).margin(5)
555        Button('rate 1').onClick(() => {
556          this.curRate = PlaybackSpeed.Speed_Forward_1_00_X // Play the video at the 1x speed.
557        }).margin(5)
558        Button('rate 2').onClick(() => {
559          this.curRate = PlaybackSpeed.Speed_Forward_2_00_X // Play the video at the 2x speed.
560        }).margin(5)
561      }
562    }
563  }
564}
565
566interface DurationObject {
567  duration: number;
568}
569
570interface TimeObject {
571  time: number;
572}
573```
574
575### Example 2
576
577This example shows how to use the AI analyzer.
578
579```ts
580// xxx.ets
581@Entry
582@Component
583struct ImageAnalyzerExample {
584  @State videoSrc: Resource = $rawfile('video1.mp4')
585  @State previewUri: Resource = $r('app.media.poster1')
586  @State showControls: boolean = true
587  controller: VideoController = new VideoController()
588  config: ImageAnalyzerConfig = {
589    types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT]
590  }
591  private aiController: ImageAnalyzerController = new ImageAnalyzerController()
592  private options: ImageAIOptions = {
593    types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT],
594    aiController: this.aiController
595  }
596
597  build() {
598    Column() {
599      Video({
600        src: this.videoSrc,
601        previewUri: this.previewUri,
602        controller: this.controller,
603        imageAIOptions: this.options
604      })
605        .width('100%')
606        .height(600)
607        .controls(false)
608        .enableAnalyzer(true)
609        .analyzerConfig(this.config)
610        .onStart(() => {
611          console.info('onStart')
612        })
613        .onPause(() => {
614          console.info('onPause')
615        })
616
617      Row() {
618        Button('start').onClick(() => {
619          this.controller.start() // Start playback.
620        }).margin(5)
621        Button('pause').onClick(() => {
622          this.controller.pause() // Pause playback.
623        }).margin(5)
624        Button('getTypes').onClick(() => {
625            this.aiController.getImageAnalyzerSupportTypes()
626        }).margin(5)
627      }
628    }
629  }
630}
631```
632