# AudioRecorder

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.

```tsx
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.

```tsx
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.

## Importação

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

## Exemplos

### Gravar e mandar uma mensagem de voz

```tsx
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@rivocode/ui'
import { Message } from '@rivocode/ui/ai'
import { AudioPlayer, AudioRecorder, type AudioInput, type AudioRecording } from '@rivocode/ui/audio'
import { useEffect, useRef, useState } from 'react'

type Sent = AudioRecording & { id: number; url: string }

function useSentNotes() {
  const [sent, setSent] = useState<Sent[]>([])
  const urls = useRef<string[]>([])
  useEffect(() => () => urls.current.forEach((url) => URL.revokeObjectURL(url)), [])
  const send = (recording: AudioRecording) => {
    const url = URL.createObjectURL(recording.blob)
    urls.current.push(url)
    setSent((before) => [...before, { ...recording, id: Date.now(), url }])
  }
  return { sent, send }
}

export function VoiceMessage() {
  const { sent, send } = useSentNotes()

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      {sent.map((note) => (
        <Message key={note.id} variant="chat" role="user">
          <AudioPlayer
            src={note.url}
            peaks={note.peaks}
            duration={note.duration}
            aria-label="Sua mensagem de voz"
            className="w-64 max-w-full"
          />
        </Message>
      ))}
      <div className="rounded-lg border border-border bg-surface p-3">
        <AudioRecorder review={false} maxDuration={120} onComplete={send} aria-label="Gravar mensagem de voz" />
      </div>
    </div>
  )
}
```

### Ouvir antes de mandar

```tsx
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@rivocode/ui'
import { Message } from '@rivocode/ui/ai'
import { AudioPlayer, AudioRecorder, type AudioInput, type AudioRecording } from '@rivocode/ui/audio'
import { useEffect, useRef, useState } from 'react'

export function ReviewBeforeSending() {
  const [recording, setRecording] = useState<AudioRecording>()

  return (
    <div className="flex w-full max-w-lg flex-col gap-3 rounded-lg border border-border bg-surface p-4">
      <AudioRecorder
        onComplete={setRecording}
        onDiscard={() => setRecording(undefined)}
        aria-label="Gravar o recado"
      />
      <p className="text-sm text-fg-muted">
        {recording
          ? `${recording.duration.toFixed(1).replace('.', ',')} s em ${recording.mimeType || 'formato do navegador'}, ${recording.peaks.length} picos prontos.`
          : 'Nada gravado ainda.'}
      </p>
    </div>
  )
}
```

### Escolher o microfone quando há mais de um

```tsx
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@rivocode/ui'
import { Message } from '@rivocode/ui/ai'
import { AudioPlayer, AudioRecorder, type AudioInput, type AudioRecording } from '@rivocode/ui/audio'
import { useEffect, useRef, useState } from 'react'

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

  return (
    <div className="flex w-full max-w-lg flex-col gap-3 rounded-lg border border-border bg-surface p-4">
      <AudioRecorder deviceId={deviceId} onInputsChange={setInputs} aria-label="Gravar a narração" />
      {inputs.length > 1 && (
        <Select
          size="sm"
          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>
      )}
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `bars` | `number` |  |  | - | Quantas barras o medidor desenha, e quantos `peaks` a gravacao entrega. |
| `classNames` | `Partial<Record<"bar" \| "discard" \| "error" \| "meter" \| "pause" \| "player" \| "record" \| "stop" \| "time", string>>` |  |  | - | 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`. |
| `deviceId` | `string` |  |  | - | O microfone, pelo `deviceId` do navegador. |
| `disabled` | `boolean` |  | `false` | - | Desliga gravar, pausar, parar e descartar. |
| `labels` | `Partial<AudioRecorderLabels>` |  |  | - | Os textos da peca, para trocar o idioma. |
| `maxDuration` | `number` |  |  | - | O teto em segundos. |
| `mimeType` | `string` |  |  | - | O formato do arquivo, se o navegador aceitar. |
| `onComplete` | `((recording: AudioRecording) => void)` |  |  | - | 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. |
| `onDiscard` | `(() => void)` |  |  | - | A pessoa descartou: no meio da gravacao ou na revisao. |
| `onError` | `((failure: AudioRecorderFailure, error: unknown) => void)` |  |  | - | Nao deu para gravar. |
| `onInputsChange` | `((inputs: AudioInput[]) => void)` |  |  | - | Os microfones que o navegador conhece, ja com nome: chega depois da primeira permissao e de novo quando um e ligado ou desligado. |
| `onRetry` | `(() => void)` |  |  | - | Chamado no "Tentar de novo", antes de a peca pedir o microfone outra vez. |
| `onStart` | `(() => void)` |  |  | - | O microfone abriu e a gravacao comecou de fato, depois da permissao. |
| `pausable` | `boolean` |  | `true` | - | Mostra o pausar e continuar quando o navegador sabe pausar. |
| `review` | `boolean` |  | `true` | - | Depois de parar, mostra a gravacao num `AudioPlayer` com o descartar, ate a pessoa descartar. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [Autocomplete](/componentes/autocomplete.md)
- [Calendar](/componentes/calendar.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxCard](/componentes/checkbox-card.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [ColorPicker](/componentes/color-picker.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
