BroadRouter

浏览器录音并发送到语音转文字 API

BroadNet Inference 团队 · 阅读约 6 分钟 · 发布于

用 getUserMedia 和 MediaRecorder 录音,用 isTypeSupported 选格式,并丢弃空数据块。如果 API 只接受 WAV 或 MP3,就在浏览器里解码录音并编码为 16 kHz 单声道 WAV,或者上传后在服务端用 ffmpeg 转换。无论哪种方式,都通过你自己的后端发送,API 密钥永远不进浏览器。

在网页应用里录一段语音,大约只要三十行 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 进行了测试:

  1. 在 Node 中测试编码器。 对一段 1 秒、440 Hz、含两个削波采样的正弦音调运行 encodeWav,得到 32,044 字节。Python 的 wave 模块读出 1 个声道、16,000 Hz、2 字节采样、16,000 帧;ffmpeg 识别为 pcm_s16le, 16000 Hz, mono。削波采样输出为 32767 和 −32768。
  2. 在 Chromium 中测试浏览器链路。 Playwright 启动带虚拟麦克风的无头 Chromium。startRecording 以 audio/webm;codecs=opus 录制了 3 秒(40,563 字节),toWav16k 将其转为 96,044 字节的 WAV:3.0 秒、16 kHz、单声道。
  3. 代理。 WAV 和原始 WebM 都返回 200。模拟服务每次都收到了 Bearer 认证、阿拉伯语模型 ID、language=ar 和一个 16 kHz 单声道 audio/wav 文件;WebM 由服务端的 ffmpeg 转换。26,214,401 字节的 WAV 得到 413,没有调用上游。非音频的请求体得到 400。
  4. 非安全来源。 通过本机局域网地址以普通 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 参考。其隐私声明表示不保留音频和转写文本。

常见问题

MediaRecorder 录出来的 WebM 能直接发给语音转文字 API 吗?

只有 API 接受 WebM 时才行。OpenAI 的转写端点在支持格式中列出了 webm 和 mp4。BroadNet 只接受 WAV 和 MP3,所以要先转换:在浏览器里用 Web Audio API,或在服务端用 ffmpeg -i in.webm -ar 16000 -ac 1 out.wav。

为什么 getUserMedia 报 navigator.mediaDevices 是 undefined?

因为页面不是安全上下文。MDN 说明 getUserMedia 只能在 HTTPS、localhost 或 file URL 下使用。从其他主机通过普通 HTTP 访问时,navigator.mediaDevices 根本不存在。请用 HTTPS 提供页面;开发时用 localhost 即可。

25 MB 的上传限制能装多长的 WAV 录音?

16 kHz 单声道 16 位 WAV 每秒 32,000 字节,外加 44 字节文件头。BroadNet 的 26,214,400 字节上限约能容纳 819 秒,也就是 13 分 39 秒。MP3 或更低采样率能装更多;更长的音频请切成几段。

为什么 iPhone 上空录音会转写出“Thank you”或“Bye”?

OpenAI 论坛上的开发者反馈,静音或损坏的录音会被转写出简短的虚构句子,并把 iOS 上的问题追溯到空的 dataavailable 数据块;过滤掉 size 为 0 的块、并用 timeslice 启动录音后问题解决。上传前先检查时长。

浏览器应该直接调用转写 API 吗?

不应该。前端代码里的任何东西,包括 API 密钥,用户都能看到。把音频 POST 到你自己的端点,由它检查大小和类型、从环境变量读取密钥,再转发出去。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity