BroadRouter

تسجيل الصوت في المتصفح وإرساله إلى API لتحويل الصوت إلى نص

بقلم فريق BroadNet Inference · قراءة في 6 دقائق · تاريخ النشر

سجّل باستخدام getUserMedia وMediaRecorder، واختر الصيغة عبر isTypeSupported، وتجاهل الأجزاء الفارغة. وإذا كانت الواجهة لا تقبل إلا WAV أو MP3، ففكّ ترميز التسجيل في المتصفح وأنشئ ملف WAV أحادي القناة بتردد 16 kHz، أو ارفعه وحوّله بـ ffmpeg على خادمك. وفي الحالتين أرسله عبر الخادم الخلفي الخاص بك، حتى لا يصل مفتاح API إلى المتصفح أبدًا.

تسجيل رسالة صوتية في تطبيق ويب يحتاج إلى نحو ثلاثين سطرًا من JavaScript. أما المشكلات فتبدأ عند إرسال الملف: سجّل المتصفح بصيغة WebM أو MP4 والواجهة تريد صيغة أخرى، وجهاز iPhone يُرجع “Thank you” لمقطع صامت، والدرس الذي نسخته يضع مفتاح API في الصفحة. يبني هذا المقال المسار كاملًا ويختبر كل جزء منه: التسجيل، والتحويل إلى WAV، والتحقق من الحجم، والتمرير عبر خادم صغير.

تستهدف الأمثلة واجهة لا تقبل إلا WAV أو MP3. وBroadNet Inference واحدة منها: تذكر وثائقها WAV (audio/wav) أو MP3 (audio/mpeg) حتى 26,214,400 بايت لكل ملف. وإذا كانت واجهتك تقبل 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

في Chromium دون واجهة (headless) بتاريخ 2026-11-15، أعاد isTypeSupported القيمة true لـ WebM/Opus وMP4، والقيمة false لـ Ogg/Opus. اعتبر الجدول نقطة بداية لا وعدًا. فـ MDN تنبّه إلى أن true تعني أن المتصفح يستطيع تسجيل النوع من حيث المبدأ؛ وقد يفشل التسجيل مع ذلك إذا نفدت الموارد. اقرأ دائمًا recorder.mimeType بعد إنشاء المسجّل، ووسِم الملف المرفوع به، لا بما طلبته.

كيف تسجّل من الميكروفون؟

قاعدتان في المتصفح تحددان شكل الشيفرة. الأولى: لا يوجد getUserMedia إلا في سياق آمن: HTTPS، أو localhost، أو رابط file:. وعلى 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();
  });
}

ثلاث تفاصيل فيها جاءت من بلاغات أخطاء حقيقية:

  • تجاهل الأجزاء الفارغة. في نقاش على منتدى OpenAI حول MediaRecorder على أجهزة iPhone، وجد أحد المطوّرين أن dataavailable ينطلق ببيانات فارغة على iOS، وحلّ المشكلةَ تصفيةُ تلك الأجزاء. وحلّ مطوّر آخر العَرَض نفسه ببدء التسجيل بفاصل timeslice، أي start(1000).
  • أوقف المسارات. إيقاف المسجّل لا يحرّر الميكروفون. ودون getTracks().forEach(t => t.stop()) يظل المتصفح يعرض مؤشر التسجيل.
  • لا تحسب مدة التسجيل بعدّ الأجزاء. تحذّر MDN من أن فواصل timeslice غير دقيقة، وقد تطول حين يوقف Safari الميكروفون مؤقتًا أو حين يقفل Chrome على Android الشاشة. استخدم مؤقتك الخاص إذا كنت تعرض المدة أو تفرض حدًا لها.

كيف تحوّل التسجيل إلى WAV في المتصفح؟

تستطيع Web Audio API فك ترميز أي شيء سجّله المتصفح. وحقيقتان من MDN تختصران الأمر: الأولى أن decodeAudioData لا يعمل إلا على ملف كامل، لا على أجزاء، ففكّ الترميز بعد stop()؛ والثانية أنه يعيد تشكيل الصوت المفكوك إلى معدل العينات في سياقه. لذلك فإن OfflineAudioContext المُنشأ بتردد 16,000 Hz يعيد عينات بتردد 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 أحادي القناة؟ لأنه الإعداد الذي يستخدمه مثال ffmpeg في وثائق BroadNet نفسها (-ar 16000 -ac 1)، ولأنه يحتفظ بنطاق الكلام، ولأنه ثلث حجم البايتات مقارنة بـ 48 kHz. أما الاستيريو فيضاعف الحجم دون فائدة لصوت واحد. راجع معدل العينات لمعرفة المفاضلات.

وحساب الحجم مهم، لأن WAV غير مضغوط. فـ 16,000 عينة في الثانية بواقع بايتين لكل منها تساوي 32,000 بايت في الثانية. ومع ترويسة من 44 بايت، يتسع حد BroadNet البالغ 26,214,400 بايت لـ 819 ثانية: نحو 13 دقيقة و39 ثانية. وما هو أطول من ذلك، أوقف تسجيله عند حد معيّن، أو قسّمه على الخادم كما في تفريغ الملفات الصوتية الطويلة. وتكتب لك أداة تقسيم الصوت أوامر ffmpeg.

التحويل في المتصفح يستهلك معالج المستخدم وذاكرته، والمقطع المفكوك كله يبقى في الذاكرة كأعداد عشرية بدقة 32 بت. وهذا مقبول للرسائل الصوتية التي تستغرق بضع دقائق. أما التسجيلات الطويلة، فارفع الملف المضغوط وحوّله على الخادم.

كيف تحوّل على الخادم بدلًا من ذلك؟

أرسل التسجيل المضغوط كما هو، ودع ffmpeg يقوم بالعمل. فهذا يعني شيفرة أقل في الصفحة، وملفًا أصغر عند الرفع، والنتيجة نفسها:

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

اكتب الملف المرفوع في ملف مؤقت بدل تمريره إلى ffmpeg عبر أنبوب (pipe). فملفات MP4 قد تحتفظ بفهرسها في نهايتها، ولا يستطيع ffmpeg دائمًا قراءتها من أنبوب. ويستخدم دليل الرسائل الصوتية في WhatsApp الأمر نفسه لملفات .ogg.

كيف تُبقي مفتاح 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 مع الرمز الصحيح لإحدى لغاته الأربع عشرة.
  • أعِد رسائل خطأ عامة. كانت النسخة الأولى من الوكيل الذي اختبرناه تعيد خطأ 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. أنتج encodeWav على ثانية واحدة من نغمة 440 Hz فيها عينتان مقصوصتان ملفًا من 32,044 بايت. وقرأته وحدة wave في Python على أنه قناة واحدة، و16,000 Hz، وعينات من بايتين، و16,000 إطار، وقرأه ffmpeg على أنه pcm_s16le, 16000 Hz, mono. وخرجت العينتان المقصوصتان بالقيمتين 32767 و−32768.
  2. مسار المتصفح في Chromium. شغّل Playwright متصفح Chromium دون واجهة مع ميكروفون وهمي. سجّل startRecording ثلاث ثوانٍ بصيغة audio/webm;codecs=opus (40,563 بايت)، وحوّلها toWav16k إلى ملف WAV من 96,044 بايت: 3.0 ثوانٍ، و16 kHz، وقناة واحدة.
  3. الوكيل. أعاد كلٌّ من ملف WAV وملف WebM الخام الحالة 200. ورأت المحاكاة في كل مرة مصادقة Bearer، ومعرّف النموذج العربي، وlanguage=ar، وملف audio/wav أحادي القناة بتردد 16 kHz؛ وحوّل ffmpeg ملف WebM على الخادم. وحصل ملف WAV من 26,214,401 بايت على 413 دون أي استدعاء للواجهة الأصلية. وحصل جسم طلب ليس صوتًا على 400.
  4. أصل غير آمن. عند تحميل الصفحة من عنوان الجهاز على الشبكة المحلية عبر HTTP العادي، أفادت بأن isSecureContext قيمتها false، ورمى startRecording رسالتنا عن HTTPS بدلًا من TypeError.

لم نختبر Safari أو Firefox، ولا تفريغًا صوتيًا حقيقيًا. جرّب على جهاز iPhone حقيقي قبل الإطلاق.

