---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.5
alternate:
  - https://divkit.tech/docs/en/concepts/video.md
  - https://divkit.tech/docs/ru/concepts/video.md
  - href: en/concepts/video.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://divkit.tech/docs/en/llms.txt

# Video

To add a video clip to the screen:

- Use a [`video`](https://divkit.tech/docs/en/concepts/divs/2/div-video.md) element.
- Connect the player in your app. For more information, see [How to connect a video player](https://divkit.tech/docs/en/concepts/video.md).

{% note info %}

For the video to work, you must specify either `video_sources` or `player_settings_payload`. If both parameters are missing, a validation error will be generated.

{% endnote %}


{% cut "View an interactive example" %}


<iframe src="https://yastatic.net/s3/home/divkit/docs/1.0.8/index.html?url=https://yastatic.net/s3/home/divkit/doc_samples/common/video_1.json" width="700" height="500" frameborder="1"></iframe>


{% endcut %}


## Video element properties {#params}

In the example above:

- `video_sources`: An array of variants with different MIME types for the same video. The player selects the source that can be played on the platform. The parameter is optional, but either it or `player_settings_payload` must be specified.
- `player_settings_payload`: Additional settings for an external video player. Used for integration with custom players. The parameter is optional, but either it or `video_sources` must be specified.
- `repeatable`: Determines whether the video automatically repeats after playback is complete.
- `autostart`: Determines whether playback starts automatically.
- `muted`: Determines whether the sound is muted during playback.
- `preview`: A line that contains a preview image in Base64 encoding that is displayed until the player finishes rendering the first video frame.
- `elapsed_time_variable`: Contains the name of the variable that stores the current position of video playback in milliseconds. When the variable value is changed from the outside, the player follows the variable value to set the playback position.
- `playback_speed`: Video playback speed. A value of 1.0 corresponds to normal speed, values greater than 1.0 speed up playback, and values less than 1.0 slow it down. Supports using [expressions](https://divkit.tech/docs/en/concepts/expressions.md) for dynamic speed changes.
- `playerSettingsPayload`: A JSON object with additional video player settings. Supports using [expressions](https://divkit.tech/docs/en/concepts/expressions.md) for dynamic settings changes. When this parameter changes while the app is running, the video player will automatically update the playback settings.
- `playback_speed`: Video playback speed. A positive number. Default value: 1.0.
- `height`: Video element container height.
- `width`: Video element container width.

For a detailed description of the `video` element properties, see the element [reference book](https://divkit.tech/docs/en/concepts/divs/2/div-video.md).

## Playback control {#control}

The `video` element only contains the player properties. All video playback control elements are implemented by calling the [`div-action` actions](https://divkit.tech/docs/en/concepts/interaction.md).


{% cut "Sample code for video playback start" %}


```json translate=no
{
  "type": "image",
  "scale": "fit",
  "image_url": "https://sample_host/image.png",
  "actions": [
    {
      "log_id": "play",
      "url": "div-action://video?id=new_video&action=start"
    }
  ]
}
```


{% endcut %}


In this example, the video starts playing when you click the image. The `aiv-action` action call parameters:

- `path`: `video`: Indicates that the action is performed on a `video` element.
- `id`: `new_video`: The ID of the video element the action is performed on.
- `action`: `start`: The action that's performed over the video. In this case, video playback starts. Supported `action` parameter values for the video element:

    - `start`
    - `pause`


## How to connect a video player {#embed}

With DivKit, you can use a standard player or your own to. The latter comes in handy, for example, when you want to play videos in a format that's not supported by the standard player.

### Standard player {#default}

By default, DivKit uses a standard player for all platforms except Android, where you need to connect the player explicitly.

#### Android

DivKit uses ExoPlayer as a standard player for Android.

Because ExoPlayer initialization is a <q>heavy</q> operation, the player is only connected when you explicitly specify it in the `DivConfiguration` class. If you don't plan to use a video player in your app, don't call the `.divPlayerFactory` method in the `DivConfiguration` class builder.

To work with the standard player, pass `ExoDivPlayerFactory` from the `com.yandex.div.video` package to the `DivConfiguration` builder as a `.divPlayerFactory()` method argument.

The `DivConfiguration` class for supporting video will generally look like this:

```translate=no
DivConfiguration.Builder()
    .divPlayerFactory(ExoDivPlayerFactory())
    .build()
```

If you don't connect the player in the `DivConfiguration` class, there will be an empty block in place of and the same size as the player when rendering the screen with the `video` element.

#### Other platforms

On platforms other than Android, you don't need to explicitly call the `.divPlayerFactory()` method to use the standard player. When creating a video element, the platform-standard video player is used by default.

### Custom player support {#custom}

To connect your own video player to DivKit, create a factory that provides a player and a view for it at the request of the DivKit app. The factory must be a descendant of the `DivPlayerFactory` class.

The video player created by the factory must implement the `DivPlayer` interface and thus be a proxy for calls from DivKit. When implementing a custom player, note that JSON object properties (such as `playerSettingsPayload`) may contain [expressions](https://divkit.tech/docs/en/concepts/expressions.md) that need to be processed using `expressionResolver`. 

{% note info %}

When `playerSettingsPayload` changes while the app is running, DivKit will automatically call the `setSource` method with updated settings. Make sure your custom player correctly handles dynamic playback settings updates.

{% endnote %}

To take one example, here's how `DivPlayer` methods for `ExoPlayer` are implemented in Kotlin.


{% cut "See sample code" %}


```csharp translate=no
val player: ExoPlayer by lazy {
     SimpleExoPlayer.Builder(context).build()
     }

     override fun play() {
     player.play()
     }

     override fun pause() {
     player.pause()
     }

     override fun seek(toMs: Long) {
     player.seekTo(toMs)
     }

     override fun setSource(sourceVariants: List<DivVideoSource>, config: DivPlayerPlaybackConfig) {
     val mediaSource = sourceVariants.toMediaSource()

     player.setMediaSource(mediaSource)
     player.prepare()
     }

     override fun release() {
     player.release()
     }
```


{% endcut %}


<!-- source: en/_includes/index/troubleshooting.md -->
## Learn more {#troubleshooting}

You can discuss topics of interest in the DivKit user community in Telegram: [https://t.me/divkit_community_en](https://t.me/divkit_community_en).



[DivKit Repository](https://github.com/divkit/divkit)
<!-- endsource: en/_includes/index/troubleshooting.md -->