componentes / video-player

VideoPlayer

Player de vídeo com controles próprios, tela cheia, legendas e atalhos de teclado.

Como usar

Envolve um `<video>` nativo. Os controles somem após `hideControlsAfter` ms de inatividade durante a reprodução e voltam com mouse, toque ou teclado. Clicar no vídeo alterna o play. Atalhos: Espaço/K, setas (busca e volume), M, F (tela cheia). Passe `<track kind="captions">` como filho e um botão de legendas aparece. `variant="overlay"` adiciona um botão play grande no centro enquanto pausado e se adapta à largura do player (container query).

preview

0:00 / 0:00

VideoPlayer.tsx

import { VideoPlayer } from "vaiperui";
 
<VideoPlayer src="/video/flower.mp4" poster="/video/poster.jpg" label="Flower">
  <track kind="captions" src="/video/en.vtt" srcLang="en" label="English" />
</VideoPlayer>

Variantes

`overlay` adiciona um botão play grande no centro enquanto pausado. Abaixo de 560px a barra de busca vai para baixo dos botões e o slider de volume some.

preview

0:00 / 0:00

default

0:00 / 0:00

overlay

0:00 / 0:00

overlay, estreito (300px)

variantes.tsx

<VideoPlayer src="/video/flower.mp4" />
<VideoPlayer src="/video/flower.mp4" variant="overlay" />

Cores

preview

0:00 / 0:00

primary

0:00 / 0:00

success

0:00 / 0:00

warning

0:00 / 0:00

danger

cores.tsx

<VideoPlayer src="/video/flower.mp4" variantColor="primary" />
<VideoPlayer src="/video/flower.mp4" variantColor="success" />
<VideoPlayer src="/video/flower.mp4" variantColor="warning" />
<VideoPlayer src="/video/flower.mp4" variantColor="danger" />

Tamanhos

preview

0:00 / 0:00

tamanhos.tsx

<VideoPlayer src="/video/flower.mp4" size="sm" />
<VideoPlayer src="/video/flower.mp4" size="md" />
<VideoPlayer src="/video/flower.mp4" size="lg" />

Cor personalizada

preview

0:00 / 0:00

Rosa

0:00 / 0:00

Por tema

cor-personalizada.tsx

<VideoPlayer src="/video/flower.mp4" customColor="#db2777" />
<VideoPlayer src="/video/flower.mp4" customColor={{ light: "#7c3aed", dark: "#c4b5fd" }} />

Props

Prop	Valores	Padrão	Descrição
variant	default \| overlay	default	overlay: botão play grande no centro enquanto pausado; abaixo de 560px a barra de busca vai para baixo dos botões e o slider de volume some
src	string	—	URL do vídeo
poster	string	nenhum	Imagem exibida antes de tocar
label	string	Video	Nome acessível do player
autoPlay / muted / loop	boolean	false	Comportamentos nativos (autoPlay quase sempre precisa de muted)
preload	none \| metadata \| auto	metadata	Quanto o navegador carrega antes do play
hideControlsAfter	number	2500	Ms de inatividade antes de esconder os controles ao tocar; 0 os mantém visíveis
children	ReactNode	nenhum	`<track>` (legendas) e elementos `<source>` extras
labels	Partial<{ play, pause, mute, unmute, seek, volume, fullscreen, exitFullscreen, captions }>	textos em inglês	Substitui os textos internos (aria-labels dos botões e sliders)
onPlay / onPause / onEnded	() => void	nenhum	Chamados pelos eventos de mídia correspondentes
onTimeUpdate	(currentTime: number) => void	nenhum	Chamado durante a reprodução, com a posição em segundos
variantColor	primary \| success \| warning \| danger	primary	Cor de destaque (botão play, progresso, indicadores)
customColor	string \| { light, dark }	nenhum	Qualquer cor CSS (ou um par por tema). Substitui o variantColor
size	sm \| md \| lg	md	Tamanho dos controles e do texto
radius	none \| sm \| md \| lg \| full	lg	Arredondamento dos cantos
animation	none \| smooth \| fast \| bounce	smooth	Transição dos controles

Acessibilidade

O player é um `role="group"` focável nomeado por `label`; foque nele (Tab ou clique no vídeo) e os atalhos funcionam.
Os botões de play, silenciar e tela cheia mudam de nome conforme o estado (`play`/`pause`, `mute`/`unmute`, `fullscreen`/`exitFullscreen` em `labels`).
A barra de busca e o volume são `Slider`s (`role="slider"`) nomeados por `labels.seek` e `labels.volume`.
O botão de legendas só aparece quando o vídeo tem filhos `<track>`, e expõe `aria-pressed` para ligado/desligado.
Os controles somem após `hideControlsAfter` de inatividade durante a reprodução, nunca enquanto um controle tem foco; controles ocultos ficam `inert` (saem da ordem de tabulação) e qualquer tecla, foco ou movimento do mouse os traz de volta.
Com `variant="overlay"`, o botão de play central grande é `aria-hidden` e `tabIndex={-1}`: é um atalho para mouse e toque, e quem usa teclado e leitor de tela usa o botão de play da barra.

Teclado

Tecla	Ação
Space / K	Play ou pause (quando o foco não está em um botão ou slider)
ArrowLeft / ArrowRight	Voltar / avançar 5s
ArrowUp / ArrowDown	Volume +/- 10%
M	Silenciar ou ativar o som
F	Alternar tela cheia

Tenha em mente

As legendas não são geradas: passe `<track kind="captions">` como filhos e ofereça transcrição ou audiodescrição quando o conteúdo precisar.
Evite `autoPlay`; se precisar, comece com `startMuted`, pois navegadores bloqueiam autoplay com som e isso surpreende o usuário. Traduza `labels` para o idioma da página.