Pular para o conteúdo
Dados

VideoPlayer

/componentes/video-player.mdmarkdown cru, para quem lê com agent em vez de olho

Vídeo numa conversa

Numa página, com velocidades

Arquivo que não carrega

Importar
import { VideoPlayer } from '@rivocode/ui'

Quando usar

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.

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:

<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.

API

PropTipoPadrão
srcobrigatória

O endereco do arquivo: o mesmo `src` do `<video>`, inclusive `blob:` e `data:`.

stringsem padrão
allowFullscreen

Mostra o botao de tela cheia, que tambem responde a tecla `f` e ao duplo clique no quadro.

booleantrue
aspectRatio

A proporcao do quadro, largura sobre altura (`9 / 16` para o video de celular em pe).

numbersem padrão
classNames

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`.

Partial<Record<"controls" | "error" | "fullscreen" | "indicator" | "mute" | "play" | "rate" | "retry" | "seek" | "stage" | "thumb" | "time" | "track" | "video", string>>sem padrão
defaultMuted

Comeca sem som, sem controlar.

booleanfalse
defaultRate

A velocidade inicial, sem controlar.

numbersem padrão
disabled

Desliga tocar, buscar, velocidade, som e tela cheia.

booleanfalse
duration

A duracao em segundos, quando ja e conhecida: aparece antes de o arquivo carregar e libera a busca sem esperar os metadados.

numbersem padrão
label

O nome acessivel do player, que e um grupo.

stringsem padrão
labels

Os textos da peca, para trocar o idioma.

Partial<VideoPlayerLabels>sem padrão
muted

O som desligado, controlado.

booleansem padrão
onEnded

Chegou ao fim.

(() => void)sem padrão
onError

O arquivo nao carregou.

((error: MediaError | null) => void)sem padrão
onFullscreenChange

Entrou ou saiu da tela cheia, pelo botao, pela tecla ou pelo `Esc` do navegador.

((fullscreen: boolean) => void)sem padrão
onMutedChange

O som ligado ou desligado, a cada toque no botao de som ou na tecla `m`.

((muted: boolean) => void)sem padrão
onPause

Pausou, pelo botao ou pelo sistema.

(() => void)sem padrão
onPlay

Comecou a tocar de fato, depois da espera.

(() => void)sem padrão
onRateChange

A velocidade nova, a cada toque no botao de velocidade.

((rate: number) => void)sem padrão
onRetry

Chamado no "Tentar de novo", antes de a peca recarregar o arquivo.

(() => void)sem padrão
poster

A imagem que aparece antes do primeiro toque, o mesmo `poster` do `<video>`.

stringsem padrão
preload

O quanto o navegador baixa antes do toque.

"auto""metadata""none""metadata"
rate

A velocidade controlada.

numbersem padrão
rates

As velocidades que o botao percorre, em ordem.

readonly number[]sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.