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## Required Permissions
10
11To 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).
12
13
14## Child Components
15
16Not supported
17
18
19## APIs
20
21Video(value: VideoOptions)
22
23**Parameters**
24
25| Name| Type| Mandatory| Description|
26| -------- | -------- | -------- | -------- |
27| value | [VideoOptions](#videooptions) | Yes| Video information.|
28
29##  VideoOptions
30
31| Name             | Type                                                    | Mandatory| Description                                                    |
32| ------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
33| src                 | string \| [Resource](ts-types.md#resource)                            | No  | Path of the video source, which can be a local path or a URL.<br>The video resources can be stored in the **video** or **rawfile** folder under **resources**.<br>The path can include a **dataability://** prefix, which indicates that the path is provided by a DataAbility Overview. For details about the path, see [DataAbility Overview](../../../application-models/dataability-overview.md).<br>- Strings with the **file:///data/storage** prefix are supported, which are used to read resources in the application sandbox. 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.|
34| 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 |
35| 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.                |
36| controller          | [VideoController](#videocontroller)                          | No  | Video controller to control the video playback status.                    |
37
38
39## PlaybackSpeed<sup>8+</sup>
40
41| Name                  | Description       |
42| -------------------- | --------- |
43| Speed_Forward_0_75_X | 0.75x playback speed.|
44| Speed_Forward_1_00_X | 1x playback speed.   |
45| Speed_Forward_1_25_X | 1.25x playback speed.|
46| Speed_Forward_1_75_X | 1.75x playback speed.|
47| Speed_Forward_2_00_X | 2x playback speed.   |
48
49## Attributes
50
51In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
52
53### muted
54
55muted(value: boolean)
56
57Specifies whether to mute the video.
58
59**System capability**: SystemCapability.ArkUI.ArkUI.Full
60
61**Parameters**
62
63| Name| Type   | Mandatory| Description                        |
64| ------ | ------- | ---- | ---------------------------- |
65| value  | boolean | Yes  | Whether to mute the video.<br>Default value: **false**|
66
67### autoPlay
68
69autoPlay(value: boolean)
70
71Specifies whether to enable auto play
72
73**System capability**: SystemCapability.ArkUI.ArkUI.Full
74
75**Parameters**
76
77| Name| Type   | Mandatory| Description                            |
78| ------ | ------- | ---- | -------------------------------- |
79| value  | boolean | Yes  | Whether to enable auto play.<br>Default value: **false**|
80
81### controls
82
83controls(value: boolean)
84
85Specifies whether to display the video playback control bar.
86
87**System capability**: SystemCapability.ArkUI.ArkUI.Full
88
89**Parameters**
90
91| Name| Type   | Mandatory| Description                                           |
92| ------ | ------- | ---- | ----------------------------------------------- |
93| value  | boolean | Yes  | Whether to display the video playback control bar.<br>Default value: **true**|
94
95### objectFit
96
97objectFit(value: ImageFit)
98
99Sets the video scale type.
100
101**System capability**: SystemCapability.ArkUI.ArkUI.Full
102
103**Parameters**
104
105| Name| Type                                     | Mandatory| Description                            |
106| ------ | ----------------------------------------- | ---- | -------------------------------- |
107| value  | [ImageFit](ts-appendix-enums.md#imagefit) | Yes  | Video scale type.<br>Default value: **Cover**|
108
109### loop
110
111loop(value: boolean)
112
113Specifies whether to repeat the video.
114
115**System capability**: SystemCapability.ArkUI.ArkUI.Full
116
117**Parameters**
118
119| Name| Type   | Mandatory| Description                                    |
120| ------ | ------- | ---- | ---------------------------------------- |
121| value  | boolean | Yes  | Whether to repeat the video.<br>Default value: **false**|
122
123## Events
124
125In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
126
127### onStart
128
129onStart(event:() =&gt; void)
130
131Triggered when the video is played.
132
133**System capability**: SystemCapability.ArkUI.ArkUI.Full
134
135### onPause
136
137onPause(event:() =&gt; void)
138
139Triggered when the video playback is paused.
140
141**System capability**: SystemCapability.ArkUI.ArkUI.Full
142
143### onFinish
144
145onFinish(event:() =&gt; void)
146
147Triggered when the video playback is finished.
148
149**System capability**: SystemCapability.ArkUI.ArkUI.Full
150
151### onError
152
153onError(event:() =&gt; void)
154
155Triggered when the video playback fails.
156
157**System capability**: SystemCapability.ArkUI.ArkUI.Full
158
159### onStop<sup>12+</sup>
160
161onStop(event:() =&gt; void)
162
163Triggered when the video playback is stopped (after **stop()** is called).
164
165**System capability**: SystemCapability.ArkUI.ArkUI.Full
166
167### onPrepared
168
169onPrepared(callback:(event: { duration: number }) =&gt; void)
170
171Triggered when video preparation is complete.
172
173**System capability**: SystemCapability.ArkUI.ArkUI.Full
174
175**Parameters**
176
177| Name  | Type  | Mandatory| Description                      |
178| -------- | ------ | ---- | -------------------------- |
179| duration | number | Yes  | Duration of the video, in seconds.|
180
181### onSeeking
182
183onSeeking(callback:(event: { time: number }) =&gt; void)
184
185Triggered to report the time when the progress bar is being dragged.
186
187**System capability**: SystemCapability.ArkUI.ArkUI.Full
188
189**Parameters**
190
191| Name| Type  | Mandatory| Description                          |
192| ------ | ------ | ---- | ------------------------------ |
193| time   | number | Yes  | Current video playback progress, in seconds.|
194
195### onSeeked
196
197onSeeked(callback:(event: { time: number }) =&gt; void)
198
199Triggered to report the playback time when the user finishes dragging the progress bar.
200
201**System capability**: SystemCapability.ArkUI.ArkUI.Full
202
203**Parameters**
204
205| Name| Type  | Mandatory| Description                          |
206| ------ | ------ | ---- | ------------------------------ |
207| time   | number | Yes  | Current video playback progress, in seconds.|
208
209### onUpdate
210
211onUpdate(callback:(event: { time: number }) =&gt; void)
212
213Triggered when the playback progress changes.
214
215**System capability**: SystemCapability.ArkUI.ArkUI.Full
216
217**Parameters**
218
219| Name| Type  | Mandatory| Description                          |
220| ------ | ------ | ---- | ------------------------------ |
221| time   | number | Yes  | Current video playback progress, in seconds.|
222
223### onFullscreenChange
224
225onFullscreenChange(callback:(event: { fullscreen: boolean }) =&gt; void)
226
227Triggered when the playback is switched between full-screen mode and non-full-screen mode.
228
229**System capability**: SystemCapability.ArkUI.ArkUI.Full
230
231**Parameters**
232
233| Name    | Type   | Mandatory| Description                                                 |
234| ---------- | ------- | ---- | ----------------------------------------------------- |
235| fullscreen | boolean | Yes  | The value **true** means that the playback is in full-screen mode, and **false** means the opposite.|
236
237
238## VideoController
239
240Defines 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).
241
242
243### Objects to Import
244
245```ts
246let controller: VideoController = new VideoController()
247```
248
249
250### start
251
252start(): void
253
254Starts playback.
255
256### pause
257
258pause(): void
259
260Pauses playback. The current frame is then displayed, and playback will be resumed from this paused position.
261
262### stop
263
264stop(): void
265
266Stops playback. The current frame is then displayed, and playback will restart from the very beginning.
267
268### setCurrentTime
269
270setCurrentTime(value: number)
271
272Sets the video playback position.
273
274**Parameters**
275
276| Name  | Type  | Mandatory  | Description          |
277| ----- | ------ | ---- | -------------- |
278| value | number | Yes   | Video playback position, in seconds.|
279
280### requestFullscreen
281
282requestFullscreen(value: boolean)
283
284Requests full-screen mode.
285
286**Parameters**
287
288| Name| Type| Mandatory| Description                        |
289| ------ | -------- | ---- | -------------------------------- |
290| value  | boolean  | Yes  | Whether to play the video in full screen mode within the application window.|
291
292### exitFullscreen
293
294exitFullscreen()
295
296Exits full-screen mode.
297
298### setCurrentTime<sup>8+</sup>
299
300setCurrentTime(value: number, seekMode: SeekMode)
301
302Sets the video playback position with the specified seek mode.
303
304**Parameters**
305
306| Name     | Type    | Mandatory  | Description          |
307| -------- | -------- | ---- | -------------- |
308| value    | number   | Yes   | Video playback position, in seconds.|
309| seekMode | [SeekMode](#seekmode8) | Yes   | Seek mode.         |
310
311## SeekMode<sup>8+</sup>
312
313| Name              | Description            |
314| ---------------- | -------------- |
315| PreviousKeyframe | Seeks to the nearest previous keyframe. |
316| NextKeyframe     | Seeks to the nearest next keyframe. |
317| ClosestKeyframe  | Seeks to the nearest keyframe.    |
318| Accurate         | Seeks to a specific frame, regardless of whether the frame is a keyframe.|
319
320## Example
321
322```ts
323// xxx.ets
324@Entry
325@Component
326struct VideoCreateComponent {
327  @State videoSrc: Resource = $rawfile('video1.mp4')
328  @State previewUri: Resource = $r('app.media.poster1')
329  @State curRate: PlaybackSpeed = PlaybackSpeed.Speed_Forward_1_00_X
330  @State isAutoPlay: boolean = false
331  @State showControls: boolean = true
332  controller: VideoController = new VideoController()
333
334  build() {
335    Column() {
336      Video({
337        src: this.videoSrc,
338        previewUri: this.previewUri,
339        currentProgressRate: this.curRate,
340        controller: this.controller
341      })
342        .width('100%')
343        .height(600)
344        .autoPlay(this.isAutoPlay)
345        .controls(this.showControls)
346        .onStart(() => {
347          console.info('onStart')
348        })
349        .onPause(() => {
350          console.info('onPause')
351        })
352        .onFinish(() => {
353          console.info('onFinish')
354        })
355        .onError(() => {
356          console.info('onError')
357        })
358        .onStop(() => {
359          console.info('onStop')
360        })
361        .onPrepared((e?: DurationObject) => {
362          if (e != undefined) {
363            console.info('onPrepared is ' + e.duration)
364          }
365        })
366        .onSeeking((e?: TimeObject) => {
367          if (e != undefined) {
368            console.info('onSeeking is ' + e.time)
369          }
370        })
371        .onSeeked((e?: TimeObject) => {
372          if (e != undefined) {
373            console.info('onSeeked is ' + e.time)
374          }
375        })
376        .onUpdate((e?: TimeObject) => {
377          if (e != undefined) {
378            console.info('onUpdate is ' + e.time)
379          }
380        })
381
382      Row() {
383        Button('src').onClick(() => {
384          this.videoSrc = $rawfile('video2.mp4') // Switch the video source.
385        }).margin(5)
386        Button('previewUri').onClick(() => {
387          this.previewUri = $r('app.media.poster2') // Switch the preview image.
388        }).margin(5)
389        Button('controls').onClick(() => {
390          this.showControls = !this.showControls // Specify whether to show the control bar.
391        }).margin(5)
392      }
393
394      Row() {
395        Button('start').onClick(() => {
396          this.controller.start() // Start playback.
397        }).margin(5)
398        Button('pause').onClick(() => {
399          this.controller.pause() // Pause playback.
400        }).margin(5)
401        Button('stop').onClick(() => {
402          this.controller.stop() // Stop playback.
403        }).margin(5)
404        Button('setTime').onClick(() => {
405          this.controller.setCurrentTime(10, SeekMode.Accurate) // Seek to the 10s position of the video.
406        }).margin(5)
407      }
408
409      Row() {
410        Button('rate 0.75').onClick(() => {
411          this.curRate = PlaybackSpeed.Speed_Forward_0_75_X // Play the video at the 0.75x speed.
412        }).margin(5)
413        Button('rate 1').onClick(() => {
414          this.curRate = PlaybackSpeed.Speed_Forward_1_00_X // Play the video at the 1x speed.
415        }).margin(5)
416        Button('rate 2').onClick(() => {
417          this.curRate = PlaybackSpeed.Speed_Forward_2_00_X // Play the video at the 2x speed.
418        }).margin(5)
419      }
420    }
421  }
422}
423
424interface DurationObject {
425  duration: number;
426}
427
428interface TimeObject {
429  time: number;
430}
431```
432