بث الكلام أثناء توليده

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

متى تستخدم البث

استخدم البث حين ينتظر أحدٌ سماع الرد: وكيل صوتي، أو مكالمة هاتفية، أو مساعد مباشر. أما الصوت الذي تخزّنه أو تقدّمه لاحقًا، فتعطيك نقطة النهاية المتزامنة ملفًا ومهمة.

كيف تعمل الجلسة

you                                        server
 |-- upgrade: Authorization --------------->|
 |-- {"type":"synthesize", ...} ----------->|
 |<-------------------------------- start   |
 |<---------------- binary PCM frames ...   |
 |<-------------------------------- done    |
 |-- {"type":"synthesize", ...} ----------->|   the next text, same socket
 |<-------------------------------- start   |
 |<---------------- binary PCM frames ...   |
 |-- {"type":"cancel"} -------------------->|   the listener interrupts
 |<---------------------------- cancelled   |

ما تحتاج إليه

• مفتاح API تشمل خدماته تحويل النص إلى كلام، أو لا يقيّد الخدمات أصلًا. انظر احصل على مفتاح API.
• قيمة voiceId من عرض الأصوات المتاحة.
• خادم. لا تستطيع المتصفحات ضبط header Authorization على WebSocket، فلا يمكن لصفحة ويب أن تتصل. ابثّ على خادمك ومرّر الصوت إلى المشغّل لديك؛ ولا تضع المفتاح في صفحة أبدًا.
• رصيد على مساحة العمل. انظر الرصيد.
• لعميل Python أدناه: Python 3.9 أو أحدث، وpip install "websockets>=14".

الخطوة 1: اتصل

افتح WebSocket إلى wss://api.echonova.ai/v1/text-to-speech/stream مع Authorization: Bearer YOUR_API_KEY على طلب الترقية (upgrade). لا يأخذ البث أي معاملات استعلام. وإن كان هناك خطأ قبل الترقية، يردّ الخادم بـ HTTP عادي والغلاف المعتاد للأخطاء، ولا يُخصم شيء؛ انظر الأخطاء.

افتح المقبس قبل أن تحتاج إليه، عند بدء المكالمة مثلًا، وأبقه مفتوحًا طوال المحادثة. إعادة استخدامه توفّر وقت الاتصال في كل رد، ولا يُحتسب إلا بثًّا واحدًا من بثوثك المتزامنة.

الخطوة 2: أرسل رسالة synthesize

{ "type": "synthesize", "requestId": "reply-1", "text": "أهلاً بك، كيف يمكنني مساعدتك اليوم؟", "voiceId": "66e5ef3a9c1d2b4f8a7e6c01" }

للحقول المعنى نفسه الذي لها في توليد الكلام بشكل متزامن؛ انظر الأصوات والخيارات في تحويل النص إلى كلام.

لا يُنطق على المقبس إلا نص واحد في كل مرة. ورسالة synthesize تُرسل بينما أخرى ما زالت قيد التشغيل تلغي الجارية أولًا، تمامًا كأنك أرسلت cancel ثم synthesize.

الخطوة 3: شغّل الصوت فور وصوله

يردّ الخادم بـ start، ثم إطارات ثنائية، ثم done:

{ "type": "start", "requestId": "reply-1", "sampleRate": 24000, "encoding": "pcm_s16le", "channels": 1 }

كل إطار ثنائي هو PCM أحادي القناة بعمق 16 بت، بإشارة، وبترتيب little-endian، بمعدل العيّنات sampleRate المذكور في start. وهو 24 kHz حاليًا، ولا تقبل synthesize معدلًا خاصًا بها، لكن اقرأه من start بدلًا من تثبيته في الكود. شغّل الإطارات بترتيب وصولها، أو ألحقها بملف. يُولَّد الصوت بضع ثوانٍ من الكلام في كل مرة، فتصل الإطارات على دفعات: أعطِ المشغّل مخزنًا مؤقتًا صغيرًا، بضع مئات من الميلي ثانية، حتى لا ينفد ما لديه بين الدفعات.

{ "type": "done", "requestId": "reply-1", "durationSeconds": 2.9, "characters": 36, "creditsConsumed": 36 }

تعني done أن كل إطارات ذلك النص قد أُرسلت. لا تحمل الإطارات الثنائية requestId؛ فالإطارات الواقعة بين start وdone أو cancelled التابعة له تنتمي إلى ذلك الطلب.

مع الحزمة sounddevice مثلًا، يكون التشغيل تدفقًا تكتب فيه الإطارات:

import sounddevice  # pip install sounddevice

player = sounddevice.RawOutputStream(samplerate=24000, channels=1, dtype="int16")
player.start()
# for every binary frame received:
player.write(frame)

الخطوة 4: انطق الرد جملةً جملة

حين يأتي النص من نموذج لغوي، لا تنتظر الرد كله. قسّمه إلى جمل أثناء توليده، وأرسل كل جملة في synthesize خاصة بها، فيسمع المستمع الجملة الأولى والنموذج ما زال يكتب البقية.

لا ترسل الجملة التالية إلا بعد done الخاصة بالجملة السابقة. فرسالة synthesize المرسلة قبل ذلك تلغي الجملة التي ما زالت تُنطق. احتفظ بطابور (queue) من جهتك:

1. حين تكتمل جملة (تنتهي بـ . أو ? أو ! أو ؟ أو بفاصل سطر)، أضفها إلى الطابور.
2. حين يكون المقبس خاملًا، أرسل أول جملة في الطابور.
3. عند done، أرسل الجملة التالية.

الموصى به

• رسالة synthesize واحدة لكل جملة أو فقرة قصيرة، كلٌّ منها أقل من 500 حرف، تُرسل واحدة تلو الأخرى على مقبس واحد.

الأقل فاعلية

• رسالة synthesize لكل بضع كلمات. تُنطق كل قطعة وحدها، فيفقد الصوت إيقاع الجملة.
• مقبس جديد لكل جملة. كل مقبس يضيف اتصالًا، ويُحتسب ضمن حد البثوث المتزامنة.

الخطوة 5: توقف عن الكلام حين يقاطعك المستمع

حين يبدأ المستمع الكلام فوق الرد، أرسل:

{ "type": "cancel" }

يوقف الخادم التوليد ويردّ بـ {"type":"cancelled","requestId":"reply-1"}. لا يصل بعد cancelled أي إطار لذلك الطلب.

يسري الإلغاء عند حدّ الدفعة التالية: فقد تصل بضعة إطارات وُلّدت بالفعل بين cancel الذي أرسلته وcancelled. أوقف المشغّل وأفرغ مخزنه المؤقت فورًا من جهتك، وتجاهل كل إطار حتى تصل cancelled. ثم أرسل synthesize التالية، أو أرسلها فورًا: فرسالة synthesize الجديدة تلغي الجارية أيضًا.

عميل Python كامل

يرسل هذا العميل نصًا واحدًا، ويجمع إطارات PCM، ويكتبها في speech.wav. العميل نفسه بلغات JavaScript وTypeScript وGo وC# موجود في بث تحويل النص إلى كلام.

import asyncio
import json
import wave

import websockets  # pip install "websockets>=14"

URL = "wss://api.echonova.ai/v1/text-to-speech/stream"
API_KEY = "YOUR_API_KEY"


async def main():
    pcm = bytearray()
    rate = 24000
    async with websockets.connect(
        URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
    ) as ws:
        await ws.send(json.dumps({
            "type": "synthesize",
            "requestId": "reply-1",
            "text": "أهلاً بك، كيف يمكنني مساعدتك اليوم؟",
            "voiceId": "66e5ef3a9c1d2b4f8a7e6c01",
        }))
        while True:
            message = await ws.recv()
            if isinstance(message, bytes):  # a binary frame of PCM16
                pcm.extend(message)
                continue
            event = json.loads(message)
            if event["type"] == "start":
                rate = event["sampleRate"]
            elif event["type"] == "done":
                print("seconds:", event["durationSeconds"], "credits:", event["creditsConsumed"])
                break
            elif event["type"] in ("error", "cancelled"):
                raise SystemExit(f"{event['type']}: {event.get('message', '')}")

    with wave.open("speech.wav", "wb") as wav:
        wav.setnchannels(1)
        wav.setsampwidth(2)
        wav.setframerate(rate)
        wav.writeframes(bytes(pcm))


asyncio.run(main())

الأخطاء على مقبس مفتوح

تحمل رسالة error الحقلين code وmessage، وكذلك requestId حين يتعلق الخطأ بنص واحد:

كل رموز الإغلاق مذكورة في الأخطاء.

الفوترة

تكلّف كل synthesize رصيدًا واحدًا (1 credit) لكل حرف من text، بما في ذلك المسافات، وهو السعر نفسه في نقاط نهاية تحويل النص إلى كلام الأخرى. يُخصم الرصيد حين يبدأ التوليد، قبل أول إطار، وتكرر done المقدار في creditsConsumed. والتوليد الملغى، سواء بـ cancel أو بـ synthesize أحدث، يُحتسب مع ذلك. وإن فشل التوليد قبل إرسال أي صوت، يُسترد الرصيد. ينطبق حد الرصيد الخاص بالمفتاح على كل synthesize. انظر الرصيد.

الحدود

انظر حدود معدل الطلبات لمعرفة كيف تُحتسب حدود البث.

حل المشكلات

قطعت جملتي الثانية الجملة الأولى

رسالة synthesize المرسلة قبل done الخاصة بالسابقة تلغيها. ضع الجمل في طابور وأرسل كلًّا منها عند done السابقة، كما في الخطوة 4.

تستمر الإطارات في الوصول بعد إرسال cancel

يتوقف التوليد عند حدّ الدفعة التالية، فقد تتبع cancel بضعة إطارات. تجاهل كل إطار حتى تصل cancelled.

يُشغَّل الصوت سريعًا جدًا أو بطيئًا جدًا أو كضجيج

شغّله بمعدل العيّنات sampleRate المذكور في start، كعيّنات أحادية القناة بعمق 16 بت، بإشارة، وبترتيب little-endian. المشغّل المضبوط على معدل آخر، أو على استريو، أو على 8 بت، يسيء قراءة الإطارات.

يُغلق المقبس بعد دقيقتين من الصمت

مهلة الخمول 120 ثانية دون أي إطار. أرسل {"type":"ping"} كل دقيقة تقريبًا ما دامت المحادثة هادئة؛ ويردّ الخادم بـ pong.

الأسئلة الشائعة

هل يمكنني الحصول على MP3 أو Opus بدلًا من PCM؟

لا. يرسل البث PCM خامًا أحادي القناة بعمق 16 بت. رمّزه بنفسك إن احتجت إلى صيغة أخرى، أو استخدم توليد الكلام بشكل متزامن للحصول على ملف WAV.

هل يمكن لمقبس واحد أن يستخدم عدة أصوات؟

نعم. voiceId جزء من كل synthesize، فيمكن لكل نص أن يستخدم صوتًا مختلفًا، نصًا واحدًا في كل مرة.

هل يمكنني الاتصال من متصفح؟

لا. لا يستطيع المتصفح ضبط header Authorization على WebSocket، ويجب ألا يصل المفتاح إلى صفحة ويب أبدًا. ابثّ على خادمك ومرّر الصوت.

صفحات ذات صلة

• بث تحويل النص إلى كلام
• دليل البدء السريع لتحويل النص إلى كلام
• الأصوات والخيارات في تحويل النص إلى كلام
• عرض الأصوات المتاحة
• الاستدعاءات المتزامنة وغير المتزامنة
• حدود معدل الطلبات
• الرصيد