VideoPlayer
Vídeo numa conversa
Numa página, com velocidades
Arquivo que não carrega
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. OAudioPlayerdesenha a onda porque o som não tem imagem; oVideoPlayerusa o espaço para o quadro. Mensagem de voz numVideoPlayeré um retângulo escuro vazio. - Imagem parada é
ImageViewer. Ele abre a foto em tela cheia com zoom e navega entre várias; oVideoPlayertoca 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: osrcdaqui é 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
| Prop | Tipo | Padrão |
|---|---|---|
srcobrigatóriaO endereco do arquivo: o mesmo `src` do `<video>`, inclusive `blob:` e `data:`. | string | sem padrão |
allowFullscreenMostra o botao de tela cheia, que tambem responde a tecla `f` e ao duplo clique no quadro. | boolean | true |
aspectRatioA proporcao do quadro, largura sobre altura (`9 / 16` para o video de celular em pe). | number | sem padrão |
classNamesClasse 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 |
defaultMutedComeca sem som, sem controlar. | boolean | false |
defaultRateA velocidade inicial, sem controlar. | number | sem padrão |
disabledDesliga tocar, buscar, velocidade, som e tela cheia. | boolean | false |
durationA duracao em segundos, quando ja e conhecida: aparece antes de o arquivo carregar e libera a busca sem esperar os metadados. | number | sem padrão |
labelO nome acessivel do player, que e um grupo. | string | sem padrão |
labelsOs textos da peca, para trocar o idioma. | Partial<VideoPlayerLabels> | sem padrão |
mutedO som desligado, controlado. | boolean | sem padrão |
onEndedChegou ao fim. | (() => void) | sem padrão |
onErrorO arquivo nao carregou. | ((error: MediaError | null) => void) | sem padrão |
onFullscreenChangeEntrou ou saiu da tela cheia, pelo botao, pela tecla ou pelo `Esc` do navegador. | ((fullscreen: boolean) => void) | sem padrão |
onMutedChangeO som ligado ou desligado, a cada toque no botao de som ou na tecla `m`. | ((muted: boolean) => void) | sem padrão |
onPausePausou, pelo botao ou pelo sistema. | (() => void) | sem padrão |
onPlayComecou a tocar de fato, depois da espera. | (() => void) | sem padrão |
onRateChangeA velocidade nova, a cada toque no botao de velocidade. | ((rate: number) => void) | sem padrão |
onRetryChamado no "Tentar de novo", antes de a peca recarregar o arquivo. | (() => void) | sem padrão |
posterA imagem que aparece antes do primeiro toque, o mesmo `poster` do `<video>`. | string | sem padrão |
preloadO quanto o navegador baixa antes do toque. | "auto""metadata""none" | "metadata" |
rateA velocidade controlada. | number | sem padrão |
ratesAs 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.