واجهة Socket.IO
اتصل بـHUMAIN Voice عبر Socket.IO وتبادل الأحداث الخام والإطارات الثنائية للنسخ السريع والنسخ الفوري وتمييز المتحدثين المباشر والاستعلام عن الأصوات وتحويل النص إلى كلام.
استخدم هذا البروتوكول مباشرة عندما لا تملك بيئة التشغيل حزمة SDK لـHUMAIN Voice. تبني حزم SDK لـJavaScript وPython هذه الإطارات نيابة عنك.
الاتصال
يخدم اتصال واحد كل سير عمل. أرسل x-api-key وOrigin كترويسات HTTP في طلب ترقية WebSocket، واستخدم وسيلة نقل WebSocket؛ فالاستعلام الدوري غير مدعوم. التفاصيل والمسار القديم: المصادقة.
import { io } from "socket.io-client";
const API_URL = process.env.API_URL!;
const socket = io(API_URL, {
path: process.env.API_PATH ?? "/socket.io",
transports: ["websocket"],
extraHeaders: {
"x-api-key": process.env.API_KEY!,
Origin: new URL(API_URL).origin,
},
});
// Binary frames carry the request UUID as 16 raw bytes.
const uuidBytes = (id: string) => Buffer.from(id.replaceAll("-", ""), "hex");
socket.on("error", (err) => console.error("error:", err));
await new Promise((resolve, reject) => {
socket.once("connect", resolve);
socket.once("connect_error", reject);
});يتحدث الخادم بروتوكول Socket.IO الإصدار 5 (Engine.IO الإصدار 4، أي socket.io-client الإصدار 3.x أو 4.x) على فضاء الأسماء الافتراضي /. تحمل الإطارات الثنائية معرفات UUID بوصفها 16 بايت بترتيب RFC 4122، وهو ترتيب السلسلة السداسية عشرية نفسه.
أعطِ كل طلب أو تدفق UUID خاصًا به؛ تعيده الاستجابات في id، فوجّه النتائج به. تصل الإخفاقات على الحدث error مع code وretryable وid عندما يمكن تحليله؛ راجع الأخطاء والحدود.
أحداث النسخ السريع
| الحدث | الاتجاه | الحمولة |
|---|---|---|
audio_file | إرسال | الحزمة الثنائية أدناه. |
audio_file_upload_success | استقبال | { id }. إيصال فقط: قد يتبعه خطأ error في الصيغة أو المدة. |
transcription_result | استقبال | id، seq، transcription، words (start_time، end_time، word)، is_final. |
error | استقبال | خطأ منظم. |
أرسل الملف كاملًا بايتات خامًا، لا JSON ولا base64. حقول الأطوال أعداد صحيحة بلا إشارة بحجم 16 بت بترتيب little-endian.
| الحقل | البايتات | القيمة والمعنى |
|---|---|---|
| UUID | 0–15 | معرّف الطلب. |
| Language | 16 | 0 = ar، 1 = en، 2 = codeswitch، 255 = auto. |
| ASR key length | 17–18 | طول مفتاح النموذج N؛ القيمة 0 تختار النموذج الافتراضي للغة. |
| ASR key | N bytes | مفتاح النموذج بترميز UTF-8، مثل bayan_cs_ar_en. |
| Reserved keys | 19+N–24+N | أطوال مفاتيح التمييز وITN والتنقيح. أرسل 6 بايتات أصفار. |
| Audio | 25+N–end | ملف الصوت كاملًا بصيغة AAC أو FLAC أو MP3 أو MP4 أو WAV. |
ضع العنصر moov في ملف MP4 في المقدمة: يُقرأ الرفع للأمام فقط، فيفشل فك ترميز ملف يقع moov فيه في النهاية. قيم اللغات ومفاتيح النماذج في النماذج.
import { randomUUID } from "node:crypto";
import { readFileSync } from "node:fs";
const key = Buffer.from("bayan_cs_ar_en");
const len = (n: number) => { const b = Buffer.alloc(2); b.writeUInt16LE(n); return b; };
const fastId = randomUUID();
socket.on("transcription_result", (r) => {
if (r.id === fastId && r.is_final) console.log("final:", r.transcription);
});
socket.emit("audio_file", Buffer.concat([
uuidBytes(fastId), Buffer.of(2), len(key.length), key,
len(0), len(0), len(0), readFileSync("recording.wav"),
]));ينتهي الطلب عند transcription_result مع is_final: true. المخططات الكاملة: أحداث النسخ السريع.
أحداث النسخ الفوري
| الحدث | الاتجاه | الحمولة |
|---|---|---|
audio_stream | إرسال | الإطار الثنائي أدناه؛ يعيد transcription_result. |
diarization_stream | إرسال | الإطار نفسه؛ يعيد diarization_result فقط. |
transcription_result | استقبال | id، seq، transcription، words، is_final، is_speech_final. |
diarization_result | استقبال | id، final_segments، active_segments (start_time، end_time، speaker)، is_final. |
error | استقبال | خطأ منظم. |
يعيد الحدث المتقادم speaker_id الخطأ METHOD_NOT_ALLOWED.
| الحقل | البايتات | القيمة والمعنى |
|---|---|---|
| UUID | 0–15 | UUID نفسه لكل إطار في تدفق واحد. |
| Flags | 16 | البت 0 للبدء، والبت 1 للنهاية، والبت 2 لتفرع التمييز؛ وبقية البتات 0. |
| Language | 17 | 0 = ar، 1 = en، 2 = codeswitch، 255 = auto. يقبل التمييز أيًا من هذه القيم ويتجاهلها. |
| PCM | 18–end | PCM16 little-endian، بتردد 16 kHz وأحادي القناة؛ بطول زوجي غير صفري. |
| الإطار | علامات audio_stream | مع تفرع التمييز |
|---|---|---|
| الأول | 1 | 5 |
| الأوسط | 0 | 4 |
| الأخير | 2 | 6 |
| إطار وحيد | 3 | 7 |
يرسل البت 2 صوت ذلك الإطار إلى التمييز، وتصل أحداث diarization_result على الاتصال نفسه بالقيمة id نفسها. اضبطه في كل إطار من التدفق: الإطارات التي لا تحمله لا تصل إلى التمييز، والتدفق المتفرع جزئيًا لا يحصل على نتيجة تمييز نهائية وينتهي بالخطأ DIARIZATION_FAILED. في diarization_stream، استخدم البتين 0 و1 فقط. أرسل 3,200 بايت (100 ms) لكل إطار بوتيرة الزمن الحقيقي. يرفض الخادم الإطار الأقصر من 18 بايت، أو ذا UUID كله أصفار، أو بت علامة غير معرّف، أو بايت لغة غير معروف، أو صوتًا فارغًا أو بطول فردي.
const streamId = randomUUID();
socket.on("transcription_result", (r) => {
if (r.id === streamId) console.log(r.is_final ? "final:" : "partial:", r.transcription);
});
const pcm = readFileSync("recording.pcm");
for (let off = 0; off < pcm.length; off += 3200) {
const flags = (off === 0 ? 1 : 0) | (off + 3200 >= pcm.length ? 2 : 0);
socket.emit("audio_stream", Buffer.concat([uuidBytes(streamId), Buffer.of(flags, 2 /* codeswitch */), pcm.subarray(off, off + 3200)]));
await new Promise((r) => setTimeout(r, 100));
}بعد الإطار الأخير، واصل الاستماع حتى تصل نتيجة مع is_final: true. مع التفرع، يرسل transcription_result وdiarization_result كل منهما is_final: true خاصًا به، وقد تصل نتيجة التمييز لاحقًا، فانتظر الاثنتين. لتطبيق النتائج المؤقتة والنهائية ودمج مقاطع المتحدثين، راجع المفاهيم. المخططات الكاملة: أحداث Realtime.
أحداث تحويل النص إلى كلام
| الحدث | الاتجاه | الحمولة |
|---|---|---|
tts | إرسال | طلب JSON أدناه. |
tts_audio | استقبال | الإطار الثنائي أدناه. |
error | استقبال | خطأ منظم. |
| الحقل | مطلوب | القيمة |
|---|---|---|
id | نعم | UUID الطلب. |
text | نعم | نص عادي، لا SSML، يحوي حرفًا أو رقمًا واحدًا على الأقل. حدود الطول. |
model | لا (أرسل nebula) | nebula. عند حذفه يُطبَّق الافتراضي للنشر. |
voice_id | أحدهما | id لملف صوت من قائمة الأصوات. |
voice_references | أحدهما | عنصر واحد { audio, text }: ملف WAV بصيغة PCM16 أحادي القناة بترميز base64 القياسي (بلا فواصل أسطر وغير آمن للعناوين) ونصه المنسوخ. |
| الحقل | البايتات | القيمة والمعنى |
|---|---|---|
| UUID | 0–15 | معرّف الطلب. |
| Header | 16 | البت 0 مضبوط في الإطار الأخير؛ وبقية البتات 0. |
| PCM | 17–end | PCM16 little-endian، بتردد 24 kHz وأحادي القناة، بلا ترويسة WAV. |
أضف البايتات من 17 فصاعدًا من كل إطار يخص id الخاص بك، بما فيها الإطار الأخير. تأتي voiceId من قائمة الأصوات.
const ttsId = randomUUID();
const chunks: Buffer[] = [];
socket.on("tts_audio", (data: ArrayBuffer) => {
const frame = Buffer.from(data);
if (!frame.subarray(0, 16).equals(uuidBytes(ttsId))) return;
chunks.push(frame.subarray(17));
if (frame[16] & 1) console.log("done:", Buffer.concat(chunks).length, "bytes");
});
socket.emit("tts", { id: ttsId, text: "مرحبًا من HUMAIN Voice", model: "nebula", voice_id: voiceId });ينتهي التوليف الذي يتجاوز 25 ثانية بالخطأ TTS_DEADLINE_EXCEEDED القابل لإعادة المحاولة؛ فتخلص من الصوت الجزئي. لجعل PCM قابلًا للتشغيل، راجع تحويل النص إلى كلام: الحفظ أو البث. المخططات الكاملة: أحداث TTS.
قائمة الأصوات
أرسل tts_voice_list مع {}؛ يجيب الخادم بحدث tts_voice_list_result واحد يحمل مصفوفة من ملفات الأصوات. لكل عنصر id وlabel وprofile:
[
{
"id": "42e38a63-849a-481a-b5bf-3c1b7a985de3",
"label": "mul_nourah",
"profile": { "speaker": { "gender": "female", "dialect": "ars" }, "languages": ["ar", "en"] }
}
]const voices = await new Promise<{ id: string; label: string }[]>((resolve) => {
socket.once("tts_voice_list_result", resolve);
socket.emit("tts_voice_list", {});
});
const voiceId = voices[0]?.id;يصدر فشل الاستعلام الخطأ TTS_VOICE_LIST_FAILED على error بلا id، فقيّد الانتظار بمهلة. تختلف المعرفات بين البيئات، والمصفوفة الفارغة إجابة صالحة. معاني الحقول والأصوات الحالية في النماذج.
انقطاع الاتصال
تذهب النتائج إلى الاتصال الذي أرسل الطلب فقط. لا يُستأنف شيء بعد إعادة الاتصال؛ ولا يوجد عقد لإعادة التشغيل.
| سير العمل | عند انقطاع اتصال عميلك |
|---|---|
| النسخ السريع | لا يوجد عقد استئناف أو إعادة تشغيل أو idempotency. لا تعد الإرسال دون تحقق؛ وإذا فعلت فاستخدم UUID جديدًا. |
| النسخ الفوري، تمييز المتحدثين المباشر | ينتهي التدفق. احتفظ بالنتائج المثبتة وابدأ تدفقًا جديدًا بـUUID جديد. |
| تحويل النص إلى كلام | يلغي الخادم عمليات التوليف الخاصة بذلك الاتصال ولا يرسل لها صوتًا أو أخطاء بعد ذلك. لا تتأثر الاتصالات الأخرى. |
يقطع الخادم اتصالك بعد هذه الأخطاء، ويصدر الحدث error دائمًا أولًا:
| الخطأ | المحفز |
|---|---|
PAYLOAD_TOO_LARGE | رفع سريع يتجاوز 64 MiB، أو إطار فوري يتجاوز 16 MiB. |
CREDITS_EXHAUSTED | نفد رصيد الحساب في منتصف التدفق. |
BILLING_AUTHORIZATION_UNAVAILABLE | تعذر على الفوترة ترخيص التدفق في منتصفه. |
لا يحمل انقطاع Socket.IO رمز إغلاق على مستوى التطبيق؛ فاعتبر الحدث error هو الإشارة.