Pular para o conteúdo
Formulário

AudioRecorder

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

Gravar e mandar uma mensagem de voz

Ouvir antes de mandar

Nada gravado ainda.

Escolher o microfone quando há mais de um

Importar
import { AudioRecorder } from '@rivocode/ui/audio'

Quando usar

O gravador de áudio: pedir o microfone, gravar vendo o nível ao vivo e o tempo decorrido, pausar e continuar, parar, descartar, e entregar o arquivo pronto. É o par do AudioPlayer, e o uso típico é a mensagem de voz numa conversa: gravar, ouvir se quiser, mandar. Vive em @rivocode/ui/audio, o mesmo caminho sem peer do player.

import { AudioRecorder } from '@rivocode/ui/audio'

<AudioRecorder
  maxDuration={120}
  onComplete={({ blob, duration, peaks }) => enviarVoz({ blob, duration, peaks })}
  aria-label="Gravar mensagem de voz"
/>

A peça é um grupo nomeado: sem aria-label, o nome é "Gravador de áudio". Ela guarda tudo que a gravação precisa (o MediaRecorder, o microfone aberto, o medidor), e você só recebe o resultado.

O que sai no fim

onComplete recebe a gravação quando a pessoa para, ou quando o maxDuration chega:

Campo O que é
blob o arquivo, para subir com FormData ou tocar com URL.createObjectURL
mimeType o formato que o navegador gravou: audio/webm;codecs=opus no Chrome, no Edge e no Firefox, audio/mp4 no Safari
duration os segundos gravados, sem contar as pausas
peaks os picos de 0 a 1, um por barra, prontos para o peaks do AudioPlayer

Mande a duration e os peaks junto com o arquivo. O WebM que o Chrome grava não traz a duração no cabeçalho, e o <audio> diz "infinito" até tocar até o fim: com a duration da gravação, o AudioPlayer mostra o total e libera a busca na hora. Os peaks saem de graça, do mesmo medidor que a pessoa viu enquanto gravava, sem decodificar o arquivo de novo como o audioPeaks faria. São 48, sem bars.

O formato sai do que o navegador grava, nessa ordem: audio/webm;codecs=opus, audio/mp4, audio/ogg;codecs=opus. mimeType pede outro, e vale se o navegador souber gravar nele.

Para mandar a gravação a outro serviço, converta no servidor. O que o navegador grava serve para tocar no próprio navegador, e não é garantia de arquivo aceito fora dele. O caso medido: pedindo audio/mp4, o Chrome responde "sim" no MediaRecorder.isTypeSupported e grava MP4 fragmentado (caixas moof e mdat); o WhatsApp aceita o envio do arquivo e falha na entrega, com "Media upload error". A biblioteca não tem como consertar isso no navegador: quem envia converte no servidor para o formato que o destino pede, como ffmpeg -i gravacao.webm -c:a libopus gravacao.ogg para OGG com Opus.

Os momentos

data-state O que a pessoa vê
idle o microfone para gravar, o medidor apagado e 0:00
requesting o giro no lugar do microfone, enquanto o navegador pergunta pela permissão; o botão vira "Pedindo acesso ao microfone", anuncia aria-busy e recusa o segundo toque
recording o parar no lugar do microfone, o medidor aceso, o ponto vermelho, o tempo correndo, o pausar e o descartar
paused o medidor apagado, o tempo parado, e o pausar vira "Continuar a gravação"
stopped a gravação num AudioPlayer, para ouvir antes de mandar, e o descartar
error a frase do que houve, com a saída escrita nela, e o "Tentar de novo"

Cada mudança é anunciada numa região viva: "Gravando", "Gravação pausada", "Gravação pronta, 12 segundos". O tempo na tela fica escondido do leitor de tela, que lê a versão por extenso ("12 segundos"), e não "0:12".

Sem revisão. Com review={false}, parar entrega e a peça volta a ficar pronta para gravar, sem o player: é o desenho do chat que manda a voz assim que a pessoa solta o botão. Com a revisão, quem manda é você, com o onComplete já em mãos; descartar chama o onDiscard e volta ao começo. Para voltar ao começo depois de mandar, troque a key da peça.

