# VideoPlayer

O player de um arquivo de vídeo, com os controles da casa e não os do
navegador: tocar e pausar, a barra de busca, o tempo decorrido e o total, o
som, a velocidade e a tela cheia. Serve ao vídeo que chega numa conversa, à
gravação de uma visita técnica e à aula gravada. Vive no índice da raiz, sem
peer: por baixo é o `<video>` do navegador.

```tsx
import { VideoPlayer } from '@rivocode/ui'

<VideoPlayer
  src={mensagem.videoUrl}
  poster={mensagem.capaUrl}
  duration={mensagem.segundos}
  label={`Vídeo de ${mensagem.autor}`}
/>
```

A peça embrulha um `<video>` sem `controls` e lê dele o que mostra: não há
estado de tocar que você precise guardar. Ela é um grupo nomeado: sem `label`,
o nome é "Vídeo", e numa conversa cada player precisa do seu ("Vídeo de Ana
Ribeiro"), senão o leitor de tela ouve vinte "Vídeo" iguais.

## O quadro

O vídeo ocupa a largura de quem o contém (`w-full`, com `max-w-full`) e a altura
sai da proporção. Sem `aspectRatio`, o quadro segue a do próprio vídeo assim
que ele carrega (o vídeo em pé do WhatsApp sai em pé) e fica 16:9 até lá. Com
`aspectRatio` (largura sobre altura, `9 / 16` para o vídeo gravado em pé), vale
a dela desde o começo, e o quadro não muda de altura ao carregar: passe quando
já souber. O vídeo que não bate com a proporção ganha faixa escura dos lados, e
nunca é cortado. No celular vale o mesmo, pelo tamanho que o `expo-video`
informa ao carregar.

O palco e a faixa de controles são escuros nos dois temas, como o do
`ImageViewer`: as cores saem dos papéis `media-*`, e não do tema, porque a
imagem em movimento pede fundo neutro e o tema claro lavaria o quadro. Os
pares (ícone sobre o palco, a parte tocada da busca sobre a que falta, o
controle inativo) são medidos a 4,5:1 e 3:1 pelo `check:contrast`.

`poster` é a imagem que aparece antes do primeiro toque, o mesmo do `<video>`.
Com `preload="metadata"`, o padrão, o navegador traz a duração e, sem
`poster`, o primeiro quadro. Numa conversa com muitos vídeos, `preload="none"`
não baixa nada até o toque, e aí o `poster` é o que segura o quadro.

## Num balão de chat

Dentro de um balão, que se mede pelo conteúdo, dê a largura que quiser e
deixe-a encolher na tela estreita:

```tsx
<Message role="assistant" variant="chat">
  <VideoPlayer src={video.url} poster={video.capa} className="w-72" />
</Message>
```

O `max-w-full` já vem da peça: a 320px o player encolhe com o balão, e a
página não rola de lado. Para o vídeo em pé, `aspectRatio={9 / 16}` com uma
largura menor (`w-40`), senão ele ocupa a tela inteira na altura.

## Os quatro momentos

| `data-state` | O que a pessoa vê |
| --- | --- |
| `paused` | o triângulo de tocar no meio do quadro (antes do primeiro toque) e na faixa, o tempo onde parou e o total |
| `loading` | o giro no quadro e no botão; o botão vira "Carregando o vídeo", anuncia `aria-busy` e **recusa o segundo toque** |
| `playing` | as duas barras de pausar, e a busca andando |
| `error` | a frase "Não foi possível carregar o vídeo." no quadro, com "Tentar de novo" logo abaixo; tocar e buscar ficam desligados |

O carregando aparece quando a pessoa pede para tocar e o arquivo ainda não tem
dados, e de novo se a rede engasga no meio (`waiting`). Ele é anunciado numa
região viva, e some sozinho quando o vídeo anda. Se você já sabe a duração,
passe em `duration`: ela aparece antes do arquivo e libera a busca sem esperar
os metadados.

**O erro não perde o lugar.** "Tentar de novo" chama o seu `onRetry` e recarrega
o arquivo, e quando ele volta, a posição é a de antes da falha. Use o `onRetry`
para trocar um endereço assinado que venceu: o `src` novo carrega sozinho.
`onError` recebe o `MediaError` do navegador, para o seu registro.

Ao fim, `onEnded` dispara, o botão volta a tocar, e o próximo toque recomeça do
início. `onPlay` dispara quando o vídeo anda de fato, depois da espera, e é o
lugar de marcar a mensagem como vista.

## Teclado e ponteiro

Clicar no quadro toca e pausa, e o duplo clique abre a tela cheia. Com o foco
em qualquer parte do player (ou depois de clicar no quadro), valem os atalhos
de quem já usou um player de vídeo:

| Tecla | Faz |
| --- | --- |
| Espaço ou `k` | toca e pausa (Espaço num botão continua sendo o botão) |
| ← e → | voltam e avançam 5 segundos |
| `m` | tira e devolve o som |
| `f` | entra e sai da tela cheia |

Com Ctrl, Alt ou Cmd, a tecla não é da peça. A busca é um controle de faixa, o
`Slider` da Base UI: `role="slider"` com o nome "Posição do vídeo" e o tempo por
extenso no `aria-valuetext` ("1 minuto e 5 segundos de 2 minutos e 5
segundos"). Com o foco nela, as setas andam 5 segundos, Page Up e Page Down
andam 30, e Home e End vão ao começo e ao fim.

Com "reduzir movimento" ligado no sistema, o giro do carregando fica parado e
os botões trocam de cor sem transição. A peça nunca toca sozinha.

## Som, velocidade e tela cheia

O botão de som alterna entre "Tirar o som" e "Ligar o som". `muted` com
`onMutedChange` controla, para a escolha valer em todos os vídeos da conversa;
`defaultMuted` só muda o começo.

O botão de velocidade percorre `rates` em ordem e volta ao começo: 1x, 1,5x e
2x, sem ele. O nome dele contém o texto que se vê ("Velocidade 1,5x"). `rate`
com `onRateChange` controla; com uma velocidade só em `rates`, o botão some.

A tela cheia leva o player inteiro, com os controles da casa, pela API de tela
cheia do navegador; `onFullscreenChange` avisa da entrada e da saída, inclusive
pelo `Esc`. No iPhone, onde o Safari não deixa um elemento ir para tela cheia,
o botão abre o player do sistema. `allowFullscreen={false}` tira o botão, e no
navegador que não deixa de jeito nenhum ele não aparece.

`disabled` desliga tudo: tocar, buscar, som, velocidade e tela cheia.

## Partes

`classNames` alcança `stage` (o quadro, com a proporção), `video`, `controls` (a
faixa de baixo), `play`, `seek` (a área que recebe o arrasto), `track`,
`indicator`, `thumb`, `time`, `rate`, `mute`, `fullscreen`, `error` e `retry`.
`labels` troca os doze textos: `player`, `play`, `pause`, `loading`, `seek`,
`rate`, `mute`, `unmute`, `fullscreen`, `exitFullscreen`, `error` e `retry`.

## Quando não usar

- **Áudio** é `AudioPlayer`. O `AudioPlayer` desenha a onda porque o som não
  tem imagem; o `VideoPlayer` usa o espaço para o quadro. Mensagem de voz num
  `VideoPlayer` é um retângulo escuro vazio.
- **Imagem parada** é `ImageViewer`. Ele abre a foto em tela cheia com zoom e
  navega entre várias; o `VideoPlayer` toca um arquivo só, no lugar.
- **Vídeo decorativo** (o fundo de uma página de entrada, um GIF em loop) não
  leva controle nenhum: é `<video autoPlay muted loop playsInline>`, e com
  "reduzir movimento" ele não deve tocar.
- **Vídeo de terceiro** (YouTube, Vimeo) vem no `<iframe>` deles, com o player
  deles: o `src` daqui é o arquivo, e não a página do vídeo.

## No React Native

Traduz, no caminho próprio `@rivocode/ui-native/video`: o React Native não toca vídeo sozinho, e o `expo-video` é peer **opcional** e módulo nativo (`npx expo install expo-video`). A regra é a da casa, **um subcaminho por peer**: quem não toca vídeo não reconstrói o app por causa dele, e quem só toca áudio não leva o `expo-video` junto com o `expo-audio`.

A API é a do web: `src`, `poster`, `label`, `aspectRatio`, `duration`, `rates`, `rate`, `defaultRate`, `onRateChange`, `muted`, `defaultMuted`, `onMutedChange`, `allowFullscreen`, `onFullscreenChange`, `onPlay`, `onPause`, `onEnded`, `onError`, `onRetry`, `disabled`, `labels` e `classNames`, com os mesmos nomes de parte. O `src` é o `VideoSource` do `expo-video`: endereço, `require("./clipe.mp4")` ou `{ uri, headers }`, e o `poster` aceita endereço ou `require`. O `onError` recebe a frase do `expo-video`, e não um `MediaError`. Não há `preload`: quem decide quanto baixar é o player nativo.

**O quadro é o `VideoView` sem os controles do sistema**, e a faixa de baixo é a mesma do web, desenhada com `View` sobre as cores de `tokens.media`, escuras nos dois esquemas. O `expo-video` não desenha capa: a peça põe o `poster` num `Image` por cima até o primeiro toque.

**A tela cheia é a do sistema**: o botão chama o `enterFullscreen` do `VideoView`, e lá quem desenha os controles é o iOS ou o Android: o `nativeControls` liga só enquanto ela está aberta, e é ele que traz o fechar e o arrastar para baixo do iPhone. No Android, o botão e o gesto de voltar saem da tela cheia, e não da tela do app. Não há atalho de teclado, porque não há teclado. A busca é `adjustable`, com o nome "Posição do vídeo" e o tempo por extenso no valor falado; deslizar para cima e para baixo no leitor de tela anda 5 segundos. O carregando troca o triângulo pelo giro, recusa o segundo toque e é anunciado, e o erro mostra "Tentar de novo", que recarrega o arquivo e volta à posição de antes. O controle desabilitado segue a regra do pacote, a camada inteira a 50%.

**A miniatura sem player na tela é o `useVideoPreview`**, do mesmo caminho: `useVideoPreview(src, { time, maxWidth })` devolve `status` (`idle`, `loading`, `ready` ou `error`), `thumbnail`, `aspectRatio` e `duration`. Ele abre o arquivo num `createVideoPlayer` mudo, com os `headers` do `src`, espera o `sourceLoad`, tira o quadro pelo `generateThumbnailsAsync` e chama o `release`. É para o vídeo da conversa: a `MessageMedia` de `/ai` recebe a proporção e a duração pelas props e o quadro pelo `renderPoster`. O `thumbnail` é um `VideoThumbnail`, que só o `Image` do `expo-image` desenha; o `Image` do core não abre. Guarda os últimos 40 por endereço, abre no máximo dois por vez e solta o player de quem desmontou antes de terminar.

**No iOS e no Android.** Em tela cheia, os controles são os do sistema: no iOS fecha pelo “OK” ou arrastando para baixo; no Android pelo voltar ou pelo botão de sair. Fora da tela cheia, os controles são os da peça, iguais nos dois. No Android, o voltar do sistema sai da tela cheia.

## Importação

```tsx
import { VideoPlayer } from '@rivocode/ui'
```

## Exemplos

### Vídeo numa conversa

```tsx
import { VideoPlayer } from '@rivocode/ui'
import { Message } from '@rivocode/ui/ai'

const CLIP = 'https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4'

function poster(hue: number, title: string, width = 1280, height = 720) {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
    <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0" stop-color="hsl(${hue} 45% 55%)"/>
      <stop offset="1" stop-color="hsl(${hue + 50} 50% 22%)"/>
    </linearGradient></defs>
    <rect width="${width}" height="${height}" fill="url(#g)"/>
    <text x="48" y="${height - 56}" font-family="sans-serif" font-size="48" fill="white">${title}</text>
  </svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

export function ChatVideo() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Message variant="chat" role="assistant" author="Ana Ribeiro">
        <VideoPlayer
          src={CLIP}
          poster={poster(200, 'Vitrine nova')}
          duration={5}
          label="Vídeo de Ana Ribeiro"
          className="w-72"
        />
      </Message>
      <Message variant="chat" role="user">
        <VideoPlayer
          src={CLIP}
          poster={poster(320, 'Em pé', 720, 1280)}
          aspectRatio={9 / 16}
          preload="none"
          defaultMuted
          label="Seu vídeo"
          className="w-40"
        />
      </Message>
    </div>
  )
}
```

### Numa página, com velocidades

```tsx
import { VideoPlayer } from '@rivocode/ui'
import { Message } from '@rivocode/ui/ai'

const CLIP = 'https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4'

function poster(hue: number, title: string, width = 1280, height = 720) {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
    <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0" stop-color="hsl(${hue} 45% 55%)"/>
      <stop offset="1" stop-color="hsl(${hue + 50} 50% 22%)"/>
    </linearGradient></defs>
    <rect width="${width}" height="${height}" fill="url(#g)"/>
    <text x="48" y="${height - 56}" font-family="sans-serif" font-size="48" fill="white">${title}</text>
  </svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

export function PagePlayer() {
  return (
    <div className="w-full max-w-2xl">
      <VideoPlayer
        src={CLIP}
        poster={poster(150, 'Aula 4: canteiros')}
        rates={[0.75, 1, 1.25, 1.5, 2]}
        defaultRate={1}
        label="Aula 4: canteiros"
      />
    </div>
  )
}
```

### Arquivo que não carrega

```tsx
import { VideoPlayer } from '@rivocode/ui'
import { Message } from '@rivocode/ui/ai'

export function LoadError() {
  return (
    <div className="w-full max-w-md">
      <VideoPlayer src="/nao-existe.mp4" duration={42} label="Vídeo indisponível" />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `src` | `string` | sim |  | - | O endereco do arquivo: o mesmo `src` do `<video>`, inclusive `blob:` e `data:`. |
| `allowFullscreen` | `boolean` |  | `true` | - | Mostra o botao de tela cheia, que tambem responde a tecla `f` e ao duplo clique no quadro. |
| `aspectRatio` | `number` |  |  | - | A proporcao do quadro, largura sobre altura (`9 / 16` para o video de celular em pe). |
| `classNames` | `Partial<Record<"controls" \| "error" \| "fullscreen" \| "indicator" \| "mute" \| "play" \| "rate" \| "retry" \| "seek" \| "stage" \| "thumb" \| "time" \| "track" \| "video", string>>` |  |  | - | Classe por parte: `stage` (o quadro, com a proporcao), `video`, `controls` (a faixa de baixo), `play`, `seek` (a area que recebe o arrasto), `track`, `indicator`, `thumb`, `time`, `rate`, `mute`, `fullscreen`, `error` e `retry`. |
| `defaultMuted` | `boolean` |  | `false` | - | Comeca sem som, sem controlar. |
| `defaultRate` | `number` |  |  | - | A velocidade inicial, sem controlar. |
| `disabled` | `boolean` |  | `false` | - | Desliga tocar, buscar, velocidade, som e tela cheia. |
| `duration` | `number` |  |  | - | A duracao em segundos, quando ja e conhecida: aparece antes de o arquivo carregar e libera a busca sem esperar os metadados. |
| `label` | `string` |  |  | - | O nome acessivel do player, que e um grupo. |
| `labels` | `Partial<VideoPlayerLabels>` |  |  | - | Os textos da peca, para trocar o idioma. |
| `muted` | `boolean` |  |  | - | O som desligado, controlado. |
| `onEnded` | `(() => void)` |  |  | - | Chegou ao fim. |
| `onError` | `((error: MediaError \| null) => void)` |  |  | - | O arquivo nao carregou. |
| `onFullscreenChange` | `((fullscreen: boolean) => void)` |  |  | - | Entrou ou saiu da tela cheia, pelo botao, pela tecla ou pelo `Esc` do navegador. |
| `onMutedChange` | `((muted: boolean) => void)` |  |  | - | O som ligado ou desligado, a cada toque no botao de som ou na tecla `m`. |
| `onPause` | `(() => void)` |  |  | - | Pausou, pelo botao ou pelo sistema. |
| `onPlay` | `(() => void)` |  |  | - | Comecou a tocar de fato, depois da espera. |
| `onRateChange` | `((rate: number) => void)` |  |  | - | A velocidade nova, a cada toque no botao de velocidade. |
| `onRetry` | `(() => void)` |  |  | - | Chamado no "Tentar de novo", antes de a peca recarregar o arquivo. |
| `poster` | `string` |  |  | - | A imagem que aparece antes do primeiro toque, o mesmo `poster` do `<video>`. |
| `preload` | `"auto" \| "metadata" \| "none"` |  | `"metadata"` | - | O quanto o navegador baixa antes do toque. |
| `rate` | `number` |  |  | - | A velocidade controlada. |
| `rates` | `readonly number[]` |  |  | - | As velocidades que o botao percorre, em ordem. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [AudioPlayer](/componentes/audio-player.md)
- [Code](/componentes/code.md)
- [EventCalendar](/componentes/event-calendar.md)
- [Gantt](/componentes/gantt.md)
- [Kanban](/componentes/kanban.md)
- [PixCode](/componentes/pix-code.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
