BroadRouter

브라우저에서 녹음한 오디오를 음성 인식(STT) API로 보내는 방법

BroadNet Inference 팀 · 6분 분량 · 게시

getUserMedia와 MediaRecorder로 녹음하고, isTypeSupported로 형식을 고르고, 빈 청크는 버리세요. API가 WAV나 MP3만 받는다면 브라우저에서 녹음을 디코딩해 16kHz 모노 WAV로 인코딩하거나, 업로드한 뒤 서버에서 ffmpeg로 변환하세요. 어느 쪽이든 자체 백엔드를 거쳐 보내야 API 키가 브라우저에 노출되지 않습니다.

웹 앱에서 음성 메시지를 녹음하는 데는 JavaScript 30줄 정도면 됩니다. 문제는 파일을 보낼 때 시작됩니다. 브라우저는 WebM이나 MP4로 녹음했는데 API는 다른 형식을 원하고, 아이폰은 무음 클립에 “Thank you”를 돌려주고, 복사해 온 튜토리얼은 API 키를 페이지에 넣어 둡니다. 이 글은 녹음, WAV 변환, 크기 확인, 작은 서버를 통한 전달까지 전체 경로를 만들고 각 단계를 테스트합니다.

예제는 WAV나 MP3만 받는 API를 대상으로 합니다. BroadNet Inference가 그런 API로, 문서에는 파일당 최대 26,214,400바이트의 WAV(audio/wav) 또는 MP3(audio/mpeg)가 명시되어 있습니다. 사용하는 API가 WebM을 받는다면 변환 단계는 건너뛰고 나머지만 쓰세요. OpenAI의 음성 텍스트 변환 가이드는 flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm을 최대 25MB까지 지원한다고 밝힙니다.

브라우저는 어떤 형식으로 녹음하나요?

MediaRecorder는 지원되는 형식을 따로 요청하지 않으면 브라우저가 고른 압축 형식으로 녹음합니다. MediaRecorder.isTypeSupported()로 물어보고 처음 일치하는 형식을 쓰세요.

형식 문자열 일반적인 브라우저
audio/webm;codecs=opus Chrome, Edge, Firefox
audio/mp4 Safari(WebKit 문서: AAC를 담은 MP4), 저희 테스트에서는 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();
  });
}

이 코드의 세 가지 세부 사항은 실제 버그 보고에서 나왔습니다.

  • 빈 청크를 버리세요. 아이폰의 MediaRecorder에 관한 OpenAI 포럼 스레드에서 한 개발자는 iOS에서 dataavailable이 빈 데이터로 발생한다는 것을 발견했고, 그 청크를 걸러내 문제를 해결했습니다. 다른 개발자는 timeslice를 지정해 start(1000)으로 시작해 같은 증상을 고쳤습니다.
  • 트랙을 멈추세요. 레코더를 멈춰도 마이크는 해제되지 않습니다. getTracks().forEach(t => t.stop())이 없으면 브라우저는 녹음 표시를 계속 보여 줍니다.
  • 청크 개수로 녹음 시간을 재지 마세요. MDN은 timeslice 간격이 정확하지 않으며, Safari가 마이크를 일시 중지하거나 Android Chrome에서 화면이 잠기면 늘어날 수 있다고 경고합니다. 길이를 표시하거나 제한을 두려면 자체 타이머를 쓰세요.

브라우저에서 녹음을 WAV로 변환하려면 어떻게 하나요?

Web Audio API는 브라우저가 녹음한 형식이면 무엇이든 디코딩할 수 있습니다. MDN의 두 가지 사실 덕분에 코드가 짧아집니다. decodeAudioData는 조각이 아니라 완전한 파일에서만 동작하므로 stop() 뒤에 디코딩해야 하고, 디코딩한 오디오를 컨텍스트의 샘플레이트로 리샘플링합니다. 따라서 16,000Hz로 만든 OfflineAudioContext는 별도의 리샘플링 코드 없이 16kHz 샘플을 돌려줍니다. 생성자는 3,000~768,000Hz의 모든 샘플레이트를 받습니다.

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" });
}

16kHz 모노를 쓰는 이유는 다음과 같습니다. BroadNet의 ffmpeg 예제가 쓰는 설정(-ar 16000 -ac 1)이고, 음성 대역을 유지하며, 48kHz의 3분의 1 바이트입니다. 스테레오는 목소리 하나에는 이득 없이 크기만 두 배로 늘립니다. 장단점은 샘플레이트를 참고하세요.

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초짜리 440Hz 톤에 encodeWav를 실행하자 32,044바이트가 나왔습니다. Python wave 모듈은 이를 채널 1개, 16,000Hz, 2바이트 샘플, 16,000프레임으로 읽었고, ffmpeg는 pcm_s16le, 16000 Hz, mono로 읽었습니다. 클리핑된 샘플은 32767과 −32768로 나왔습니다.
  2. Chromium에서 브라우저 경로 테스트. Playwright로 가짜 마이크를 단 헤드리스 Chromium을 실행했습니다. startRecording은 3초를 audio/webm;codecs=opus(40,563바이트)로 녹음했고, toWav16k는 이를 3.0초, 16kHz, 모노인 96,044바이트 WAV로 바꿨습니다.
  3. 프록시 테스트. WAV와 원본 WebM 모두 200을 반환했습니다. 모의 서버는 매번 Bearer 인증, 아랍어 모델 ID, language=ar, 16kHz 모노 audio/wav 파일을 받았고, WebM은 서버에서 ffmpeg가 변환했습니다. 26,214,401바이트 WAV는 업스트림 호출 없이 413을 받았습니다. 오디오가 아닌 본문은 400을 받았습니다.
  4. 안전하지 않은 출처 테스트. 머신의 LAN 주소에서 일반 HTTP로 불러오자 페이지는 isSecureContext를 false로 보고했고, startRecording은 TypeError 대신 저희가 작성한 HTTPS 메시지를 던졌습니다.

Safari, Firefox, 실제 전사는 테스트하지 않았습니다. 출시 전에 실제 아이폰으로 확인하세요.

비용은 얼마인가요?

BroadNet은 전사를 오디오 1분 단위로 과금합니다. Transcribe Arabic은 $0.0042 금액, 다국어 모델은 $0.002 금액입니다. 아랍어 음성 메시지 1시간은 $0.25 요금입니다. 두 모델 모두 $5 상당의 초기 크레딧으로 쓸 수 있으며, 아랍어 약 1,190분 분량입니다. 실제 사용량에 맞춘 계산은 음성 인식 비용 계산기를 쓰세요. 제공업체 비교는 아랍어 음성 인식 API 구매 가이드에 있습니다.

BroadNet Inference가 맞는 경우

BroadRouter는 BroadNet의 자체 웹사이트입니다. BroadNet Inference는 업로드한 파일을 전사합니다. WAV 또는 MP3를 파일당 요청 1개로 보내면 텍스트를 담은 JSON 응답이 옵니다. 실시간 또는 스트리밍 전사, 타임스탬프, 화자 레이블은 문서화되어 있지 않습니다. 사용자가 말하는 동안 단어가 나타나야 하는 앱이라면 스트리밍 음성 API를 제공하는 업체를 쓰세요. 사용자가 녹음한 뒤 보내는 음성 메시지, 메모, 양식에는 위의 업로드 흐름으로 충분합니다. 설정 방법은 아랍어 음성 인식 API 가이드에 있고, API 레퍼런스에 필드가 정리되어 있습니다. BroadNet의 개인정보 처리방침에 따르면 오디오와 전사본은 보관되지 않습니다.

자주 묻는 질문

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로 충분합니다.

25MB 업로드 한도에 WAV로 몇 분까지 녹음할 수 있나요?

16kHz 모노 16비트 WAV는 초당 32,000바이트에 44바이트 헤더가 더해집니다. BroadNet의 26,214,400바이트 상한에는 약 819초, 즉 13분 39초가 들어갑니다. MP3나 더 낮은 샘플레이트라면 더 길게 넣을 수 있으며, 더 긴 오디오는 여러 조각으로 나누세요.

아이폰에서 빈 녹음을 보냈는데 "Thank you"나 "Bye"가 나오는 이유는 무엇인가요?

OpenAI 포럼의 개발자들은 무음이거나 손상된 녹음에서 짧은 문구가 지어내어진다고 보고했고, iOS 사례의 원인을 빈 dataavailable 청크로 추적했습니다. 크기가 0인 청크를 걸러내고 timeslice를 지정해 녹음을 시작하자 해결되었다고 합니다. 업로드 전에 길이를 확인하세요.

브라우저에서 전사 API를 직접 호출해도 되나요?

안 됩니다. API 키를 포함해 프런트엔드 코드에 있는 것은 무엇이든 사용자가 읽을 수 있습니다. 오디오를 자체 엔드포인트로 보내고, 그 엔드포인트에서 크기와 형식을 확인한 뒤 환경 변수의 키를 붙여 전달하세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기