BroadRouter

Registrare audio nel browser e inviarlo a un’API speech-to-text

A cura del team di BroadNet Inference · 6 min di lettura · Pubblicato

Registra con getUserMedia e MediaRecorder, scegli il formato con isTypeSupported e scarta i chunk vuoti. Se l’API accetta solo WAV o MP3, decodifica la registrazione nel browser e codificala in WAV mono a 16 kHz, oppure caricala e convertila con ffmpeg sul tuo server. In entrambi i casi passa dal tuo backend, così la chiave API non arriva mai al browser.

Registrare un messaggio vocale in una web app richiede una trentina di righe di JavaScript. I problemi iniziano quando invii il file: il browser ha registrato WebM o MP4, l’API vuole altro, un iPhone restituisce «Thank you» per una clip silenziosa, e il tutorial che hai copiato mette la chiave API nella pagina. Questo articolo costruisce l’intero percorso e testa ogni pezzo: registrazione, conversione in WAV, controllo della dimensione e inoltro tramite un piccolo server.

Gli esempi puntano a un’API che accetta solo WAV o MP3. BroadNet Inference è una di queste: la sua documentazione indica WAV (audio/wav) o MP3 (audio/mpeg) fino a 26.214.400 byte per file. Se la tua API accetta WebM, salta la conversione e tieni il resto. La guida speech-to-text di OpenAI elenca flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav e webm, fino a 25 MB.

Che formato registra il browser?

MediaRecorder registra in un formato compresso scelto dal browser, a meno che tu non ne chieda uno supportato. Chiedilo con MediaRecorder.isTypeSupported() e prendi la prima corrispondenza:

Stringa del tipo Browser tipico
audio/webm;codecs=opus Chrome, Edge, Firefox
audio/mp4 Safari (WebKit documenta MP4 con AAC); nel nostro test lo ha indicato anche Chromium
audio/ogg;codecs=opus Firefox

In Chromium headless, il 2026-11-15, isTypeSupported ha restituito true per WebM/Opus e MP4 e false per Ogg/Opus. Considera la tabella un punto di partenza, non una promessa. MDN precisa che true significa che il browser può registrare quel tipo in linea di principio; la registrazione può comunque fallire se le risorse scarseggiano. Leggi sempre recorder.mimeType dopo averlo creato, ed etichetta l’upload con quello, non con quello che avevi chiesto.

Come si registra dal microfono?

Due regole del browser determinano il codice. Primo, getUserMedia esiste solo in un contesto sicuro: HTTPS, localhost o un URL file:. In HTTP semplice da un altro host, navigator.mediaDevices è undefined, quindi chiamarlo lancia un TypeError invece di chiedere il permesso. Secondo, l’utente deve concedere l’accesso, e un rifiuto solleva NotAllowedError. Gestisci entrambi i casi con un messaggio su cui l’utente possa agire.

// 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();
  });
}

Tre dettagli vengono da segnalazioni di bug reali:

  • Scarta i chunk vuoti. In una discussione sul forum di OpenAI dedicata a MediaRecorder su iPhone, uno sviluppatore ha scoperto che su iOS dataavailable scattava con dati vuoti, e filtrare quei chunk ha risolto. Un altro ha risolto lo stesso sintomo avviando con un timeslice, start(1000).
  • Ferma le tracce. Fermare il registratore non rilascia il microfono. Senza getTracks().forEach(t => t.stop()) il browser continua a mostrare l’indicatore di registrazione.
  • Non misurare la durata contando i chunk. MDN avverte che gli intervalli del timeslice non sono esatti e possono allungarsi quando Safari mette in pausa il microfono o Chrome su Android blocca lo schermo. Usa un tuo timer se mostri una durata o imponi un limite.

Come si converte la registrazione in WAV nel browser?

La Web Audio API sa decodificare qualunque cosa abbia registrato il browser. Due fatti tratti da MDN accorciano il lavoro: decodeAudioData funziona solo su un file completo, non su frammenti, quindi decodifica dopo stop(); e ricampiona l’audio decodificato alla frequenza di campionamento del suo contesto. Un OfflineAudioContext creato a 16.000 Hz restituisce quindi campioni a 16 kHz senza codice di ricampionamento aggiuntivo. Il suo costruttore accetta qualsiasi frequenza da 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" });
}

