AudioPlayer
Mensagem de voz numa conversa
Picos calculados do arquivo
Sem forma de onda, numa barra
Arquivo que não carrega
Em sequência, com os não ouvidos
import { AudioPlayer } from '@rivocode/ui/audio'Quando usar
O player de um arquivo de áudio: tocar e pausar, a forma de onda que se enche
conforme toca, arrastar na onda (ou numa barra) para buscar, o tempo atual e o
total, e a velocidade. Serve à mensagem de voz numa conversa, à gravação de um
atendimento e à aula gravada. Vive em @rivocode/ui/audio, um caminho sem
peer, pelo peso: quem monta formulário não carrega a onda nem o decodificador
de picos.
import { AudioPlayer } from '@rivocode/ui/audio'
<AudioPlayer
src={mensagem.audioUrl}
peaks={mensagem.picos}
duration={mensagem.segundos}
aria-label={`Mensagem de voz de ${mensagem.autor}`}
/>
A peça embrulha um <audio> escondido e lê dele o que mostra: não há estado
de tocar que você precise guardar. Ela é um grupo nomeado: sem aria-label, o
nome é "Áudio", e numa lista de mensagens cada player precisa do seu ("Mensagem
de voz de Ana Ribeiro"), senão o leitor de tela ouve vinte "Áudio" iguais.
A forma de onda
peaks é um número por trecho do arquivo, em qualquer escala: a peça divide
pelo maior, e o silêncio ainda desenha um traço baixo, para a onda não ter
buraco. bars diz quantas barras saem (48, sem ele), e os peaks são
reamostrados para esse número pelo maior de cada trecho, então tanto faz
mandar 48 ou 1.000 picos. Sem peaks, a busca é uma barra fina, com o
mesmo arrasto e o mesmo teclado.
A barra que já tocou sai em fg, e a que falta tocar em border-disabled: a
diferença entre as duas é medida a 3:1 sobre a página, o cartão, o balão do
outro (surface-hover) e o seu balão (accent-subtle), nos dois temas e com
contraste aumentado.
Guarde os picos junto do arquivo. audioPeaks calcula a partir do
arquivo, no navegador:
import { audioPeaks } from '@rivocode/ui/audio'
const picos = await audioPeaks(arquivo, { count: 48 })
Ele aceita Blob (o que o gravador entrega), ArrayBuffer ou endereço, e
devolve de 0 a 1. O custo é o arquivo inteiro: ele baixa tudo, decodifica
para amostras na memória (reamostrado a 8 kHz, cerca de 32 KB por segundo de
cada canal, ou uns 4 MB num minuto em estéreo) e percorre uma vez. Numa
mensagem de voz de segundos isso é nada; numa aula de uma hora são centenas de
megabytes. Calcule uma vez, na hora em que a gravação termina ou no servidor,
e salve os 48 números com a mensagem. Chamar o audioPeaks a cada tela
desenhada baixa cada áudio duas vezes.
Num balão de chat
No balão, use variant="bubble", o desenho da mensagem de voz do WhatsApp: o
tocar e a onda numa linha só, e embaixo a duração à esquerda ("0:12" parado,
"0:04 / 0:12" depois de começar) e a hora e os tiques da mensagem à direita. A
velocidade só aparece enquanto toca, à direita da onda, e a largura é de 240px
(w-60), para a onda não sumir num balão curto, sem nunca passar da coluna em
que mora: numa tela de 320px ela encolhe junto com o balão.
<Message variant="chat" role="user" time="14:32" status="read">
<AudioPlayer variant="bubble" src={voz.url} peaks={voz.peaks} duration={voz.segundos} />
</Message>
O Message entrega a hora. Quando o filho direto dele é um AudioPlayer
com variant="bubble", ele passa a time e o status para o meta do player
e não desenha a própria linha embaixo, que sobraria vazia de conteúdo. O
mecanismo é a prop meta, e não um contexto: ela é um nó qualquer, e fora do
Message você põe nela o que quiser. Se o player não é o filho direto (está
dentro de uma div sua), passe o meta você mesmo ou deixe o Message
desenhar a linha dele.
O padrão, variant="plain", é o player de página: o tempo atual e o total
embaixo da onda, e a velocidade sempre à direita. Ele mede a largura de quem o
contém (w-full); num balão sem o bubble, dê a largura e deixe-a encolher
(className="w-64 max-w-full"), senão a 320px a página rola de lado.
Não ouvido
unheard marca o áudio que a pessoa ainda não ouviu: um ponto de acento ao
lado da duração, nos dois desenhos, com o texto falado "Não ouvido" (o
labels.unheard). O ponto some no primeiro toque, sem esperar o app, e o
onHeard dispara uma vez nesse toque: é ali que você grava a escuta. Depois
de gravada, o seu unheard vira false e a peça não precisa de mais nada.
<AudioPlayer
variant="bubble"
src={voz.url}
duration={voz.segundos}
unheard={!voz.ouvido}
onHeard={() => marcarOuvido(voz.id)}
/>
O ponto é accent-text, a cor do texto de acento, que passa dos 3:1 da 1.4.11
sobre a página, o cartão e os dois balões. Ele não é o único sinal: o leitor
de tela ouve "Não ouvido" dentro do grupo do player.
Em sequência, um por vez
Numa conversa com vários áudios, crie um grupo com useAudioSequence e passe o
mesmo sequence a cada player. O grupo faz duas coisas sem estado nenhum do
seu lado:
- Um por vez. Tocar um áudio pausa o que estava tocando.
- O seguinte toca sozinho. Quando um áudio chega ao fim, o mais perto abaixo dele na tela começa do início, como no WhatsApp. O seguinte é medido pela posição na tela no momento do fim, e não pela ordem em que os players montaram: a lista invertida e a que carrega as antigas em cima dão o mesmo resultado. Um player desabilitado ou com erro é pulado.
import { AudioPlayer, useAudioSequence } from '@rivocode/ui/audio'
function Conversa({ mensagens }) {
const sequence = useAudioSequence()
return mensagens.map((m) => (
<Message key={m.id} variant="chat" role={m.papel} time={m.hora}>
<AudioPlayer variant="bubble" src={m.audio} duration={m.segundos} sequence={sequence} />
</Message>
))
}
useAudioSequence({ continuous: false }) deixa só o um por vez, sem tocar o
seguinte. Um grupo por conversa: dois grupos não se conhecem, e o player sem
sequence toca por conta própria. Numa lista virtualizada, o seguinte que
ainda não montou não toca.
Os quatro momentos
data-state |
O que a pessoa vê |
|---|---|
paused |
o triângulo de tocar, o tempo onde parou e o total |
loading |
o giro no lugar do triângulo; o botão vira "Carregando o áudio", anuncia aria-busy e recusa o segundo toque |
playing |
as duas barras de pausar, e a onda se enchendo |
error |
a frase "Não foi possível carregar o áudio." no lugar do tempo, e o tocar vira "Tentar de novo" |
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 som sai. Antes do toque não há giro: com
preload="metadata", o padrão, o navegador traz só a duração, e o total
aparece quando ela chega. Numa lista longa de áudios, preload="none" não
baixa nada até o toque. 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 som sai de fato, depois da espera, e é o
lugar de marcar a mensagem como ouvida.
A busca
A busca é um controle de faixa, o Slider da Base UI: role="slider" com o
nome "Posição do áudio" e o tempo por extenso no aria-valuetext ("1 minuto e
5 segundos de 2 minutos e 5 segundos"), e não "1:05", que o leitor de tela lê
como hora. As setas andam 5 segundos, Page Up e Page Down (e Shift com seta)
andam 30, e Home e End vão ao começo e ao fim. Arrastar com o dedo ou o
ponteiro busca em qualquer ponto da onda, e não só no pino.
A velocidade
O botão à direita 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"), para quem
comanda por voz dizer o que lê. rate com onRateChange controla, para a
velocidade escolhida valer em todos os áudios da conversa; defaultRate só
muda o começo. Com uma velocidade só em rates, o botão não aparece.
disabled desliga os três: tocar, buscar e velocidade.
Partes
classNames alcança play (o botão de tocar, e o de tentar de novo no erro),
seek (a área que recebe o arrasto), track, bar (cada barra da onda),
indicator (o preenchimento, só sem peaks), thumb, time, rate,
error e unheard (o ponto do não ouvido). Em bubble, time veste a
duração da segunda linha. labels troca os nove textos: player, play,
pause, loading, seek, rate, error, retry e unheard.
Quando não usar
- Andamento de uma tarefa é
Progress. OProgressanda sozinho até terminar e ninguém o arrasta; a busca doAudioPlayeré um controle, e a pessoa decide onde ela está. - Escolher um valor (volume de um alerta, uma faixa de preço) é
Slider. OSliderguarda um número seu; a busca do player mostra o tempo de um arquivo, e o número é do<audio>. - Vídeo é
<video controls>. O player desenha a onda porque áudio não tem imagem; um vídeo já tem a sua. - Som de interface (o toque de uma notificação, o bipe de leitura de um
código) não leva player: toca com
new Audio(url).play(), sem nada na tela.
No React Native
Traduz, no caminho próprio @rivocode/ui-native/audio: o React Native não toca áudio sozinho, e o expo-audio é peer opcional e módulo nativo (npx expo install expo-audio). A regra é a da casa, um subcaminho por peer: quem não toca áudio não reconstrói o app por causa dele. A onda é desenhada com View, uma por barra, e não cobra o react-native-svg.
A API é a do web: src, peaks, bars, duration, rates, rate, defaultRate, onRateChange, onPlay, onPause, onEnded, onError, onRetry, disabled, labels, classNames, variant, meta, unheard, onHeard e sequence, com os mesmos nomes de parte. O src é o AudioSource do expo-audio: endereço, require("./voz.m4a") ou { uri, headers }. O onError recebe a frase do expo-audio, e não um MediaError. Não há preload: quem decide quanto baixar é o player nativo.
Cabe no balão do Message. O balão do celular mede só o próprio conteúdo, então a peça tem largura mínima de 240pt (min-w-60), e a onda e o tempo não somem. Para outra largura, className (w-72, ou min-w-0 para soltar o mínimo). No balão, use variant="bubble", como no web: o tocar e a onda numa linha, e embaixo a duração à esquerda e a hora e os tiques do Message à direita, que ele passa pelo meta quando o player é o filho direto. A velocidade só aparece enquanto toca.
Os picos vêm prontos. O celular não tem Web Audio, então não há audioPeaks aqui: calcule no servidor, ou no web na hora em que a gravação sobe, e mande os números junto da mensagem.
A busca é adjustable, com o nome "Posição do áudio" e o tempo por extenso no valor falado; deslizar para cima e para baixo no leitor de tela anda 5 segundos, como as setas do web. O dedo arrasta em qualquer ponto da onda, e a posição só vai para o player quando o dedo sai, para o arrasto não disparar uma busca por quadro. O carregando troca o triângulo pelo giro, recusa o segundo toque e é anunciado, e o erro troca o tocar por "Tentar de novo", que recarrega o arquivo e volta à posição de antes.
Não ouvido e em sequência, como no web. unheard põe o ponto de acento ao lado da duração, um elemento image com o nome "Não ouvido", e ele some no primeiro toque, com o onHeard uma vez. O useAudioSequence vem do mesmo caminho e é o mesmo grupo do web: um áudio por vez, e quando um termina o seguinte abaixo dele na tela toca. A posição sai do measureInWindow de cada player no momento do fim, então a FlatList invertida do chat dá a mesma ordem que se vê.
import { AudioPlayer, useAudioSequence } from '@rivocode/ui-native/audio'
const sequence = useAudioSequence()
<AudioPlayer variant="bubble" src={voz.url} sequence={sequence} unheard={!voz.ouvido} onHeard={() => marcarOuvido(voz.id)} />
API
| Prop | Tipo | Padrão |
|---|---|---|
srcobrigatóriaO endereco do arquivo: o mesmo `src` do `<audio>`, inclusive `blob:` e `data:`. | string | sem padrão |
barsQuantas barras a onda desenha. | number | sem padrão |
classNamesClasse por parte: `play` (o botao de tocar, e o de tentar de novo no erro), `seek` (a area que recebe o arrasto), `track`, `bar` (cada barra da onda), `indicator` (o preenchimento, so sem `peaks`), `thumb`, `time`, `rate`, `error` e `unheard` (o ponto do nao ouvido). | Partial<Record<"bar" | "error" | "indicator" | "play" | "rate" | "seek" | "thumb" | "time" | "track" | "unheard", string>> | sem padrão |
defaultRateA velocidade inicial, sem controlar. | number | sem padrão |
disabledDesliga tocar, buscar e velocidade. | 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 |
labelsOs textos da peca, para trocar o idioma. | Partial<AudioPlayerLabels> | sem padrão |
metaO que vai a direita da duracao em `variant="bubble"`: a hora e os tiques da mensagem. | ReactNode | sem padrão |
onEndedChegou ao fim. | (() => void) | sem padrão |
onErrorO arquivo nao carregou. | ((error: MediaError | null) => void) | sem padrão |
onHeardChamado uma vez, quando um audio `unheard` comeca a tocar. | (() => 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 |
peaksA forma de onda, um numero por trecho, em qualquer escala: a peca divide pelo maior. | readonly number[] | 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 |
sequenceO grupo do `useAudioSequence`. | AudioSequence | sem padrão |
unheardO audio ainda nao foi ouvido: um ponto de acento ao lado da duracao, com o texto falado "Não ouvido". | boolean | false |
variantO desenho. | "bubble" | "plain" | "plain" |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.