Pausar aparece quando o navegador sabe pausar o MediaRecorder (todos os atuais sabem); pausable={false} tira. Descartar no meio fecha o microfone e não entrega nada. Sair da tela no meio da gravação também fecha o microfone, e a gravação some sem onComplete.

Os erros, e a saída de cada um

Motivo A frase A saída
denied Sem permissão para usar o microfone. Libere o acesso nas configurações e tente de novo. "Tentar de novo" pede outra vez. Se a pessoa bloqueou de vez, o navegador responde não sem perguntar, e a frase diz onde liberar
no-device Nenhum microfone encontrado. Conecte um e tente de novo. "Tentar de novo", depois de conectar
failed Não foi possível usar o microfone. Feche outro app que esteja gravando e tente de novo. "Tentar de novo"; é o caso do microfone ocupado por outra chamada
unsupported Este navegador não grava áudio. Abra a página num navegador atualizado, como Chrome, Edge, Firefox ou Safari. não há botão: tentar de novo não muda o navegador. Também aparece fora do HTTPS, onde o navegador esconde o microfone

onError recebe o motivo e o que o navegador lançou, para o seu registro, e onRetry é chamado antes de pedir de novo.

O medidor, e o movimento reduzido

O medidor lê o microfone pelo Web Audio (AnalyserNode) 25 vezes por segundo: cada barra é o pico de um instante, a mais nova entra pela direita e as velhas saem pela esquerda, na mesma cor fg da onda tocada do player.

Com "reduzir movimento" ligado no sistema, o medidor para de correr. Uma onda que anda sem parar é exatamente o movimento que essa preferência pede para tirar, e ela continua necessária: é por ela que a pessoa sabe que o microfone está captando. Então o medidor vira cinco degraus parados, que acendem conforme o nível mais alto do último meio segundo e só mudam duas vezes por segundo, e o ponto vermelho para de pulsar. Os degraus acesos são fg e os apagados border-disabled, o mesmo par medido a 3:1 da onda do player. Os peaks entregues são os mesmos nos dois modos.

O microfone

Sem deviceId, grava o microfone padrão do sistema. A peça não desenha um seletor: ela enumera os microfones e entrega a lista por onInputsChange, e você põe o Select ao lado só quando há mais de um.

const [inputs, setInputs] = useState<AudioInput[]>([])
const [deviceId, setDeviceId] = useState<string>()

<AudioRecorder deviceId={deviceId} onInputsChange={setInputs} />
{inputs.length > 1 && (
  <Select
    items={inputs.map((input) => ({ label: input.label, value: input.deviceId }))}
    value={deviceId ?? inputs[0].deviceId}
    onValueChange={(next) => setDeviceId(next as string)}
  >
    <SelectTrigger aria-label="Microfone"><SelectValue /></SelectTrigger>
    <SelectContent>
      {inputs.map((input) => (
        <SelectItem key={input.deviceId} value={input.deviceId}>{input.label}</SelectItem>
      ))}
    </SelectContent>
  </Select>
)}

Foi medido: o Select dentro da peça levava o @rivocode/ui/audio de 9,9 para 19,4 KB em gzip, e quem grava mensagem de voz quase nunca troca de microfone. A lista só chega depois da primeira permissão: antes dela o navegador não diz o nome de nenhum microfone, e a peça não entrega lista sem nome. Ela chega de novo quando um microfone é ligado ou desligado. Os apelidos do sistema (default, communications) ficam de fora, porque repetem um dos microfones da lista.

Partes

classNames alcança record (o botão de gravar, e o de tentar de novo no erro), stop, pause (o de pausar e o de continuar), discard, meter, bar (cada barra, ou cada degrau com movimento reduzido), time, player (o AudioPlayer da revisão) e error. labels troca os textos: recorder, record, requesting, recording, pause, resume, paused, stop, done, discard, recordingPlayer, microphone, retry, settings (só no nativo), unsupported, denied, noDevice e failed.

Quando não usar

  • Tocar um áudio que já existe é AudioPlayer. O AudioRecorder produz o arquivo; o player toca, e é ele que aparece na revisão.
  • Transformar fala em texto é o dictation do PromptInput. O ditado escreve no campo e não guarda som nenhum; o gravador guarda o som e não sabe o que foi dito.
  • Anexar um áudio gravado antes é FileUpload com accept="audio/*". O gravador abre o microfone agora; o anexo escolhe um arquivo que já existe.
  • Chamada de voz ou transmissão ao vivo não é gravação: o som sai enquanto se fala, por WebRTC, e não vira arquivo no fim.