Perché 16 kHz mono: è l’impostazione usata nell’esempio ffmpeg di BroadNet stessa (-ar 16000 -ac 1), conserva la banda del parlato e occupa un terzo dei byte rispetto a 48 kHz. Lo stereo raddoppia la dimensione senza alcun vantaggio per una voce sola. Per i compromessi vedi frequenza di campionamento.

I calcoli sulla dimensione contano, perché il WAV non è compresso. 16.000 campioni al secondo da 2 byte ciascuno fanno 32.000 byte al secondo. Con l’intestazione da 44 byte, il limite di 26.214.400 byte di BroadNet contiene 819 secondi: circa 13 minuti e 39 secondi. Per durate maggiori, ferma la registrazione a un limite, oppure dividi sul server come in trascrivere file audio lunghi. Lo splitter audio scrive i comandi ffmpeg per te.

Convertire nel browser consuma CPU e memoria dell’utente, e l’intera clip decodificata resta in memoria come float a 32 bit. Per messaggi vocali di pochi minuti va bene. Per registrazioni lunghe, carica il file compresso e converti sul server.

Come si converte invece sul server?

Invia la registrazione compressa così com’è e lascia lavorare ffmpeg. Meno codice nella pagina, un upload più piccolo e lo stesso risultato:

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

Scrivi l’upload in un file temporaneo invece di passarlo a ffmpeg tramite pipe. I file MP4 possono avere l’indice alla fine, e ffmpeg non sempre riesce a leggerli da una pipe. La guida sui vocali WhatsApp usa lo stesso comando per i file .ogg.

Come si tiene la chiave API fuori dal browser?

Metti un piccolo endpoint tra la pagina e l’API. Riceve la registrazione, la converte se serve, controlla la dimensione, aggiunge la chiave da una variabile d’ambiente e la inoltra. Node 18 e successivi hanno fetch, FormData e Blob integrati, quindi non servono pacchetti:

// 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);

La pagina invia poi il WAV oppure la registrazione grezza:

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();

Punti da conservare quando lo adatti:

  • Invia sempre language. La documentazione di BroadNet avverte che altrimenti l’arabo può tornare traslitterato in caratteri latini. Usa ar con il modello arabo, oppure passa a broadnet/cohere-transcribe con il codice giusto per una delle sue 14 lingue.
  • Restituisci errori generici. La prima versione del nostro proxy di test rimandava indietro l’errore di ffmpeg, che conteneva un percorso di file del server. Il codice sopra restituisce invece «Could not read the recording.» (traduzione: impossibile leggere la registrazione).
  • Aggiungi autenticazione e rate limit prima del deploy. Altrimenti chiunque trovi /transcribe spende il tuo saldo. Sicurezza delle chiavi API LLM copre il resto, e le chiavi BroadNet si possono limitare con le allow-list di IP.
  • Rifiuta le clip quasi silenziose. Le segnalazioni sul forum di trascrizioni inventate come «Thank you» o «Bye» riguardano registrazioni silenziose o danneggiate. Controlla la durata (byte del WAV ÷ 32.000) e, se puoi, il livello del segnale prima di pagarla.

Come l’abbiamo testato?

