chrome.tts

الوصف

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

الأذونات

tts

نظرة عامة

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

جارٍ إنشاء الكلام

يمكنك الاتصال بالرقم 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

"البدء"

"النهاية"

"كلمة"

"الجملة"

"marker"

"تمّت المقاطعة"

"تم الإلغاء"

"خطأ"

"إيقاف مؤقت"

"الاستئناف"

TtsEvent

حدث من محرك تحويل النص إلى كلام (TTS) لتوصيل حالة اللفظ.

أماكن إقامة

  • charIndex

    الرقم اختياري

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

  • errorMessage

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

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

  • length

    الرقم اختياري

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

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

  • كتابة

    EventType

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

TtsOptions

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

خيارات الكلام لمحرك تحويل النص إلى كلام.

أماكن إقامة

  • desiredEventTypes

    string[] اختيارية

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

  • إدراج في قائمة الانتظار

    قيمة منطقية اختيارية

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

  • extensionId

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

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

  • الجنس

    VoiceGender اختياري

    متوقّف منذ الإصدار 77 من Chrome

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

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

  • lang

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

    اللغة التي سيتم استخدامها في التركيبة، بالتنسيق language-region أمثلة: "en" و"en-US" و"en-GB" و"zh-CN"

  • رمية

    الرقم اختياري

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

  • المعدّل

    الرقم اختياري

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

  • requiredEventTypes

    string[] اختيارية

    أنواع أحداث "تحويل النص إلى كلام" (TTS) التي يجب أن تتوافق مع الصوت.

  • voiceName

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

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

  • الحجم

    الرقم اختياري

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

  • onEvent

    null اختياري

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

    تبدو دالة onEvent كما يلي: 

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

    • event

      TtsEvent

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

TtsVoice

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

أماكن إقامة

  • eventTypes

    EventType[] اختيارية

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

  • extensionId

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

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

  • الجنس

    VoiceGender اختياري

    متوقّف منذ إصدار Chrome 70

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

    جنس هذا الصوت

  • lang

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

    اللغة المتوافقة مع هذا الصوت على شكل language-region أمثلة: "en" و"en-US" و"en-GB" و"zh-CN"

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

    قيمة منطقية اختيارية

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

  • voiceName

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

    اسم الصوت

VoiceGender

الإصدار 54 من Chrome أو الإصدارات الأحدث متوقّف منذ إصدار Chrome 70

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

Enum

"ذكر"

"أنثى"

الطُرق

getVoices()

وعود 
chrome.tts.getVoices(
  callback?: function,
)

للحصول على مجموعة من جميع الأصوات المتاحة.

المعلمات

  • رد الاتصال

    الدالة اختيارية

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

    (voices: TtsVoice[]) => void

    • الأصوات

      TtsVoice[]

      مصفوفة من عناصر tts.TtsVoice التي تمثّل الأصوات المتاحة لتجميع الكلام

المرتجعات

  • Promise&lt;TtsVoice[]&gt;

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

    لا تتوفّر الوعود إلا مع إصدار Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

isSpeaking()

وعود 
chrome.tts.isSpeaking(
  callback?: function,
)

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

المعلمات

  • رد الاتصال

    الدالة اختيارية

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

    (speaking: boolean) => void

    • يتحدث

      منطقي

      صواب إذا كنت تتحدث، وخطأ في الحالات الأخرى.

المرتجعات

  • Promise&lt;boolean&gt;

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

    لا تتوفّر الوعود إلا مع إصدار Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

pause()

chrome.tts.pause()

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

resume()

chrome.tts.resume()

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

speak()

وعود 
chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
)

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

المعلمات

  • النطق

    سلسلة

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

  • الخيارات

    TtsOptions اختيارية

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

  • رد الاتصال

    الدالة اختيارية

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

    () => void

المرتجعات

  • وعود <باطلة>

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

    لا تتوفّر الوعود إلا مع إصدار Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

stop()

chrome.tts.stop()

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

فعاليات

onVoicesChanged

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

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

المعلمات

  • رد الاتصال

    دالة

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

    () => void