واجهة Socket.IO

استخدم هذا الدليل لدورة حياة Socket.IO: اختر قدرة، واتصل، وسجل أقل مجموعة أحداث، وتعرف على إشارتها النهائية، وافصل دائمًا. استخدم صفحات AsyncAPI المولدة لمخططات الحمولات الكاملة.

في تطبيقات JavaScript وPython، فضّل SDK 0.18.0؛ فهو ينشئ الإطارات الثنائية، ويوجه UUID، ويطبع الأخطاء، ويوفر مساعدي الإغلاق. ابنِ عميلًا مباشرًا فقط عندما تحتاج إلى تحكم على مستوى السلك.

اختر سير العمل

يستقبل النسخ السريع الحمولة المكتملة مرة واحدة. وهو ليس مسار الاجتماعات أو البودكاست أو المواد الأرشيفية الطويلة؛ استخدم النسخ الدفعي لهذه التسجيلات المكتملة.

متطلبات الاتصال

• API_URL وAPI_KEY الصادرتان للبيئة. ويضبط عميل Socket.IO المباشر المسار على /socket.io أيضًا.
• عميل Socket.IO على الخادم. أبقِ API_KEY خارج حزم المتصفح والجوال.
• اضبط transports: ["websocket"] لعقد النقل المنشور والقابل للنقل بين البيئات. قد توجه بعض البيئات polling، لكن يجب ألا يعتمد العميل عليه.
• أرسل x-api-key وOrigin كترويستي اتصال. يشغّل طرف الإنتاج جدار حماية لتطبيقات الويب يرفض أي مصافحة بلا Origin؛ اضبطها على مخطط API_URL ومضيفه.
• تسجيل معالجات الأحداث قبل الاتصال أو قبل إرسال طلب.
• مهلة تطبيق إجمالية لكل طلب أو تدفق.

أبقِ المسار صريحًا في عملاء Socket.IO المباشرين. يستخدم SDK 0.18.0 المسار /socket.io افتراضيًا؛ ولا تمرر api_path إلا عندما يستخدم النشر مسارًا مخصصًا. تتطلب نقطة النهاية القديمة sautech.humain.com المسار /realtime/socket.io.

اتصل مرة واحدة ثم افصل

يمكن لاتصال واحد مضاعفة عدة طلبات أو تدفقات. أعطِ كلًا منها UUID ووجّه كل استجابة حسب id قبل معالجتها.

import { io } from "socket.io-client";

const socket = io(process.env.API_URL!, {
  path: process.env.API_PATH ?? "/socket.io",
  transports: ["websocket"],
  extraHeaders: {
    "x-api-key": process.env.API_KEY!,
    Origin: process.env.API_URL!,
  },
});

try {
  // Register handlers, wait for connect, and run one or more operations.
} finally {
  socket.disconnect();
}

النتيجة المتوقعة: يستدعي العميل معالج نجاح الاتصال قبل إرسال أي طلب للتطبيق. تعامل مع فشل الاتصال كنهاية لهذه المحاولة ونظّف قبل إعادة المحاولة.

في python-socketio، يكون transports معاملًا لـconnect()، وليس لمُنشئ AsyncClient.

النسخ السريع لوحدة صوت مكتملة

يقبل النسخ السريع حمولة AAC أو FLAC أو MP3 أو MP4 أو WAV مكتملة. يجب أن تكون ذرة moov في مقدمة MP4. أرسل ثنائيًا خامًا، لا JSON أو base64.

أقل تسلسل للأحداث:

1. سجل audio_file_upload_success وtranscription_result وerror.
2. أرسل حزمة audio_file ثنائية واحدة.
3. طابق audio_file_upload_success.id مع UUID الطلب؛ فهذا يؤكد الاستلام ولا يعني اكتمال النسخ.
4. وجّه أحداث النتائج حسب id، وعامل seq كقيمة مبهمة لأن عقد Fast العام لا يعرّف دلالات ترتيب أو تجميع لها. أنهِ الانتظار فقط عندما تصبح is_final صحيحة.
5. احتفظ بالاتصال أو أعد استخدامه فقط ضمن مهلة تطبيق؛ وإلا فافصل.

تملك حزمة audio_file هذا التخطيط المتغير الطول الدقيق:

يسلسل SDK 0.18.0 حقول التوافق الثلاثة المحجوزة، لكن خدمة Fast العامة المتحقق منها لا تطبقها. استخدم Batch عندما تحتاج إلى التمييز أو ITN أو الإخفاء.

لا يملك JavaScript SDK 0.18.0 خيار مهلة للنسخ السريع. يستدعي خطأ الطلب الموجه onError ثم يرفض بـError عام يحتفظ بالرسالة فقط. لا تعد إرسال رفع ملتبس بلا تمييز؛ فلا يوجد عقد idempotency-key منشور.

تأطير Realtime ASR ودورة حياته

يحمل audio_stream عينات PCM16 little-endian بتردد 16 kHz وأحادية القناة. أعد استخدام UUID واحد للتدفق كله.

أقل تسلسل للأحداث:

1. سجل transcription_result وdiarization_result الاختياري وerror.
2. أرسل إطار بداية واحدًا بالضبط وبايت رايات 1.
3. أرسل إطارات وسطية وبايت رايات 0.
4. أرسل إطار نهاية واحدًا بالضبط وبايت رايات 2.
5. وجّه النص حسب id وترتيب الوصول المرصود. أبقِ seq القادمة من الخادم للتشخيص فقط لأن ترتيبها وتفرّدها ليسا ضمانين عامين. استبدل النص المؤقت ما دامت رايتا النهاية خاطئتين، وثبّت كلمات الحدث مرة واحدة عندما تصبح is_final أو is_speech_final صحيحة.
6. بعد الدخل النهائي، ينتظر العميل المباشر is_final: true حتى مهلة التطبيق. وينتظر مساعد close() في SDK المنشور is_final نفسها على مستوى البروتوكول أو خطأ موجهًا أو انتهاء مهلته المحدودة. لا تنهي is_speech_final ذلك الانتظار. افحص حالة الاستجابة؛ فقد يعني العود الناجح انتهاء المهلة ولا يثبت النهائية وحده.

ترسل وصفة SDK المختبرة 3,200 بايت صوت، أي 100 ms، في كل إطار. هذا إيقاع عملي وليس ضمانًا للإنتاجية أو زمن الوصول. اضبط البت 2 في بايت الرايات فقط عندما تريد أيضًا أحداث diarization_result على الاتصال نفسه.

تأطير التمييز المباشر ودورة حياته

يستخدم diarization_stream تخطيط الإطار ذي 18 بايت وصيغة PCM المطلوبين نفسيهما في audio_stream. تستخدم راياته البت 0 للبداية والبت 1 للنهاية؛ وأبقِ البتات الأخرى صفرًا.

أقل تسلسل للأحداث:

1. سجل diarization_result وerror.
2. أرسل إطار بداية، ثم إطارات وسطية، ثم إطار نهاية تحت UUID نفسه.
3. اجمع إضافات final_segments غير المشاهدة واستبدل ذيل active_segments الحالي في كل نتيجة.
4. تعامل مع is_final: true كإشارة الخادم النهائية. إذا انتهت المهلة أولًا، فأعد أفضل خط زمني موفق معروف بوصفه غير مكتمل.
5. افصل أثناء التنظيف.

يوصي مساعد SDK الصادر بـ15,360 بايت صوت لكل تغذية. استهلك النتائج أثناء الإرسال؛ فقد يعلق المسار إذا أخّرت الاستهلاك إلى ما بعد انتهاء التغذية. يعيد SDK ‏close(5) أفضل خط زمني معروف عند انتهاء مهلة انتظاره النهائي.

اكتشاف الأصوات ودورة حياة TTS

اكتشف صوتًا بدل تخمين معرّفه:

1. سجل tts_voice_list_result وerror.
2. أرسل tts_voice_list مع {}.
3. تعامل مع الاستجابة كمصفوفة { id, label }؛ وتعامل مع المصفوفة الفارغة.

ثم ولّد الكلام:

1. سجل tts_audio وerror.
2. أرسل tts مع id ونص text يحتوي بعد إزالة الفراغات على حرف Unicode أو رقم واحد على الأقل، وmodel: "nebula" صريح.
3. لاختيار صوت متوقع، أرسل إما voice_id من الاكتشاف أو عنصر voice_references واحدًا بشكل { audio, text }. يكون audio فيه RIFF/WAVE بترميز base64 القياسي وبيانات PCM16 أحادية غير فارغة. المحددان متنافيان.
4. طابق كل استجابة ثنائية حسب UUID الطلب، وألحق البايتات 17..end، وتوقف عند ضبط البت 0 في البايت 16.

بت النهاية هو إشارة اكتمال TTS. حلل كل حدث tts_audio بترويسة التطبيق هذه، ولا تلحق أول 17 بايت منه. استخدم وصفة TTS إلى WAV المختبرة لإنشاء ملف قابل للتشغيل. يؤدي فصل الاتصال إلى إلغاء طلبات التوليف النشطة التي يملكها ذلك الاتصال ومنع أحداث الصوت والخطأ اللاحقة، من دون إغلاق اتصالات الاستدلال المشتركة مع طلبات أخرى.

الأخطاء المنظمة والمهل والإنهاء

تعرف عقود الأحداث المولدة كائنات error تحتوي الحقول المطلوبة code و message وretryable وtimestamp، إضافة إلى id الطلب عندما يمكن توجيه الحمولة. سجل معالجة الأخطاء الخاصة بالطلب والعامة معًا.

يطبع SDK 0.18.0 الاستدعاءات المنظمة. تصبح الحمولة القديمة غير الكائنية { message }. ترفض وعود طلب Fast وTTS بأخطاء عامة تحتفظ بالرسالة فقط بعد استدعاءاتها المنظمة. لا تثبت المهلة النهائية: أوقف الإرسال، واحتفظ بالنتائج المؤكدة، وسجل الإنهاء غير المكتمل، وافصل.

استخدم retryable كمدخل في سياسة إعادة محاولة محدودة، لا كإذن لإعادة محاولة بلا حد. لا تعد رفعًا نتيجته ملتبسة بلا سياسة تطبيق لمنع التكرار.

مرجع الأحداث المولد

يتوقف هذا الدليل عمدًا عند دورة الحياة والتأطير. تحتوي صفحات AsyncAPI المولدة كل حقل وخاصية مطلوبة ومثال وقيد مخطط.