---
title: بث الصوت
description: دليل استلام ومعالجة وتشغيل تدفق الصوت العربي بطريقة صحيحة وآمنة عبر المسار POST /v1/audio/speech.
---

تتيح واجهة برمجة تطبيقات تحويل النص إلى كلام تسليم الصوت لحظياً باستخدام تقنية التجزئة لبروتوكول HTTP (Chunked Transfer Encoding). يوضح هذا الدليل بروتوكول نقل البيانات عبر الشبكة، وصيغ الصوت المدعومة، وكيفية قراءة ترويسات الاستجابة، وأفضل ممارسات التشغيل الصوتي الآمن، وسلوك النظام عند انقطاع تدفق الصوت.

## آلية نقل البيانات عبر الشبكة

```http
POST /v1/audio/speech
```

عند بدء توليد الصوت، تستجيب بوابة الخدمة برمز الحالة `200 OK` وتبث البيانات الصوتية جزءاً تلو الآخر في الوقت الفعلي:

- **آلية النقل**: البث التدفقي عبر HTTP Chunked Transfer Encoding (`Transfer-Encoding: chunked`).
- **غياب ترويسة طول المحتوى (Content-Length)**: نظراً لأن الصوت يُولّد ديناميكياً ولحظياً، لا تتضمن الاستجابة ترويسة `Content-Length`.
- **التسليم اللحظي**: تُمرر الأجزاء الصوتية إلى العميل فور صدورها من محرك الاستدلال لتقليل زمن وصول أول بايت (TTFB).

## صيغ الصوت المدعومة

تُحدد صيغة الصوت المطلوبة في جسم طلب JSON عبر المعامل `response_format`.

| الصيغة | قيمة `response_format` | نوع المحتوى (`Content-Type`) | المواصفات الفنية |
| :--- | :--- | :--- | :--- |
| **PCM الخطي** | `"pcm"` *(الافتراضي)* | `audio/pcm` | بيانات خطية خام غير مضغوطة بدقة 16 بت بإشارة ونهاية صغرى (`s16le`)، أحادية القناة (Mono). معدل أخذ العينات الافتراضي هو 24,000 هرتز (`24000`)، أو القيمة المحددة في `sample_rate` (بين 8,000 و 48,000 هرتز). لا تتضمن أي ترويسة أو غلاف للبيانات. |
| **WAV** | `"wav"` | `audio/wav` | ترويسة RIFF/WAVE قياسية بحجم 44 بايت تضاف في مستهل دفق PCM الخطي أحادي القناة بدقة 16 بت. تعتمد قيم أطوال البث التدفقي القياسية (`0xFFFFFFFF`). |

### محاذير مفككات الترميز والصيغ غير المدعومة

- **عدم دعم MP3**: لا تدعم الخدمة الصيغ الصوتية المضغوطة مثل `mp3`. يؤدي طلب صيغة غير مدعومة إلى إعادة رمز الخطأ `400 Bad Request` مع كود `unsupported_response_format`.
- **القيم الافتراضية لأطر عمل العملاء**: تعتمد بعض حزم تطوير البرمجيات وأطر عمل الوكلاء الصوتيين (مثل LiveKit) طلب صيغة `mp3` افتراضياً. يجب تحديد المعامل صراحةً بقيمة `response_format: "pcm"` أو `"wav"`.
- **أخطاء فك الترميز الصامتة**: تمرير بايتات PCM الخام مباشرة إلى مفكك ترميز MP3 أو AAC يؤدي إلى إصدار ضجيج وتشويش حاد دون ظهور رسالة خطأ صريحة من بروتوكول HTTP أو من مفكك الترميز.

## ترويسات الاستجابة الفعلية

يجب فحص ترويسات استجابة HTTP لضبط مشغلات الصوت، والتحقق من معدلات العينات، وربط سجلات الطلبات.