كم يكلّف ذلك؟

تحتسب BroadNet التفريغ الصوتي لكل دقيقة صوت: $0.0042 لنموذج Transcribe Arabic، و$0.002 للنموذج متعدد اللغات. وساعة من الرسائل الصوتية العربية تكلّف $0.25. ويعمل كلاهما على الرصيد المبدئي البالغ $5، الذي يغطي نحو 1,190 دقيقة من العربية. ولأحجامك الخاصة، استخدم حاسبة تكلفة تحويل الكلام إلى نص. ويقارن دليل شراء API تحويل الكلام العربي إلى نص بين المزوّدين.

أين تناسب BroadNet Inference

BroadRouter هو موقع BroadNet الخاص. تفرّغ BroadNet Inference الملفات المرفوعة: WAV أو MP3، بطلب واحد لكل ملف، مع استجابة JSON تحمل النص. ولا توثّق التفريغ المباشر أو المتدفق، ولا الطوابع الزمنية، ولا تمييز المتحدثين. فإذا كان تطبيقك يحتاج إلى ظهور الكلمات أثناء حديث المستخدم، فاستخدم مزوّدًا يقدّم API كلام متدفقة. أما الرسائل الصوتية والملاحظات والنماذج، حيث يسجّل المستخدم ثم يرسل، فمسار الرفع أعلاه هو كل ما تحتاجه. والإعداد موجود في دليل API تحويل الكلام العربي إلى نص، ويسرد المرجع التقني للواجهة الحقول. ويقول بيان الخصوصية فيها إن الصوت والنصوص المفرّغة لا يُحتفظ بها.

أسئلة شائعة

هل يمكنني إرسال ملف WebM من MediaRecorder مباشرة إلى API لتحويل الصوت إلى نص؟

فقط إذا كانت الواجهة تقبل WebM. تذكر نقطة نهاية التفريغ في OpenAI صيغتَي webm وmp4 ضمن صيغها. أما BroadNet فلا تقبل إلا WAV وMP3، فحوّل الملف أولًا: في المتصفح عبر Web Audio API، أو على خادمك بالأمر ffmpeg -i in.webm -ar 16000 -ac 1 out.wav.

لماذا يقول getUserMedia إن navigator.mediaDevices غير معرّفة؟

لأن الصفحة ليست في سياق آمن. تقول MDN إن getUserMedia لا يعمل إلا عبر HTTPS، أو على localhost، أو من روابط file. وعلى HTTP العادي من مضيف آخر لا تكون navigator.mediaDevices موجودة. قدّم الصفحة عبر HTTPS؛ ويكفي localhost أثناء التطوير.

كم مدة التسجيل التي تتسع لها 25 MB بصيغة WAV؟

ملف WAV أحادي القناة بتردد 16 kHz وعمق 16 بت يشغل 32,000 بايت في الثانية، إضافة إلى ترويسة من 44 بايت. ويتسع حد BroadNet البالغ 26,214,400 بايت لنحو 819 ثانية، أي 13 دقيقة و39 ثانية. وتتسع صيغة MP3 أو معدل عينات أقل لمدة أطول؛ أما الصوت الأطول فقسّمه إلى أجزاء.

لماذا أحصل على "Thank you" أو "Bye" من تسجيل فارغ على iPhone؟

يذكر مطوّرون في منتدى OpenAI عبارات قصيرة مختلَقة من تسجيلات صامتة أو تالفة، وتتبّعوا حالات iOS إلى أجزاء dataavailable فارغة؛ وحلّ المشكلة لديهم تصفيةُ الأجزاء ذات الحجم 0 وبدءُ المسجّل بفاصل timeslice. تحقّق من المدة قبل الرفع.

هل يجب أن يستدعي المتصفح API التفريغ الصوتي مباشرة؟

لا. كل ما في شيفرة الواجهة الأمامية، بما في ذلك مفتاح API، يستطيع المستخدم قراءته. أرسل الصوت إلى نقطة نهاية خاصة بك تتحقق من الحجم والنوع، وتضيف المفتاح من متغير بيئة، ثم تمرّر الطلب.

اقرأها بصيغة Markdownاسأل ChatGPTاسأل Claudeاسأل Perplexity

المصادر