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
dataavailablescattava 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. Usaarcon il modello arabo, oppure passa abroadnet/cohere-transcribecon 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
/transcribespende 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:
- Encoder in Node.
encodeWavsu un secondo di tono a 440 Hz con due campioni saturati ha prodotto 32.044 byte. Il modulowavedi Python l’ha letto come 1 canale, 16.000 Hz, campioni da 2 byte, 16.000 frame, e ffmpeg comepcm_s16le, 16000 Hz, mono. I campioni saturati sono usciti come 32767 e −32768. - Percorso nel browser in Chromium. Playwright ha avviato Chromium headless con un microfono finto.
startRecordingha registrato 3 secondi comeaudio/webm;codecs=opus(40.563 byte), etoWav16kli ha trasformati in un WAV da 96.044 byte: 3,0 secondi, 16 kHz, mono. - 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=are un fileaudio/wavmono 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. - Origine non sicura. Caricata dall’indirizzo LAN della macchina in HTTP semplice, la pagina ha riportato
isSecureContextfalse estartRecordingha lanciato il nostro messaggio sull’HTTPS invece di unTypeError.
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.
