在网页应用里录一段语音,大约只要三十行 JavaScript。麻烦从发送文件开始:浏览器录的是 WebM 或 MP4,API 却要别的格式;iPhone 把一段静音转写成“Thank you”;而你照抄的教程把 API 密钥直接写进了页面。本文搭建完整链路并逐段测试:录音、转成 WAV、检查大小,再通过一个小服务端转发。
示例针对只接受 WAV 或 MP3 的 API。BroadNet Inference 就是其中之一:它的文档列出 WAV(audio/wav)或 MP3(audio/mpeg),每个文件最大 26,214,400 字节。如果你的 API 接受 WebM,跳过转换步骤,其余照用即可。OpenAI 的语音转文字指南列出 flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav 和 webm,最大 25 MB。
浏览器录出来的是什么格式?
MediaRecorder 会录制浏览器自选的压缩格式,除非你指定一个它支持的格式。用 MediaRecorder.isTypeSupported() 逐个询问,取第一个匹配项:
| 类型字符串 | 常见浏览器 |
|---|---|
audio/webm;codecs=opus |
Chrome、Edge、Firefox |
audio/mp4 |
Safari(WebKit 文档说明为 MP4 加 AAC);在我们的测试中 Chromium 也报告支持 |
audio/ogg;codecs=opus |
Firefox |
2026-11-15 在无头 Chromium 中,isTypeSupported 对 WebM/Opus 和 MP4 返回 true,对 Ogg/Opus 返回 false。请把这张表当作起点,而不是保证。MDN 指出,true 只表示浏览器原则上能录制该类型;资源不足时录制仍可能失败。创建录音器后务必读取 recorder.mimeType,并用它来标注上传文件,而不是用你请求的类型。
如何从麦克风录音?
两条浏览器规则决定了代码的写法。第一,getUserMedia 只存在于安全上下文中:HTTPS、localhost 或 file: URL。从其他主机通过普通 HTTP 访问时,navigator.mediaDevices 是 undefined,调用它会抛出 TypeError,而不是请求权限。第二,用户必须授权,拒绝时会抛出 NotAllowedError。两种情况都要给出用户能据此操作的提示。
// 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();
});
}
其中三个细节来自真实的 bug 报告:
- 丢弃空数据块。 在 OpenAI 论坛一个关于 iPhone 上 MediaRecorder 的帖子里,一位开发者发现 iOS 上
dataavailable会携带空数据触发,过滤掉这些块后问题解决。另一位开发者用 timeslice 启动录音(start(1000))解决了同样的症状。 - 停止音轨。 停止录音器并不会释放麦克风。不调用
getTracks().forEach(t => t.stop()),浏览器会一直显示录音指示。 - 不要靠数块数来计时。 MDN 提醒,timeslice 间隔并不精确,在 Safari 暂停麦克风或 Android Chrome 锁屏时还会被拉长。如果要显示时长或限制时长,请自己维护计时器。
如何在浏览器里把录音转成 WAV?
Web Audio API 能解码浏览器录制的任何格式。MDN 中的两点让这件事很简单:decodeAudioData 只能处理完整文件,不能处理片段,所以要在 stop() 之后解码;并且它会把解码后的音频重采样到所属上下文的采样率。因此,以 16,000 Hz 创建的 OfflineAudioContext 直接返回 16 kHz 的采样,不需要额外的重采样代码。它的构造函数接受 3,000 到 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" });
}
为什么选 16 kHz 单声道:这是 BroadNet 自己的 ffmpeg 示例使用的设置(-ar 16000 -ac 1),能保留语音频段,字节数只有 48 kHz 的三分之一。立体声会让体积翻倍,而对单人语音没有任何好处。取舍详见采样率。
体积计算很重要,因为 WAV 是未压缩的。每秒 16,000 个采样、每个 2 字节,即每秒 32,000 字节。加上 44 字节文件头,BroadNet 的 26,214,400 字节上限能容纳 819 秒,约 13 分 39 秒。更长的录音,要么到上限时停止录音,要么像转写长音频文件那样在服务端切分。音频切分工具会帮你写好 ffmpeg 命令。
在浏览器中转换会消耗用户的 CPU 和内存,整段解码后的音频以 32 位浮点数驻留在内存里。几分钟的语音消息没问题;长录音则应上传压缩文件,在服务端转换。
如何改在服务端转换?
把压缩录音原样发送,让 ffmpeg 来处理。页面代码更少,上传更小,结果一样:
ffmpeg -i in.webm -ar 16000 -ac 1 out.wav
把上传内容写入临时文件,而不是通过管道喂给 ffmpeg。MP4 文件可能把索引放在末尾,ffmpeg 从管道读取时不一定能读到。WhatsApp 语音消息指南对 .ogg 文件用的也是同一条命令。
如何让 API 密钥不进浏览器?
在页面和 API 之间放一个小端点。它接收录音,必要时转换,检查大小,从环境变量读取密钥并转发。Node 18 及以上版本内置了 fetch、FormData 和 Blob,所以不需要任何依赖包:
// 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);
页面随后发送 WAV 或原始录音:
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();
改写时值得保留的几点:
- 始终传
language。 BroadNet 的文档说明,否则阿拉伯语可能被音译成拉丁字母返回。阿拉伯语模型用ar,或者换成broadnet/cohere-transcribe,并为它支持的 14 种语言之一传入正确的代码。 - 返回笼统的错误信息。 我们测试代理的第一版直接回显了 ffmpeg 的错误,其中包含服务器上的文件路径。上面的代码改为返回 “Could not read the recording.”。
- 部署前加上认证和限流。 否则任何找到
/transcribe的人都能花你的余额。其余内容见 LLM API 密钥安全,BroadNet 的密钥还可以用 IP 白名单加以限制。 - 拒绝几乎无声的片段。 论坛上关于虚构出“Thank you”或“Bye”的报告,涉及的都是静音或损坏的录音。付费转写前先检查时长(WAV 字节数 ÷ 32,000),条件允许的话再检查信号电平。
我们是怎么测试的?
没有使用 BroadNet 密钥。2026-11-15,我们用上面的代码对一个本地模拟的 /v1/audio/transcriptions 进行了测试:
- 在 Node 中测试编码器。 对一段 1 秒、440 Hz、含两个削波采样的正弦音调运行
encodeWav,得到 32,044 字节。Python 的wave模块读出 1 个声道、16,000 Hz、2 字节采样、16,000 帧;ffmpeg 识别为pcm_s16le, 16000 Hz, mono。削波采样输出为 32767 和 −32768。 - 在 Chromium 中测试浏览器链路。 Playwright 启动带虚拟麦克风的无头 Chromium。
startRecording以audio/webm;codecs=opus录制了 3 秒(40,563 字节),toWav16k将其转为 96,044 字节的 WAV:3.0 秒、16 kHz、单声道。 - 代理。 WAV 和原始 WebM 都返回 200。模拟服务每次都收到了
Bearer认证、阿拉伯语模型 ID、language=ar和一个 16 kHz 单声道audio/wav文件;WebM 由服务端的 ffmpeg 转换。26,214,401 字节的 WAV 得到 413,没有调用上游。非音频的请求体得到 400。 - 非安全来源。 通过本机局域网地址以普通 HTTP 加载时,页面报告
isSecureContext为 false,startRecording抛出的是我们写的 HTTPS 提示,而不是TypeError。
我们没有测试 Safari 或 Firefox,也没有做真实转写。上线前请在真实 iPhone 上试一试。
费用是多少?
BroadNet 按音频分钟计费:Transcribe Arabic 为 $0.0042,多语言模型为 $0.002。一小时阿拉伯语语音消息为 $0.25。两者都可以用 $5 的初始额度,大约够转写 1,190 分钟阿拉伯语。按你自己的用量估算,请用语音转文字费用计算器。阿拉伯语语音转文字 API 选购指南对各家供应商做了比较。
BroadNet Inference 适合什么场景
BroadRouter 是 BroadNet 自己的网站。BroadNet Inference 转写上传的文件:WAV 或 MP3,每个文件一个请求,JSON 响应中包含文本。它的文档没有提供实时或流式转写、时间戳或说话人标签。如果你的应用需要在用户说话时就显示文字,请选择提供流式语音 API 的供应商。对于语音消息、笔记和表单这类先录完再发送的场景,上面的上传流程就够了。接入步骤见阿拉伯语语音转文字 API 指南,字段说明见 API 参考。其隐私声明表示不保留音频和转写文本。
