# `Expresso.Element.Video`
[🔗](https://github.com/rellen/expresso/blob/main/lib/expresso/element/video.ex#L1)

An element that plays a video file in a slide

The `video` entity takes the path of a WebM or an MP4 file as its first
argument, relative to the working directory of the command or to the `root`
option of the deck. The `title` option names the video for a screen reader,
and the `poster` option gives the path of an image. Both are required. The
poster shows on paper, in the handout view, in the speaker view, in the
overview, in the menu and while the video loads.

The `video` element holds only `data-video`, the number of the element in
the deck, and the renderer writes each video one time, as a data URI, into
the element `expresso-videos`. `Expresso.Media` gives the reasons. The
presenter gives a video its source when it plays.

The video plays in the present view only, while its slide shows and the
element shows at the current step. Thus `at` gives the step where it
starts. A black screen, the menu and the overview pause it. A video starts
again from the start when its slide shows again. It has no sound, because a
browser starts a video with sound only after a click. With
`controls true`, the video shows the controls of the browser, and the
presenter can turn the sound on. `docs/reference/video-element.md` gives
the rules.

# `t`

```elixir
@type t() :: %Expresso.Element.Video{
  __spark_metadata__: term(),
  aspect: term(),
  at: term(),
  captions: term(),
  class: term(),
  controls: term(),
  easing: term(),
  effect: term(),
  el: term(),
  index: term(),
  loop: term(),
  morph: term(),
  on: term(),
  poster: term(),
  signature: term(),
  speed: term(),
  src: term(),
  steps: term(),
  title: term(),
  width: term()
}
```

The struct of a video element

# `captions`

```elixir
@spec captions(term()) :: {:ok, String.t()} | {:error, String.t()}
```

Validate the `captions` option: the path of a WebVTT file

    iex> Expresso.Element.Video.captions("talk.vtt")
    {:ok, "talk.vtt"}
    iex> Expresso.Element.Video.captions("talk.srt")
    {:error, "the captions must be a WebVTT file with the extension .vtt, and not \"talk.srt\""}

# `get_assigns`

```elixir
@spec get_assigns(t()) :: map()
```

Make the assigns of the render function from the struct

The key `overlay` holds the attributes of the overlay contract, and the
`style` attribute of the `width` and `aspect` options. The key `poster`
holds the data URI of the poster, and the key `captions` the data URI of the
captions, or `nil`.

# `json`

```elixir
@spec json(Expresso.Deck.t()) :: String.t() | nil
```

Write the videos of a deck as JSON, or return `nil`

The value is a list with the data URI of each video, in the order of their
numbers. A deck with no video gets `nil`, and the document then holds no
element `expresso-videos`.

# `number`

```elixir
@spec number(Expresso.Deck.t()) :: Expresso.Deck.t()
```

Give each video of a deck its number

`Expresso.Renderer` calls this function before the render, and the render
function writes the number into `data-video`. `Expresso.Media.number/2`
gives the rules.

# `render`

```elixir
@spec render(map()) :: Phoenix.HTML.safe()
```

Make the HTML of a video

The element has the box of an embed: the poster, and the `video` element on
it. The `video` element has no source, and the presenter gives it one. It
has no sound, and it plays inline on a phone. A video with no controls gets
`tabindex="-1"`, so the key Tab does not go into it.

# `source`

```elixir
@spec source(term()) :: {:ok, String.t()} | {:error, String.t()}
```

Make sure that the source of a video is the path of a WebM or an MP4 file

This function is the custom type of the first argument. It does not read
the file, so a missing file gives an error at render time, as for an image.

    iex> Expresso.Element.Video.source("demo/demo.webm")
    {:ok, "demo/demo.webm"}

    iex> {:error, _message} = Expresso.Element.Video.source("demo/demo.mov")

# `sources`

```elixir
@spec sources(Expresso.Deck.t()) :: [String.t()]
```

Return the data URI of each file of the videos of a deck, in the order of
their numbers

It raises for a file that it cannot read. `Expresso.Media.sources/4` gives
the rules.

---

*Consult [api-reference.md](api-reference.md) for complete listing*