componentes / video-player

VideoPlayer

Reproductor de video con controles propios, pantalla completa, subtítulos y atajos de teclado.

Cómo usar

Envuelve un `<video>` nativo. Los controles se ocultan tras `hideControlsAfter` ms de inactividad durante la reproducción y vuelven con ratón, toque o teclado. Hacer clic en el video alterna el play. Atajos: Espacio/K, flechas (búsqueda y volumen), M, F (pantalla completa). Pasa `<track kind="captions">` como hijo y aparece un botón de subtítulos. `variant="overlay"` añade un botón play grande en el centro mientras está en pausa y se adapta al ancho del reproductor (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` añade un botón play grande en el centro mientras está en pausa. Por debajo de 560px la barra de búsqueda baja de los botones y el slider de volumen se oculta.

preview

0:00 / 0:00

default

0:00 / 0:00

overlay

0:00 / 0:00

overlay, estrecho (300px)

variantes.tsx

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

Colores

preview

0:00 / 0:00

primary

0:00 / 0:00

success

0:00 / 0:00

warning

0:00 / 0:00

danger

colores.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" />

Tamaños

preview

0:00 / 0:00

tamanos.tsx

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

Color personalizado

preview

0:00 / 0:00

Rosa

0:00 / 0:00

Por tema

color-personalizado.tsx

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

Props

Prop	Valores	Predeterminado	Descripción
variant	default \| overlay	default	overlay: botón play grande en el centro mientras está en pausa; por debajo de 560px la barra de búsqueda baja de los botones y el slider de volumen se oculta
src	string	—	URL del video
poster	string	ninguno	Imagen mostrada antes de reproducir
label	string	Video	Nombre accesible del reproductor
autoPlay / muted / loop	boolean	false	Comportamientos nativos (autoPlay casi siempre necesita muted)
preload	none \| metadata \| auto	metadata	Cuánto carga el navegador antes del play
hideControlsAfter	number	2500	Ms de inactividad antes de ocultar los controles al reproducir; 0 los mantiene visibles
children	ReactNode	ninguno	`<track>` (subtítulos) y elementos `<source>` extra
labels	Partial<{ play, pause, mute, unmute, seek, volume, fullscreen, exitFullscreen, captions }>	textos en inglés	Reemplaza los textos internos (aria-labels de los botones y sliders)
onPlay / onPause / onEnded	() => void	ninguno	Llamados por los eventos de medios correspondientes
onTimeUpdate	(currentTime: number) => void	ninguno	Llamado durante la reproducción, con la posición en segundos
variantColor	primary \| success \| warning \| danger	primary	Color de acento (botón play, progreso, indicadores)
customColor	string \| { light, dark }	ninguno	Cualquier color CSS (o un par por tema). Reemplaza a variantColor
size	sm \| md \| lg	md	Tamaño de los controles y del texto
radius	none \| sm \| md \| lg \| full	lg	Redondeo de las esquinas
animation	none \| smooth \| fast \| bounce	smooth	Transición de los controles

Accesibilidad

El reproductor es un `role="group"` enfocable nombrado por `label`; enfócalo (Tab o clic en el video) y los atajos funcionan.
Los botones de play, silenciar y pantalla completa cambian de nombre según el estado (`play`/`pause`, `mute`/`unmute`, `fullscreen`/`exitFullscreen` en `labels`).
La barra de búsqueda y el volumen son `Slider`s (`role="slider"`) nombrados por `labels.seek` y `labels.volume`.
El botón de subtítulos solo aparece cuando el video tiene hijos `<track>`, y expone `aria-pressed` para activado/desactivado.
Los controles se ocultan tras `hideControlsAfter` de inactividad durante la reproducción, nunca mientras un control tiene el foco; los controles ocultos quedan `inert` (salen del orden de tabulación) y cualquier tecla, foco o movimiento del mouse los devuelve.
Con `variant="overlay"`, el botón de play central grande es `aria-hidden` y `tabIndex={-1}`: es un atajo para mouse y táctil, y quien usa teclado y lector de pantalla usa el botón de play de la barra.

Teclado

Tecla	Acción
Space / K	Play o pausa (cuando el foco no está en un botón o slider)
ArrowLeft / ArrowRight	Retroceder / avanzar 5s
ArrowUp / ArrowDown	Volumen +/- 10%
M	Silenciar o activar el sonido
F	Alternar pantalla completa

Ten en cuenta

Los subtítulos no se generan: pasa `<track kind="captions">` como hijos y ofrece transcripción o audiodescripción cuando el contenido lo necesite.
Evita `autoPlay`; si es necesario, empieza con `startMuted`, pues los navegadores bloquean el autoplay con sonido y sorprende al usuario. Traduce `labels` al idioma de la página.