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
dataavailabledisparava 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. Usearcom o modelo de árabe, ou troque parabroadnet/cohere-transcribee 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
/transcribegasta 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:
- Encoder no Node.
encodeWavsobre um segundo de tom de 440 Hz com duas amostras saturadas gerou 32.044 bytes. O módulowavedo Python leu o arquivo como 1 canal, 16.000 Hz, amostras de 2 bytes, 16.000 frames, e o ffmpeg comopcm_s16le, 16000 Hz, mono. As amostras saturadas saíram como 32767 e −32768. - Caminho do navegador no Chromium. O Playwright abriu o Chromium headless com um microfone falso.
startRecordinggravou 3 segundos comoaudio/webm;codecs=opus(40.563 bytes), etoWav16ktransformou isso em um WAV de 96.044 bytes: 3,0 segundos, 16 kHz, mono. - 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=are um arquivoaudio/wavmono 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. - Origem insegura. Carregada pelo endereço de rede local da máquina em HTTP simples, a página reportou
isSecureContextfalse, estartRecordinglançou a nossa mensagem sobre HTTPS em vez de umTypeError.
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.