Non abbiamo usato nessuna chiave BroadNet. Il 2026-11-15 abbiamo eseguito il codice sopra contro un mock locale di /v1/audio/transcriptions:

  1. Encoder in Node. encodeWav su un secondo di tono a 440 Hz con due campioni saturati ha prodotto 32.044 byte. Il modulo wave di Python l’ha letto come 1 canale, 16.000 Hz, campioni da 2 byte, 16.000 frame, e ffmpeg come pcm_s16le, 16000 Hz, mono. I campioni saturati sono usciti come 32767 e −32768.
  2. Percorso nel browser in Chromium. Playwright ha avviato Chromium headless con un microfono finto. startRecording ha registrato 3 secondi come audio/webm;codecs=opus (40.563 byte), e toWav16k li ha trasformati in un WAV da 96.044 byte: 3,0 secondi, 16 kHz, mono.
  3. Proxy. Sia il WAV sia il WebM grezzo hanno restituito 200. Il mock ha ricevuto ogni volta l’autenticazione Bearer, l’ID del modello arabo, language=ar e un file audio/wav mono a 16 kHz; ffmpeg ha convertito il WebM sul server. Un WAV da 26.214.401 byte ha ricevuto 413 senza alcuna chiamata a monte. Un corpo che non era audio ha ricevuto 400.
  4. Origine non sicura. Caricata dall’indirizzo LAN della macchina in HTTP semplice, la pagina ha riportato isSecureContext false e startRecording ha lanciato il nostro messaggio sull’HTTPS invece di un TypeError.

Non abbiamo testato Safari né Firefox, né una trascrizione reale. Prova su un iPhone vero prima di andare in produzione.

Quanto costa?

BroadNet fattura la trascrizione per minuto di audio: $0.0042 per Transcribe Arabic e $0.002 per il modello multilingue. Un’ora di messaggi vocali in arabo costa $0.25. Entrambi funzionano con il credito iniziale di $5, che copre circa 1,190 minuti di arabo. Per i tuoi volumi, usa il calcolatore dei costi speech-to-text. La guida all’acquisto di API speech-to-text in arabo confronta i provider.

Dove si colloca BroadNet Inference

BroadRouter è il sito di BroadNet. BroadNet Inference trascrive file caricati: WAV o MP3, una richiesta per file, con una risposta JSON che contiene il testo. Non documenta trascrizione dal vivo o in streaming, timestamp né etichette dei parlanti. Se la tua app deve mostrare le parole mentre l’utente parla, usa un provider con un’API vocale in streaming. Per messaggi vocali, note e moduli, dove l’utente registra e poi invia, il flusso di upload qui sopra è tutto ciò che serve. La configurazione è nella guida all’API speech-to-text in arabo, e il riferimento API elenca i campi. La sua informativa privacy dichiara che audio e trascrizioni non vengono conservati.

Domande frequenti

Posso inviare il file WebM di MediaRecorder direttamente a un’API speech-to-text?

Solo se l’API accetta WebM. L’endpoint di trascrizione di OpenAI elenca webm e mp4 tra i formati. BroadNet accetta solo WAV e MP3, quindi converti prima: nel browser con la Web Audio API, oppure sul server con ffmpeg -i in.webm -ar 16000 -ac 1 out.wav.

Perché getUserMedia dice che navigator.mediaDevices è undefined?

La pagina non è in un contesto sicuro. Secondo MDN getUserMedia funziona solo via HTTPS, su localhost o da URL file. In HTTP semplice da un altro host, navigator.mediaDevices non esiste. Servi la pagina in HTTPS; per lo sviluppo localhost va bene.

Quanto dura una registrazione WAV che sta in un upload da 25 MB?

Un WAV mono a 16 kHz e 16 bit occupa 32.000 byte al secondo più un’intestazione di 44 byte. Il limite di 26.214.400 byte di BroadNet contiene circa 819 secondi, cioè 13 minuti e 39 secondi. Con MP3 o una frequenza di campionamento più bassa ci sta di più; per audio più lunghi, dividili in parti.

Perché da una registrazione vuota su iPhone ottengo «Thank you» o «Bye»?

Alcuni sviluppatori sul forum di OpenAI segnalano brevi frasi inventate da registrazioni silenziose o danneggiate, e hanno ricondotto i casi iOS a chunk dataavailable vuoti; filtrare i chunk di dimensione 0 e avviare il registratore con un timeslice ha risolto il problema. Controlla la durata prima dell’upload.

Il browser deve chiamare direttamente l’API di trascrizione?

No. Qualsiasi cosa nel codice frontend, chiave API compresa, è leggibile dall’utente. Invia l’audio a un tuo endpoint, che controlla dimensione e tipo, aggiunge la chiave da una variabile d’ambiente e lo inoltra.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity