componentes / audio-player

AudioPlayer

Player de áudio acessível com play/pause, barra de busca, tempo, velocidade e volume.

Como usar

Envolve um `<audio>` nativo com controles próprios. A barra de busca e o volume usam o `Slider` da biblioteca. Teclado no player: Espaço ou K play/pause, setas buscam 5s e mudam o volume, M silencia. Todo texto interno pode ser trocado em `labels`. Com `variant="waveform"` vira um cartão compacto de mensagem de voz: o arquivo é baixado e decodificado em memória para desenhar as barras pelo volume (pulsando enquanto isso; um padrão se falhar, ex.: sem CORS em outra origem), e a onda é um slider (clique ou arraste para buscar, setas movem 5s). Para áudio longo, passe os picos em `waveform`.

preview

0:00

AudioPlayer.tsx

import { AudioPlayer } from "vaiperui";
 
<AudioPlayer
  src="/audio/roar.mp3"
  label="Nota de voz"
  onEnded={() => console.log("done")}
/>

Variantes

`waveform` é um cartão compacto de mensagem de voz: onda clicável, tempo atual / total e botão de velocidade.

preview

0:00

default

0:00 / 0:00

waveform

0:00 / 0:00

waveform + speeds

0:00 / 0:00

waveform + peaks

variantes.tsx

<AudioPlayer src="/audio/roar.mp3" />
<AudioPlayer src="/audio/roar.mp3" variant="waveform" />
<AudioPlayer src="/audio/roar.mp3" variant="waveform" speeds={[0.75, 1, 1.25, 1.5]} />
// peaks from 0 to 1, computed on the server: skips the download and analysis
<AudioPlayer src="/audio/roar.mp3" variant="waveform" waveform={[0.1, 0.4, 0.9, 0.6, 0.2]} />

Cores

preview

0:00

primary

0:00

success

0:00

warning

0:00

danger

cores.tsx

<AudioPlayer src="/audio/roar.mp3" variantColor="primary" />
<AudioPlayer src="/audio/roar.mp3" variantColor="success" />
<AudioPlayer src="/audio/roar.mp3" variantColor="warning" />
<AudioPlayer src="/audio/roar.mp3" variantColor="danger" />

Tamanhos

preview

0:00

tamanhos.tsx

<AudioPlayer src="/audio/roar.mp3" size="sm" />
<AudioPlayer src="/audio/roar.mp3" size="md" />
<AudioPlayer src="/audio/roar.mp3" size="lg" />

Cor personalizada

preview

0:00

Rosa

0:00

Por tema

cor-personalizada.tsx

<AudioPlayer src="/audio/roar.mp3" customColor="#db2777" />
<AudioPlayer src="/audio/roar.mp3" customColor={{ light: "#7c3aed", dark: "#c4b5fd" }} />

Props

Prop	Valores	Padrão	Descrição
variant	default \| waveform	default	default: barra de busca, volume e mudo. waveform: um cartão compacto como uma mensagem de voz, com onda clicável, tempo atual / total e botão de velocidade
bars	number	52	variante waveform: quantidade de barras
waveform	number[]	—	variante waveform: picos de 0 a 1, reamostrados para as barras. Pula o download e a análise do áudio
src	string	—	URL do áudio
label	string	Audio	Nome acessível do player
preload	none \| metadata \| auto	metadata	Quanto o navegador carrega antes do play
loop / autoPlay	boolean	false	Comportamentos nativos
speeds	number[]	[1, 1.5, 2]	Velocidades pelas quais o botão alterna; lista vazia o esconde
labels	Partial<{ play, pause, mute, unmute, seek, volume, speed }>	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"` nomeado por `label`, então leitores de tela o anunciam como um único controle.
O botão de play troca o nome entre `labels.play` e `labels.pause`; o de silenciar, entre `labels.mute` e `labels.unmute`.
A barra de busca e o volume são `Slider`s (`role="slider"`) nomeados por `labels.seek` e `labels.volume`; o botão de velocidade anuncia a taxa atual (ex.: `Playback speed: 1.5x`).
Com `variant="waveform"`, a onda é um `role="slider"` com `aria-valuemin`, `aria-valuemax`, `aria-valuenow` e um `aria-valuetext` como `0:12 of 0:40`; só recebe foco depois que a duração é conhecida e fica `aria-disabled` antes disso.
As barras da onda são `aria-hidden`, então apenas o slider é anunciado.
Enquanto a onda é analisada as barras pulsam, e o pulso é desligado com `prefers-reduced-motion`; se a análise falhar (ex.: sem CORS) um padrão é desenhado e o player continua funcionando.

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
Home / End	No slider da onda: ir ao início / fim (as setas movem 5s ali)
Tab	Percorre botões e sliders

Tenha em mente

Não há legendas nem transcrição: ofereça uma alternativa em texto para conteúdo falado (ex.: transcrição ao lado do player).
Passe um `label` significativo e traduza `labels` para o idioma da página; os padrões estão em inglês. `autoPlay` inicia o som sem ação do usuário, evite.