chrome.tts

الوصف

استخدِم واجهة برمجة التطبيقات chrome.tts لتشغيل النص المركّب المحوّل إلى كلام (TTS). اطّلِع أيضًا على واجهة برمجة التطبيقات ذات الصلة ttsEngine، والتي تسمح لإحدى الإضافات بتنفيذ محرّك للتعرّف على الكلام.

يوفّر Chrome هذه الإمكانية على أجهزة Windows (باستخدام SAPI 5) وMac OS X وChromeOS، وذلك باستخدام إمكانات تركيب الكلام التي يوفّرها نظام التشغيل. على جميع الأنظمة الأساسية، يمكن للمستخدم تثبيت إضافات تسجّل نفسها كمحركات بديلة للتعرّف على الكلام.

الأذونات

tts

المفاهيم والاستخدام

إنشاء كلام

اتّصِل بالرقم speak() من الإضافة للتحدّث. على سبيل المثال:

chrome.tts.speak('Hello, world.');

لإيقاف التحدّث فورًا، ما عليك سوى الاتصال بالرقم stop():

chrome.tts.stop();

يمكنك تقديم خيارات تتحكّم في خصائص مختلفة للكلام، مثل سرعته ونبرته وغير ذلك. على سبيل المثال:

chrome.tts.speak('Hello, world.', {'rate': 2.0});

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

chrome.tts.speak('Hello, world.', {'lang': 'en-US', 'rate': 2.0});

بشكل تلقائي، يؤدي كل طلب إلى speak() إلى مقاطعة أي كلام جارٍ والتحدث على الفور. لتحديد ما إذا كانت المكالمة ستؤدي إلى مقاطعة أي شيء، يمكنك الاتصال بالرقم isSpeaking(). بالإضافة إلى ذلك، يمكنك استخدام الخيار enqueue لإضافة هذه العبارة إلى قائمة انتظار من العبارات التي سيتم نطقها عند انتهاء العبارة الحالية.

chrome.tts.speak('Speak this first.'); chrome.tts.speak(     'Speak this next, when the first sentence is done.', {'enqueue': true});

يمكن العثور على وصف كامل لجميع الخيارات ضمن tts.speak(). لن تتوافق بعض محركات تحويل النص إلى كلام مع جميع الخيارات.

لتحديد الأخطاء والتأكّد من أنّك تستخدم speak() بشكل صحيح، مرِّر دالة ردّ لا تأخذ أي وسيطات. داخل دالة الاستدعاء، تحقَّق من runtime.lastError لمعرفة ما إذا حدثت أي أخطاء.

chrome.tts.speak(   utterance,   options,   function() {     if (chrome.runtime.lastError) {       console.log('Error: ' + chrome.runtime.lastError.message);     }   } );

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

الاستماع إلى الأحداث

للحصول على مزيد من المعلومات في الوقت الفعلي حول حالة الكلام المركّب، مرِّر أداة معالجة الأحداث في الخيارات إلى speak()، على النحو التالي:

chrome.tts.speak(   utterance,   {     onEvent: function(event) {       console.log('Event ' + event.type + ' at position ' + event.charIndex);       if (event.type == 'error') {         console.log('Error: ' + event.errorMessage);       }     }   },   callback );

يتضمّن كل حدث نوع الحدث وفهرس الحرف الخاص بالكلام الحالي بالنسبة إلى الجملة، كما يتضمّن رسالة خطأ اختيارية لأحداث الخطأ. أنواع الأحداث هي:

  • ‫'start': بدأ المحرّك بنطق العبارة.
  • ‫'word': تم الوصول إلى حدود كلمة. استخدِم event.charIndex لتحديد موضع الكلام الحالي.
  • ‫'sentence': تم الوصول إلى نهاية جملة. استخدِم event.charIndex لتحديد موضع الكلام الحالي.
  • 'marker': تم الوصول إلى علامة SSML. استخدِم event.charIndex لتحديد موضع الكلام الحالي.
  • ‫'end': انتهى المحرّك من نطق العبارة.
  • ‫'interrupted': تمّت مقاطعة هذا الكلام بمكالمة أخرى إلى speak() أو stop() ولم يكتمل.
  • ‫'cancelled': تم وضع هذا الرد في قائمة الانتظار، ولكن تم إلغاؤه بعد ذلك من خلال طلب آخر إلى speak() أو stop() ولم يبدأ في التحدث على الإطلاق.
  • ‫'error': حدث خطأ خاص بمحرّك معيّن ولا يمكن نطق هذه العبارة. يمكنك الاطّلاع على event.errorMessage لمعرفة التفاصيل.

أربعة من أنواع الأحداث، وهي 'end' و'interrupted' و'cancelled' و'error'، هي نهائية. بعد تلقّي أحد هذه الأحداث، لن يتم نطق هذا الردّ ولن يتم تلقّي أي أحداث جديدة منه.

قد لا تتوافق بعض الأصوات مع جميع أنواع الأحداث، وقد لا ترسل بعض الأصوات أي أحداث على الإطلاق. إذا كنت لا تريد استخدام صوت إلا إذا كان يرسل أحداثًا معيّنة، مرِّر الأحداث التي تحتاج إليها في العنصر requiredEventTypes من عنصر الخيارات، أو استخدِم getVoices() لاختيار صوت يستوفي متطلباتك. يتم توضيح كليهما في ما يلي.

ترميز SSML

قد تتضمّن الجُمل المستخدَمة في واجهة برمجة التطبيقات هذه ترميزًا باستخدام لغة ترميز تركيب الكلام (SSML). في حال استخدام SSML، يجب أن تكون الوسيطة الأولى للدالة speak() مستند SSML كاملاً يتضمّن عنوان XML وعلامة <speak> ذات مستوى أعلى، وليس جزءًا من مستند.

على سبيل المثال:

chrome.tts.speak(   '<?xml version="1.0"?>' +   '<speak>' +   '  The <emphasis>second</emphasis> ' +   '  word of this sentence was emphasized.' +   '</speak>' );

لن تتوافق بعض محرّكات تحويل النص إلى كلام مع جميع علامات SSML، وقد لا تتوافق بعضها مع SSML على الإطلاق، ولكن يجب أن تتجاهل جميع المحرّكات أي علامات SSML غير متوافقة معها وأن تواصل نطق النص الأساسي.

اختيار صوت

يختار Chrome تلقائيًا الصوت الأنسب لكل عبارة تريد نطقها، وذلك استنادًا إلى اللغة. على معظم أنظمة التشغيل Windows وMac OS X وChromeOS، من المفترض أن تتمكّن ميزة تركيب الكلام التي يوفّرها نظام التشغيل من قراءة أي نص بلغة واحدة على الأقل. قد يتوفّر لبعض المستخدمين مجموعة متنوعة من الأصوات من نظام التشغيل ومن محركات تحويل النص إلى كلام التي تنفّذها إضافات Chrome الأخرى. في هذه الحالات، يمكنك تنفيذ رمز مخصّص لاختيار الصوت المناسب أو لتقديم قائمة خيارات للمستخدم.

للحصول على قائمة بجميع الأصوات، استدعِ getVoices() ومرِّر إليها دالة تتلقّى مصفوفة من عناصر TtsVoice كوسيطة:

chrome.tts.getVoices(   function(voices) {     for (var i = 0; i < voices.length; i++) {       console.log('Voice ' + i + ':');       console.log('  name: ' + voices[i].voiceName);       console.log('  lang: ' + voices[i].lang);       console.log('  extension id: ' + voices[i].extensionId);       console.log('  event types: ' + voices[i].eventTypes);     }   } );

الأنواع

EventType

الإصدار 54 من Chrome أو إصدار أحدث

Enum

"start"

"end"

"كلمة"

"جملة"

"marker"

"interrupted"

"cancelled"

"error"

"pause"

"resume"

TtsEvent

حدث من محرّك تحويل النص إلى كلام لإبلاغ حالة الجملة.

الخصائص

  • charIndex

    number اختياري

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

  • errorMessage

    سلسلة اختيارية

    وصف الخطأ، إذا كان نوع الحدث error

  • length

    number اختياري

    الإصدار 74 من Chrome والإصدارات الأحدث

    طول الجزء التالي من العبارة. على سبيل المثال، في حدث word، يمثّل هذا الحقل طول الكلمة التي سيتم نطقها بعد ذلك. سيتم ضبطها على -1 إذا لم يتم ضبطها من خلال محرّك تحويل النص إلى كلام.

  • النوع

    EventType

    يمكن أن يكون النوع start بمجرد بدء الكلام، أو word عند الوصول إلى حدود كلمة، أو sentence عند الوصول إلى حدود جملة، أو marker عند الوصول إلى عنصر علامة SSML، أو end عند الوصول إلى نهاية الجملة، أو interrupted عند إيقاف الجملة أو مقاطعتها قبل الوصول إلى نهايتها، أو cancelled عند إزالتها من قائمة الانتظار قبل تركيبها، أو error عند حدوث أي خطأ آخر. عند إيقاف الكلام مؤقتًا، يتم إطلاق الحدث pause إذا تم إيقاف جملة معيّنة مؤقتًا في منتصفها، ويتم إطلاق الحدث resume إذا تم استئناف الكلام. يُرجى العِلم أنّ أحداث الإيقاف المؤقت والاستئناف قد لا يتم تشغيلها إذا تم إيقاف الكلام مؤقتًا بين الجُمل.

TtsOptions

الإصدار 77 من Chrome أو إصدار أحدث

خيارات الكلام لمشغّل تحويل النص إلى كلام

الخصائص

  • desiredEventTypes

    string[] اختياري

    أنواع أحداث تحويل النص إلى كلام التي تهمّك. في حال عدم توفّرها، قد يتم إرسال جميع أنواع الأحداث.

  • إضافة إلى قائمة الانتظار

    boolean اختياري

    إذا كانت القيمة true، يتم وضع هذا النص في قائمة الانتظار إذا كان تحويل النص إلى كلام قيد التقدّم. إذا كانت القيمة false (وهي القيمة التلقائية)، سيتم إيقاف أي كلام حالي ومسح قائمة انتظار الكلام قبل نطق هذه العبارة الجديدة.

  • extensionId

    سلسلة اختيارية

    معرّف إضافة محرّك تحويل النص إلى كلام المطلوب استخدامه، إذا كان معروفًا

  • الجنس

    VoiceGender اختيارية

    تم إيقافها نهائيًا منذ الإصدار Chrome 77

    تم إيقاف الجنس نهائيًا وسيتم تجاهله.

    جنس صاحب الصوت المُرَكَّب

  • lang

    سلسلة اختيارية

    اللغة التي سيتم استخدامها في التوليف، بالتنسيق اللغة-المنطقة أمثلة: 'en' و'en-US' و'en-GB' و'zh-CN'.

  • رمية

    number اختياري

    درجة الصوت بين 0 و2، حيث 0 هي الأدنى و2 هي الأعلى تشير القيمة 1.0 إلى درجة الصوت التلقائية.

  • المعدّل

    number اختياري

    معدّل التكلّم مقارنةً بالمعدّل التلقائي لهذا الصوت ‫1.0 هو المعدّل التلقائي، وعادةً ما يتراوح بين 180 و220 كلمة في الدقيقة. ‫2.0 أسرع بمرّتين، و0.5 أبطأ بمرّتين. لا يُسمح مطلقًا بالقيم الأقل من 0.1 أو الأكبر من 10.0، ولكن العديد من الأصوات ستفرض قيودًا إضافية على الحد الأدنى والحد الأقصى للمعدلات، على سبيل المثال، قد لا يتحدث صوت معيّن أسرع من 3 مرات من السرعة العادية حتى إذا حدّدت قيمة أكبر من 3.0.

  • requiredEventTypes

    string[] اختياري

    أنواع أحداث تحويل النص إلى كلام التي يجب أن يتوافق معها الصوت

  • voiceName

    سلسلة اختيارية

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

  • الحجم

    number اختياري

    مستوى الصوت بين 0 و1 شاملةً، حيث يمثّل 0 أدنى مستوى و1 أعلى مستوى، والقيمة التلقائية هي 1.0.

  • onEvent

    void اختياري

    يتم استدعاء هذه الدالة مع الأحداث التي تحدث أثناء نطق العبارة.

    تبدو الدالة onEvent على النحو التالي: 

    (event: TtsEvent) => {...}

    • حدث

      TtsEvent

      حدث التعديل من محرك تحويل النص إلى كلام يشير إلى حالة هذا اللفظ.

TtsVoice

وصف لصوت متاح لتجميع الكلام

الخصائص

  • eventTypes

    EventType[] اختياري

    جميع أنواع أحداث معاودة الاتصال التي يمكن لهذا الصوت إرسالها.

  • extensionId

    سلسلة اختيارية

    معرّف الإضافة التي توفّر هذا الصوت

  • الجنس

    VoiceGender اختيارية

    تم إيقافها نهائيًا منذ الإصدار 70 من Chrome

    تم إيقاف الجنس نهائيًا وسيتم تجاهله.

    جنس صاحب هذا الصوت

  • lang

    سلسلة اختيارية

    اللغة التي يتوافق معها هذا الصوت، بالتنسيق اللغة-المنطقة أمثلة: 'en' و'en-US' و'en-GB' و'zh-CN'.

  • جهاز تحكّم عن بُعد

    boolean اختياري

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

  • voiceName

    سلسلة اختيارية

    تمثّل هذه السمة اسم الصوت.

VoiceGender

الإصدار 54 من Chrome والإصدارات الأحدث تم إيقافها نهائيًا منذ الإصدار 70 من Chrome

تم إيقاف الجنس نهائيًا وسيتم تجاهله.

Enum

"male"

"female"

الطُرق

getVoices()

chrome.tts.getVoices(): Promise<TtsVoice[]>

تعرض هذه السمة مصفوفة تتضمّن جميع الأصوات المتاحة.

المرتجعات

  • Promise<TtsVoice[]>

    Chrome 101 والإصدارات الأحدث

isSpeaking()

chrome.tts.isSpeaking(): Promise<boolean>

تتحقّق هذه السمة مما إذا كان المحرّك يتحدث حاليًا. في نظام التشغيل Mac OS X، تكون النتيجة صحيحة عندما يكون محرك تحويل النص إلى كلام في النظام ينطق، حتى إذا لم يبدأ Chrome عملية تحويل النص إلى كلام.

المرتجعات

  • Promise<boolean>

    Chrome 101 والإصدارات الأحدث

pause()

chrome.tts.pause(): void

توقِف تجميع الكلام مؤقتًا، ربما في منتصف الجملة سيؤدي إجراء مكالمة لاستئناف الكلام أو إيقافه إلى إلغاء الإيقاف المؤقت للكلام.

resume()

chrome.tts.resume(): void

في حال تم إيقاف الكلام مؤقتًا، يتم استئنافه من حيث توقّف.

speak()

chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
): Promise<void>

تتحدث باستخدام محرّك تحويل النص إلى كلام.

المعلمات

  • عبارة

    سلسلة

    النص المطلوب تحويله إلى كلام، سواء كان نصًا عاديًا أو مستند SSML كاملاً وسليم البنية ستزيل محرّكات تحويل النص إلى كلام التي لا تتوافق مع SSML العلامات وتقرأ النص. يبلغ الحد الأقصى لطول النص 32,768 حرفًا.

  • الخيارات

    TtsOptions اختيارية

    خيارات الكلام

المرتجعات

  • Promise<void>

    Chrome 101 والإصدارات الأحدث

stop()

chrome.tts.stop(): void

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

الفعاليات

onVoicesChanged

الإصدار 124 من Chrome والإصدارات الأحدث 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

يتم استدعاؤها عند تغيير قائمة tts.TtsVoice التي سيتم عرضها من خلال getVoices.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    () => void