| الترويسة | قيمة نموذجية | الوصف |
| :--- | :--- | :--- |
| `Content-Type` | `audio/pcm` أو `audio/wav` | نوع الوسائط المطابق لقيمة `response_format` المحددة. في حال حدوث خطأ قبل بدء البث تعود بقيمة `application/json`. |
| `Transfer-Encoding` | `chunked` | تشير إلى تسليم الصوت في أجزاء تدفقية لحظية دون تحديد مسبق لحجم المحتوى. |
| `X-Sample-Rate` | `24000` | معدل أخذ العينات الفعلي للصوت بالهرتز. يعكس إما القيمة الافتراضية (`24000`) أو المعدل المطلوب في `sample_rate` (بين 8000 و 48000). يجب دائماً ضبط جهاز إخراج الصوت وفقاً لهذه القيمة. |
| `X-Audio-Sample-Rate` | `24000` | ترويسة رديفة مطابقة لقيمة `X-Sample-Rate`. |
| `X-Channels` | `1` | عدد القنوات الصوتية (`1` للصوت الأحادي Mono). |
| `X-Audio-Channels` | `1` | ترويسة رديفة مطابقة لقيمة `X-Channels`. |
| `X-Request-Id` | `a1b2c3d4-...` | معرّف الطلب الفريد (UUID) الصادر عن بوابة الخدمة. يُستخدم لربط السجلات، واستكشاف الأخطاء، والمتابعة المالية. |
| `Cache-Control` | `no-cache` | يمنع خوادم التخزين المؤقت الوسيطة من احتجاز أجزاء البث التدفقي. |
| `X-Accel-Buffering` | `no` | يوجه خوادم الوكيل العكسي (مثل Nginx) بإلغاء التخزين المؤقت، مما يضمن تسليم أجزاء الصوت للعميل فوراً دون تأخير. |

## إرشادات التشغيل الآمن لصوت PCM و WAV

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

### تشغيل صوت PCM الخام (`audio/pcm`)

لا يحتوي دفق PCM الخام على أي ترويسات لتحديد الصيغة أو القنوات أو معدل أخذ العينات.

1. **التهيئة المسبقة لمشغل الصوت**:
   يجب ضبط جهاز إخراج الصوت أو سياق الصوت (Audio Context) يدوياً قبل تمرير الأجزاء الصوتية:
   - **صيغة العينات**: عدد صحيح 16 بت ذو إشارة ونهاية صغرى (`s16le` أو `Int16Array`).
   - **عدد القنوات**: 1 (أحادي Mono).
   - **معدل أخذ العينات**: يُقرأ ديناميكياً من ترويسة الاستجابة `X-Sample-Rate` (القيمة الافتراضية `24000` هرتز).
2. **محاذاة حدود العينات (Sample Boundary Alignment)**:
   - تتكون كل عينة صوتية من 16 بت (2 بايت).
   - قد تصل أجزاء الشبكة بعدد فردي من البايتات. يحظر تمرير عينة غير مكتملة (بايت واحد) إلى مصفوفة معالجة العينات.
   - إذا انتهى جزء البيانات ببايت مفرد، يجب الاحتفاظ به ودمجه في مقدمة الجزء التالي قبل التحويل إلى عينات PCM خطية.
3. **مخزن موازنة التذبذب (Jitter Buffer)**:
   يُوصى بالاحتفاظ بقدر يسير من الصوت في الذاكرة المؤقتة (من 50 إلى 100 مللي ثانية مثلاً) قبل بدء التشغيل الفعلي لتفادي تقطع الصوت الناتج عن تفاوت زمن استجابة الشبكة.

### تشغيل صوت WAV التدفقي (`audio/wav`)

تُغلّف صيغة `"wav"` دفق PCM أحادي القناة بدقة 16 بت بترويسة RIFF/WAVE قياسية مكونة من 44 بايت في أول جزء تدفقي يُرسل.

1. **دلالة أطوال البث التدفقي (`0xFFFFFFFF`)**:
   نظراً لأن الطول الكلي للصوت غير معروف أثناء البث اللحظي، تضبط بوابة الخدمة حقل حجم كتلة RIFF (عند الإزاحة 4) وحقل حجم كتلة البيانات `data` (عند الإزاحة 40) على القيمة القصوى `0xFFFFFFFF` (`4,294,967,295` بايت). وهذا هو العرف القياسي المعتمد في مشغلات WAV التدفّقية.
2. **المشغلات التدفّقية مقابل المشغلات الثابتة**:
   - **مفككات البث التدفقي**: تدعم أدوات ومكتبات مثل FFmpeg ومفككات الصوت التدفّقية في المتصفحات القيمة `0xFFFFFFFF` وتشغل التدفق باستمرار حتى إغلاق اتصال HTTP.
   - **مفككات الملفات الثابتة**: المشغلات التي تفترض ملفاً مكتملاً وتبحث عن نهاية الملف استناداً إلى الطول المسجل بالترويسة قد تُظهر خطأ يفيد بعدم صلاحية الملف.
3. **الحفظ على وسائط التخزين (القرص)**:
   في حال حفظ تدفق WAV في ملف لتشغيله لاحقاً عبر برامج الوسائط التقليدية:
   - احسب إجمالي بايتات البيانات الصوتية المستلمة (`data_bytes`).
   - بعد انتهاء البث بالكامل، انتقل إلى الإزاحة 4 واكتب القيمة `data_bytes + 36` بنظام النهاية الصغرى 32 بت (حجم كتلة RIFF).
   - انتقل إلى الإزاحة 40 واكتب القيمة `data_bytes` بنظام النهاية الصغرى 32 بت (حجم كتلة `data`).
   - كخيار بديل، يمكنك اقتطاع أول 44 بايت وتخزين البيانات المتبقية كصوت PCM خام بنظام `s16le`.

## سلوك النظام عند انقطاع الاستجابة

يضمن فهم دورة محاسبة الطلبات وطريقة تعامل البوابة مع حالات انقطاع الاتصال بناء تكامل برمجي متين لدى العميل.

### دورة المحاسبة ومراحل التدفق

- **التفويض والخصم المسبق**: تتحقق البوابة من صحة الطلب وتخصم التكلفة من الرصيد مسبقاً بناءً على عدد أحرف حقل `input` قبل حجز وحدات المعالجة.
- **تأكيد نجاح العملية عند أول بايت**: بمجرد تسليم أول جزء صوتي للعميل بنجاح، تُعتمد العملية كطلب مكتمل بنجاح.
- **الاكتمال الطبيعي**: عند انتهاء توليد الصوت، يُغلق اتصال HTTP تلقائياً وتُحرر جميع موارد المعالجة وحصص التزامن.

### سيناريوهات الانقطاع

#### 1. فشل الخادم قبل بدء البث (رموز 4xx / 5xx)
إذا تعذر التحقق من صحة المدخلات، أو كان الرصيد غير كافٍ، أو تعذر توفير وحدة معالجة، تعيد البوابة كائن خطأ قياسي بصيغة JSON:

```json
{
  "error": {
    "message": "Insufficient balance",
    "type": "billing_error",
    "code": "insufficient_balance",
    "param": null,
    "request_id": "..."
  }
}
```

إذا كان الفشل ناتجاً عن خطأ مؤهل من جانب الخادم (مثل أخطاء 5xx أو صدور تدفق فارغ تماماً بحيث لم يُنتج الخادم أي بايتات صوتية)، يُسترد المبلغ المخصوم تلقائياً إلى رصيد الحساب.

#### 2. تعثر الخادم أو وحدة المعالجة أثناء البث
إذا واجهت وحدة المعالجة خطأ غير قابل للاسترداد بعد بدء بث أجزاء الصوت:
- نظراً لإرسال رمز الحالة `200 OK` والترويسات للعميل مسبقاً، لا يمكن تعديل رمز الحالة في منتصف الاستجابة.
- تنهي البوابة البث التدفقي وتقطع اتصال الشبكة فوراً لمنع إرسال بيانات صامتة أو تالفة.
- يظل الخصم المالي المقتطع قائماً نظراً لتسليم جزء من الصوت إلى العميل.

#### 3. انقطاع الاتصال أو إلغاء الطلب من جانب العميل أثناء البث
إذا قام العميل بإلغاء الطلب، أو إغلاق المقبس الشبكي، أو انقطع اتصاله قبل اكتمال البث:
- تكتشف البوابة انقطاع الاتصال فوراً، وتُحرر وحدة المعالجة وحصة التزامن دون إبطاء.
- **يظل الخصم المالي قائماً**: يُصنف انقطاع العميل على أنه انسحاب من جهة المستخدم وليس خللاً في الخدمة، ولا يتم استرداد المبلغ المخصوم.

### تعامل العميل البرمجي مع انقطاع التدفق

- **تدفقات PCM**: في حال انقطاع الشبكة فجأة أو إلغاء البث، تظل كافة العينات المكتملة بدقة 16 بت التي استُلمت قبل الانقطاع صالحة وسليمة وقابلة للتشغيل دون تشوه صوتي.
- **تدفقات WAV**: في حال انقطاع التدفق، ينتهي الاتصال قبل بلوغ الطول الاسمي `0xFFFFFFFF`؛ وستواجه مفككات البث التدفقي إشارة نهاية ملف غير متوقعة (EOF). يجب على تطبيق العميل التقاط إغلاق المقبس بسلاسة دون التسبب في انهيار التطبيق.