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);
    }
  }
);

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

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

للحصول على مزيد من المعلومات في الوقت الفعلي حول حالة الكلام المركَّب، مرِّر أداة معالجة الحدث في الخيارات إلى 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

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

التعداد

"end"

TtsEvent

حدث من محرك تحويل النص إلى كلام للإعلان عن حالة الكلام.

أماكن إقامة

  • charIndex

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

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

  • errorMessage

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

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

  • length

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

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

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

  • كتابة

    EventType

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

TtsOptions

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

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

أماكن إقامة

  • desiredEventTypes

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

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

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

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

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

  • extensionId

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

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

  • gender

    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 أسرع بمرتين، و0.5 أسرع بنصف السرعة. القيم التي تقل عن 0.1 أو أعلى من 10.0 غير مسموح بها إطلاقًا، إلا أن العديد من الأصوات ستفرض قيودًا على الحد الأدنى والأقصى للمعدلات بشكل أكبر، على سبيل المثال، قد لا يتحدث صوت معيَّن بشكل أسرع من 3 مرات في الواقع حتى إذا حددت قيمة أكبر من 3.0.

  • requiredEventTypes

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

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

  • voiceName

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

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

  • الحجم

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

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

  • onEvent

    باطل اختياري

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

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

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

    • حدث

      TtsEvent

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

TtsVoice

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

أماكن إقامة

  • eventTypes

    EventType[] اختيارية

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

  • extensionId

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

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

  • gender

    VoiceGender اختيارية

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

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

    جنس هذا الصوت

  • lang

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

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

  • عمل عن بُعد

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

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

  • voiceName

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

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

VoiceGender

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

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

التعداد

الطُرق

getVoices()

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

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

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (voices: TtsVoice[])=>void

    • الأصوات

      TtsVoice[]

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

المرتجعات

  • Promise<TtsVoice[]>

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

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

isSpeaking()

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

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

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (speaking: boolean)=>void

    • يتحدث

      boolean

      True في حالة التحدث، أو false في الحالات الأخرى.

المرتجعات

  • Promise<boolean>

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

    تتوفّر الوعود في إصدار 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

المرتجعات

  • Promise<void>

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

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

stop()

chrome.tts.stop()

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

فعاليات

onVoicesChanged

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    ()=>void