BroadRouter

Gravar áudio no navegador e enviar para uma API de speech-to-text

Pela equipe da BroadNet Inference · 6 min de leitura · Publicado em

Grave com getUserMedia e MediaRecorder, escolha o formato com isTypeSupported e descarte os chunks vazios. Se a API aceita só WAV ou MP3, decodifique a gravação no navegador e codifique em WAV mono de 16 kHz, ou faça o upload e converta com ffmpeg no seu servidor. Em qualquer caso, envie pelo seu backend, para que a chave de API nunca chegue ao navegador.

Gravar uma mensagem de voz em um web app leva umas trinta linhas de JavaScript. Os problemas começam quando você envia o arquivo: o navegador gravou WebM ou MP4, a API quer outra coisa, um iPhone devolve “Thank you” para um clipe silencioso, e o tutorial que você copiou coloca a chave de API na página. Este post monta o caminho inteiro e testa cada parte: gravar, converter para WAV, conferir o tamanho e encaminhar por um pequeno servidor.

Os exemplos miram uma API que aceita só WAV ou MP3. A BroadNet Inference é uma delas: a documentação lista WAV (audio/wav) ou MP3 (audio/mpeg) até 26.214.400 bytes por arquivo. Se a sua API aceita WebM, pule a conversão e mantenha o resto. O guia de speech-to-text da OpenAI lista flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav e webm, até 25 MB.

Em que formato o navegador grava?

O MediaRecorder grava em um formato comprimido escolhido pelo navegador, a menos que você peça um que ele suporte. Peça com MediaRecorder.isTypeSupported() e use o primeiro que bater:

String do tipo Navegador típico
audio/webm;codecs=opus Chrome, Edge, Firefox
audio/mp4 Safari (o WebKit documenta MP4 com AAC); o Chromium também o reportou no nosso teste
audio/ogg;codecs=opus Firefox

No Chromium headless, em 2026-11-15, isTypeSupported retornou true para WebM/Opus e MP4 e false para Ogg/Opus. Trate a tabela como ponto de partida, não como promessa. O MDN observa que true significa que o navegador consegue gravar o tipo em princípio; a gravação ainda pode falhar se faltarem recursos. Sempre leia recorder.mimeType depois de criá-lo e rotule o upload com esse valor, não com o que você pediu.

Como gravar a partir do microfone?

Duas regras do navegador definem o código. Primeiro, getUserMedia só existe em um contexto seguro: HTTPS, localhost ou uma URL file:. Em HTTP simples vindo de outro host, navigator.mediaDevices é undefined, então a chamada lança um TypeError em vez de pedir permissão. Segundo, o usuário precisa conceder acesso, e uma recusa gera NotAllowedError. Trate os dois casos com uma mensagem que o usuário consiga resolver.

// record.js: record from the microphone, return a 16 kHz mono WAV Blob.
const TYPES = ["audio/webm;codecs=opus", "audio/mp4", "audio/ogg;codecs=opus"];

export async function startRecording() {
  if (!navigator.mediaDevices?.getUserMedia) {
    throw new Error("Microphone access needs HTTPS (or localhost).");
  }
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const mimeType = TYPES.find((t) => MediaRecorder.isTypeSupported(t));
  const rec = new MediaRecorder(stream, mimeType ? { mimeType } : {});
  const chunks = [];
  rec.ondataavailable = (e) => { if (e.data.size > 0) chunks.push(e.data); };
  rec.start(1000); // a chunk every second, so a crash loses at most one second
  return () => new Promise((resolve) => {
    rec.onstop = () => {
      stream.getTracks().forEach((t) => t.stop()); // turn the mic indicator off
      resolve(new Blob(chunks, { type: rec.mimeType }));
    };
    rec.stop();
  });
}

Três detalhes desse código vêm de relatos de bugs reais:

  • Descarte chunks vazios. Em um tópico do fórum da OpenAI sobre MediaRecorder no iPhone, um desenvolvedor descobriu que no iOS o dataavailable disparava com dados vazios, e filtrar esses chunks resolveu. Outro resolveu o mesmo sintoma iniciando com um timeslice, start(1000).
  • Pare as faixas. Parar o gravador não libera o microfone. Sem getTracks().forEach(t => t.stop()), o navegador continua mostrando o indicador de gravação.
  • Não meça a gravação contando chunks. O MDN avisa que os intervalos do timeslice são inexatos e podem se alongar quando o Safari pausa o microfone ou o Chrome no Android bloqueia a tela. Use um timer próprio se você mostra a duração ou impõe um limite.

Como converter a gravação para WAV no navegador?

A Web Audio API consegue decodificar o que quer que o navegador tenha gravado. Dois fatos do MDN deixam isso curto: decodeAudioData só funciona com um arquivo completo, não com fragmentos, então decodifique depois de stop(); e ele reamostra o áudio decodificado para a taxa de amostragem do seu contexto. Um OfflineAudioContext criado a 16.000 Hz devolve, portanto, amostras de 16 kHz sem código extra de reamostragem. O construtor aceita qualquer taxa de 3.000 a 768.000 Hz.

export async function toWav16k(blob) {
  // decodeAudioData needs the whole file and resamples to the context's rate.
  const ctx = new OfflineAudioContext(1, 1, 16000);
  const audio = await ctx.decodeAudioData(await blob.arrayBuffer());
  return encodeWav(mixDown(audio), 16000);
}

export function mixDown(audio) {
  const out = new Float32Array(audio.length);
  for (let c = 0; c < audio.numberOfChannels; c++) {
    const ch = audio.getChannelData(c);
    for (let i = 0; i < out.length; i++) out[i] += ch[i] / audio.numberOfChannels;
  }
  return out;
}

export function encodeWav(samples, rate) {
  const buf = new ArrayBuffer(44 + samples.length * 2);
  const v = new DataView(buf);
  const str = (o, s) => [...s].forEach((ch, i) => v.setUint8(o + i, ch.charCodeAt(0)));
  str(0, "RIFF"); v.setUint32(4, 36 + samples.length * 2, true); str(8, "WAVE");
  str(12, "fmt "); v.setUint32(16, 16, true); v.setUint16(20, 1, true); // PCM
  v.setUint16(22, 1, true); v.setUint32(24, rate, true);                // mono
  v.setUint32(28, rate * 2, true); v.setUint16(32, 2, true); v.setUint16(34, 16, true);
  str(36, "data"); v.setUint32(40, samples.length * 2, true);
  for (let i = 0; i < samples.length; i++) {
    const s = Math.max(-1, Math.min(1, samples[i]));
    v.setInt16(44 + i * 2, s < 0 ? s * 0x8000 : s * 0x7fff, true);
  }
  return new Blob([buf], { type: "audio/wav" });
}

Por que 16 kHz mono: é a configuração do próprio exemplo de ffmpeg da BroadNet (-ar 16000 -ac 1), preserva a banda da fala e ocupa um terço dos bytes de 48 kHz. Estéreo dobra o tamanho sem ganho nenhum para uma única voz. Veja taxa de amostragem para os prós e contras.

A conta do tamanho importa, porque WAV não é comprimido. 16.000 amostras por segundo, com 2 bytes cada, dão 32.000 bytes por segundo. Com o cabeçalho de 44 bytes, o limite de 26.214.400 bytes da BroadNet comporta 819 segundos: cerca de 13 minutos e 39 segundos. Para algo mais longo, pare a gravação em um limite ou divida no servidor, como em transcrever arquivos de áudio longos. O divisor de áudio escreve os comandos do ffmpeg.

Converter no navegador gasta CPU e memória do usuário, e o clipe decodificado inteiro fica na memória como floats de 32 bits. Para mensagens de voz de poucos minutos, tudo bem. Para gravações longas, faça o upload do arquivo comprimido e converta no servidor.

Como converter no servidor?

Envie a gravação comprimida do jeito que está e deixe o ffmpeg trabalhar. Menos código na página, upload menor e o mesmo resultado:

ffmpeg -i in.webm -ar 16000 -ac 1 out.wav

Grave o upload em um arquivo temporário em vez de passá-lo ao ffmpeg por pipe. Arquivos MP4 podem guardar o índice no final, e o ffmpeg nem sempre consegue lê-los de um pipe. O guia de áudios do WhatsApp usa o mesmo comando para arquivos .ogg.

Como manter a chave de API fora do navegador?

Coloque um pequeno endpoint entre a página e a API. Ele recebe a gravação, converte se precisar, confere o tamanho, adiciona a chave a partir de uma variável de ambiente e encaminha. O Node 18 e versões posteriores têm fetch, FormData e Blob nativos, então não é preciso nenhum pacote:

// server.mjs: POST /transcribe with the recording as the body. The key stays here.
import http from "node:http";
import { execFile } from "node:child_process";
import { mkdtemp, writeFile, readFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { promisify } from "node:util";

const API = process.env.BROADNET_BASE_URL ?? "https://inference.broadnet.ai/v1";
const KEY = process.env.BROADNET_API_KEY;
const FFMPEG = process.env.FFMPEG ?? "ffmpeg";
const MAX = 26_214_400; // BroadNet's per-file cap in bytes
const run = promisify(execFile);

async function readBody(req, limit) {
  const parts = []; let n = 0;
  for await (const c of req) { n += c.length; if (n > limit) throw Object.assign(new Error("too large"), { code: 413 }); parts.push(c); }
  return Buffer.concat(parts);
}

async function toWav(bytes) {
  // Temp files, not pipes: an MP4 from Safari can keep its index at the end.
  const dir = await mkdtemp(join(tmpdir(), "rec-"));
  try {
    await writeFile(join(dir, "in"), bytes);
    await run(FFMPEG, ["-v", "error", "-i", join(dir, "in"), "-ar", "16000", "-ac", "1", join(dir, "out.wav")]);
    return await readFile(join(dir, "out.wav"));
  } finally { await rm(dir, { recursive: true, force: true }); }
}

http.createServer(async (req, res) => {
  const reply = (code, obj) => { res.writeHead(code, { "content-type": "application/json" }); res.end(JSON.stringify(obj)); };
  if (req.method !== "POST" || req.url !== "/transcribe") return reply(404, { error: "not found" });
  try {
    const type = (req.headers["content-type"] ?? "").split(";")[0];
    let body = await readBody(req, 4 * MAX);
    if (type !== "audio/wav" && type !== "audio/mpeg") {
      try { body = await toWav(body); }
      catch { return reply(400, { error: "Could not read the recording." }); }
    }
    if (body.length > MAX) return reply(413, { error: "Recording too long; split it first." });
    const form = new FormData();
    form.append("model", "broadnet/cohere-transcribe-arabic");
    form.append("language", "ar");
    form.append("file", new Blob([body], { type: type === "audio/mpeg" ? "audio/mpeg" : "audio/wav" }),
      type === "audio/mpeg" ? "audio.mp3" : "audio.wav");
    const r = await fetch(`${API}/audio/transcriptions`, {
      method: "POST", headers: { Authorization: `Bearer ${KEY}` }, body: form,
    });
    const data = await r.json();
    return r.ok ? reply(200, { text: data.text }) : reply(r.status, { error: data });
  } catch (e) {
    return reply(e.code === 413 ? 413 : 500, { error: String(e.message ?? e) });
  }
}).listen(process.env.PORT ?? 8787);

A página então envia o WAV ou a gravação bruta:

const stop = await startRecording();
// ...later, when the user taps Stop:
const raw = await stop();
const wav = await toWav16k(raw);          // or send `raw` and let the server convert
const r = await fetch("/transcribe", { method: "POST", headers: { "content-type": wav.type }, body: wav });
const { text } = await r.json();

Pontos que valem manter quando você adaptar:

  • Sempre envie language. A documentação da BroadNet avisa que, sem isso, o árabe pode voltar transliterado em letras latinas. Use ar com o modelo de árabe, ou troque para broadnet/cohere-transcribe e o código certo de um dos seus 14 idiomas.
  • Devolva erros genéricos. A primeira versão do nosso proxy de teste repassava o erro do ffmpeg, que incluía um caminho de arquivo do servidor. O código acima devolve “Could not read the recording.” (tradução: não foi possível ler a gravação) em vez disso.
  • Adicione autenticação e rate limit antes do deploy. Caso contrário, qualquer um que encontrar /transcribe gasta o seu saldo. Segurança de chaves de API de LLM cobre o resto, e as chaves da BroadNet podem ser restritas com listas de IPs permitidos.
  • Rejeite clipes quase silenciosos. Os relatos no fórum de transcrições inventadas como “Thank you” ou “Bye” envolvem gravações silenciosas ou corrompidas. Confira a duração (bytes do WAV ÷ 32.000) e, se puder, o nível do sinal antes de pagar por ela.

Como testamos isso?

Nenhuma chave da BroadNet foi usada. Em 2026-11-15 rodamos o código acima contra um mock local de /v1/audio/transcriptions:

  1. Encoder no Node. encodeWav sobre um segundo de tom de 440 Hz com duas amostras saturadas gerou 32.044 bytes. O módulo wave do Python leu o arquivo como 1 canal, 16.000 Hz, amostras de 2 bytes, 16.000 frames, e o ffmpeg como pcm_s16le, 16000 Hz, mono. As amostras saturadas saíram como 32767 e −32768.
  2. Caminho do navegador no Chromium. O Playwright abriu o Chromium headless com um microfone falso. startRecording gravou 3 segundos como audio/webm;codecs=opus (40.563 bytes), e toWav16k transformou isso em um WAV de 96.044 bytes: 3,0 segundos, 16 kHz, mono.
  3. Proxy. O WAV e o WebM bruto retornaram 200. O mock recebeu, em todas as vezes, autenticação Bearer, o ID do modelo de árabe, language=ar e um arquivo audio/wav mono de 16 kHz; o ffmpeg converteu o WebM no servidor. Um WAV de 26.214.401 bytes recebeu 413 sem nenhuma chamada upstream. Um corpo que não era áudio recebeu 400.
  4. Origem insegura. Carregada pelo endereço de rede local da máquina em HTTP simples, a página reportou isSecureContext false, e startRecording lançou a nossa mensagem sobre HTTPS em vez de um TypeError.

Não testamos Safari nem Firefox, nem uma transcrição real. Teste em um iPhone de verdade antes de publicar.

Quanto custa?

A BroadNet cobra a transcrição por minuto de áudio: $0.0042 pelo Transcribe Arabic e $0.002 pelo modelo multilíngue. Uma hora de mensagens de voz em árabe sai por $0.25. Os dois funcionam com o crédito inicial de $5, que cobre cerca de 1,190 minutos de árabe. Para os seus volumes, use a calculadora de custo de speech-to-text. O guia de compra de APIs de speech-to-text em árabe compara provedores.

Onde a BroadNet Inference se encaixa

O BroadRouter é o site da própria BroadNet. A BroadNet Inference transcreve arquivos enviados: WAV ou MP3, uma requisição por arquivo, com uma resposta JSON que traz o texto. Ela não documenta transcrição ao vivo ou em streaming, timestamps nem identificação de falantes. Se o seu app precisa mostrar as palavras enquanto o usuário fala, use um provedor com API de voz em streaming. Para mensagens de voz, anotações e formulários, em que o usuário grava e depois envia, o fluxo de upload acima é tudo de que você precisa. A configuração está no guia da API de speech-to-text em árabe, e a referência da API lista os campos. A declaração de privacidade dela diz que áudios e transcrições não são retidos.

Perguntas frequentes

Posso mandar o arquivo WebM do MediaRecorder direto para uma API de speech-to-text?

Só se a API aceitar WebM. O endpoint de transcrição da OpenAI lista webm e mp4 entre os formatos. A BroadNet aceita só WAV e MP3, então converta antes: no navegador com a Web Audio API, ou no servidor com ffmpeg -i in.webm -ar 16000 -ac 1 out.wav.

Por que o getUserMedia diz que navigator.mediaDevices é undefined?

A página não está em um contexto seguro. Segundo o MDN, getUserMedia só funciona via HTTPS, em localhost ou a partir de URLs file. Em HTTP simples vindo de outro host, navigator.mediaDevices não existe. Sirva a página em HTTPS; para desenvolvimento, localhost serve.

Quanto tempo de gravação em WAV cabe em um upload de 25 MB?

WAV mono de 16 kHz e 16 bits ocupa 32.000 bytes por segundo, mais um cabeçalho de 44 bytes. O limite de 26.214.400 bytes da BroadNet comporta cerca de 819 segundos, ou 13 minutos e 39 segundos. MP3 ou uma taxa de amostragem menor cabem mais; para áudios mais longos, divida em partes.

Por que recebo "Thank you" ou "Bye" de uma gravação vazia no iPhone?

Desenvolvedores no fórum da OpenAI relatam frases curtas inventadas a partir de gravações silenciosas ou corrompidas, e atribuíram os casos no iOS a chunks dataavailable vazios; filtrar os chunks de tamanho 0 e iniciar o gravador com um timeslice resolveu para eles. Confira a duração antes do upload.

O navegador deve chamar a API de transcrição diretamente?

Não. Tudo o que está no código do frontend, inclusive uma chave de API, pode ser lido pelo usuário. Envie o áudio para um endpoint seu, que confere tamanho e tipo, adiciona a chave a partir de uma variável de ambiente e encaminha.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity