Pular para o conteúdo
Dados

AudioPlayer

/componentes/audio-player.mdmarkdown cru, para quem lê com agent em vez de olho

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

Importar
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. O Progress anda sozinho até terminar e ninguém o arrasta; a busca do AudioPlayer é um controle, e a pessoa decide onde ela está.
  • Escolher um valor (volume de um alerta, uma faixa de preço) é Slider. O Slider guarda 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

PropTipoPadrão
srcobrigatória

O endereco do arquivo: o mesmo `src` do `<audio>`, inclusive `blob:` e `data:`.

stringsem padrão
bars

Quantas barras a onda desenha.

numbersem padrão
classNames

Classe 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
defaultRate

A velocidade inicial, sem controlar.

numbersem padrão
disabled

Desliga tocar, buscar e velocidade.

booleanfalse
duration

A duracao em segundos, quando ja e conhecida: aparece antes de o arquivo carregar e libera a busca sem esperar os metadados.

numbersem padrão
labels

Os textos da peca, para trocar o idioma.

Partial<AudioPlayerLabels>sem padrão
meta

O que vai a direita da duracao em `variant="bubble"`: a hora e os tiques da mensagem.

ReactNodesem padrão
onEnded

Chegou ao fim.

(() => void)sem padrão
onError

O arquivo nao carregou.

((error: MediaError | null) => void)sem padrão
onHeard

Chamado uma vez, quando um audio `unheard` comeca a tocar.

(() => void)sem padrão
onPause

Pausou, pelo botao ou pelo sistema.

(() => void)sem padrão
onPlay

Comecou a tocar de fato, depois da espera.

(() => void)sem padrão
onRateChange

A velocidade nova, a cada toque no botao de velocidade.

((rate: number) => void)sem padrão
onRetry

Chamado no "Tentar de novo", antes de a peca recarregar o arquivo.

(() => void)sem padrão
peaks

A forma de onda, um numero por trecho, em qualquer escala: a peca divide pelo maior.

readonly number[]sem padrão
preload

O quanto o navegador baixa antes do toque.

"auto""metadata""none""metadata"
rate

A velocidade controlada.

numbersem padrão
rates

As velocidades que o botao percorre, em ordem.

readonly number[]sem padrão
sequence

O grupo do `useAudioSequence`.

AudioSequencesem padrão
unheard

O audio ainda nao foi ouvido: um ponto de acento ao lado da duracao, com o texto falado "Não ouvido".

booleanfalse
variant

O desenho.

"bubble" | "plain""plain"

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.