No React Native

Traduz, no mesmo caminho do player, @rivocode/ui-native/audio, atrás do expo-audio (peer opcional, npx expo install expo-audio). O app precisa da permissão do microfone no app.json: o plugin do expo-audio com microphonePermission, a frase que o iOS mostra ao pedir.

A API é a do web: onComplete, onStart, onDiscard, onError, onRetry, maxDuration, pausable, review, bars, deviceId, onInputsChange, disabled, labels e classNames, com os mesmos nomes de parte. Duas diferenças: o onComplete entrega a uri do arquivo que o expo-audio escreveu (no cache do app), com a duration e os peaks, e não um Blob; e no lugar do mimeType há options, as RecordingOptions do expo-audio por cima do RecordingPresets.HIGH_QUALITY (.m4a).

O medidor é o do aparelho. O expo-audio não dá as amostras do microfone, mas dá o nível de entrada em dB (metering, ligado pela peça com isMeteringEnabled), lido 20 vezes por segundo e levado de -60 a 0 dB para 0 a 1. É dele que saem as barras e os peaks. Com reduzir movimento, são os mesmos cinco degraus parados do web.

Permissão negada de vez tem saída. No celular o sistema só pergunta uma vez: quando o expo-audio responde que não pode perguntar de novo, o "Tentar de novo" vira "Abrir os ajustes" (labels.settings), que abre a tela do app nos ajustes do sistema. As entradas vêm de getAvailableInputs (o microfone do aparelho, o fone com fio, o Bluetooth), com o uid no deviceId. Depois de parar, a peça devolve o modo de áudio a allowsRecording: false, senão o iOS toca a revisão baixinho, pelo alto-falante de ouvido.

No iOS e no Android. O pedido do microfone é o do sistema, com o texto que o app declara no app.json. Recusado de vez, a peça oferece abrir os Ajustes nos dois.

API

PropTipoPadrão
bars

Quantas barras o medidor desenha, e quantos `peaks` a gravacao entrega.

numbersem padrão
classNames

Classe por parte: `record` (o botao de gravar, e o de tentar de novo no erro), `stop`, `pause` (o de pausar e o de continuar), `discard`, `meter`, `bar` (cada barra, ou cada degrau com movimento reduzido), `time`, `player` (o `AudioPlayer` da revisao) e `error`.

Partial<Record<"bar" | "discard" | "error" | "meter" | "pause" | "player" | "record" | "stop" | "time", string>>sem padrão
deviceId

O microfone, pelo `deviceId` do navegador.

stringsem padrão
disabled

Desliga gravar, pausar, parar e descartar.

booleanfalse
labels

Os textos da peca, para trocar o idioma.

Partial<AudioRecorderLabels>sem padrão
maxDuration

O teto em segundos.

numbersem padrão
mimeType

O formato do arquivo, se o navegador aceitar.

stringsem padrão
onComplete

A gravacao pronta, quando a pessoa para (ou o `maxDuration` chega): o `Blob`, o tipo dele, a duracao em segundos e os `peaks` ja calculados do nivel do microfone, para o `AudioPlayer` desenhar a onda sem decodificar.

((recording: AudioRecording) => void)sem padrão
onDiscard

A pessoa descartou: no meio da gravacao ou na revisao.

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

Nao deu para gravar.

((failure: AudioRecorderFailure, error: unknown) => void)sem padrão
onInputsChange

Os microfones que o navegador conhece, ja com nome: chega depois da primeira permissao e de novo quando um e ligado ou desligado.

((inputs: AudioInput[]) => void)sem padrão
onRetry

Chamado no "Tentar de novo", antes de a peca pedir o microfone outra vez.

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

O microfone abriu e a gravacao comecou de fato, depois da permissao.

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

Mostra o pausar e continuar quando o navegador sabe pausar.

booleantrue
review

Depois de parar, mostra a gravacao num `AudioPlayer` com o descartar, ate a pessoa descartar.

booleantrue

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.