chrome.ttsEngine

الوصف

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

الأذونات

ttsEngine

المفاهيم وطريقة الاستخدام

يمكن للإضافة تسجيل نفسها كمحرّك للخطاب. ومن خلال إجراء ذلك، يمكنه اعتراض بعض أو كل طلبات الربط بدوال مثل tts.speak() وtts.stop() وتقديم طريقة تنفيذ بديلة. يمكن للإضافات استخدام أي تقنية ويب متاحة لتوفير الكلام، بما في ذلك بث المحتوى الصوتي من خادم أو محتوى صوتي بتنسيق HTML5. يمكن أن تُجري الإضافة إجراءً مختلفًا بشأن الطلبات، مثل عرض مقاطع ترجمة وشرح في نافذة منبثقة أو إرسالها كرسائل سجلّ إلى خادم عن بُعد.

لتنفيذ محرك تحويل النص إلى كلام، يجب أن تذكر الإضافة إذن ttsEngine، ثم تذكر كل الأصوات التي تقدّمها في بيان الإضافة، على النحو التالي:

{
  "name": "My TTS Engine",
  "version": "1.0",
  "permissions": ["ttsEngine"],
  "tts_engine": {
    "voices": [
      {
        "voice_name": "Alice",
        "lang": "en-US",
        "event_types": ["start", "marker", "end"]
      },
      {
        "voice_name": "Pat",
        "lang": "en-US",
        "event_types": ["end"]
      }
    ]
  },
  "background": {
    "page": "background.html",
    "persistent": false
  }
}

يمكن أن تحدِّد الإضافة أي عدد من الأصوات.

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

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

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

بعد تحميل الإضافة، يمكنها استبدال قائمة الأصوات المعلَن عنها من خلال استدعاء chrome.ttsEngine.updateVoices. (يُرجى العِلم أنّ المَعلمات المستخدَمة في الطلب الآلي إلى updateVoices تكون بالتنسيق اللاتيني الكبير: على سبيل المثال، voiceName، على عكس ملف البيان الذي يستخدم voice_name.)

ملاحظة: إذا كان محرّك تحويل النص إلى كلام لا يتيح استخدام نوع الحدث 'end'، لا يمكن لمتصفّح Chrome إضافة الجمل إلى "قائمة الانتظار" لأنّه لا يمكنه معرفة وقت انتهاء الجملة. للمساعدة في تخفيف هذا التأثير، يُرسِل Chromeenqueue خيارًا منطقيًا إضافيًا إلى معالِج onSpeak في المحرّك، ما يمنحك خيار تنفيذ عملية وضع الطلبات في قائمة الانتظار. لا يُنصح بذلك لأنّه لا يمكن للعملاء بعد ذلك إضافة عبارات إلى "قائمة المحتوى التالي" ليتم نطقها باستخدام محركات تحويل نص إلى كلام مختلفة.

تتوافق أنواع الأحداث المحتمَلة التي يمكنك إرسالها مع أنواع الأحداث التي تتلقّاها طريقة speak():

• 'start': بدأ المحرّك بنطق الجملة.
• 'word': تم الوصول إلى حدود كلمة. استخدِم event.charIndex لتحديد موضع الكلام الحالي.
• 'sentence': تم الوصول إلى حدود الجملة. استخدِم event.charIndex لتحديد موضع العبارة الحالي.
• 'marker': تم الوصول إلى علامة SSML. استخدِم event.charIndex لتحديد موضع الكلام الحالي.
• 'end': انتهى المحرّك من قول الجملة.
• 'error': حدث خطأ في المحرّك ولا يمكن نطق هذه الجملة. يُرجى إرسال المزيد من المعلومات في event.errorMessage.

لا يُرسِل محرّك الكلام حدثَي 'interrupted' و'cancelled'، بل ينشئهما Chrome تلقائيًا.

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

التعامل مع أحداث الكلام

لإنشاء محتوى صوتي بناءً على طلب العملاء، يجب أن تسجِّل الإضافة مستمعين لكل من onSpeak وonStop، على النحو التالي:

const speakListener = (utterance, options, sendTtsEvent) => {
  sendTtsEvent({type: 'start', charIndex: 0})

  // (start speaking)

  sendTtsEvent({type: 'end', charIndex: utterance.length})
};

const stopListener = () => {
  // (stop all speech)
};

chrome.ttsEngine.onSpeak.addListener(speakListener);
chrome.ttsEngine.onStop.addListener(stopListener);

تحذير: إذا لم تسجِّل إضافتك مستمعين لكل من onSpeak وonStop، لن تتعذّر على الإضافة اعتراض أي طلبات معالجة للخطاب، بغض النظر عما هو مذكور في البيان.

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

الأنواع

AudioBuffer

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

المَعلمات التي تحتوي على ذاكرة تخزين مؤقت للصوت والبيانات المرتبطة بها

أماكن إقامة

• audioBuffer

  ArrayBuffer

  ذاكرة التخزين المؤقت للصوت من محرّك تحويل النص إلى كلام يجب أن يكون طوله بالضبط audioStreamOptions.bufferSize وأن يكون مُشفَّرًا بتنسيق أحادي الصوت بمعدّل audioStreamOptions.sampleRate، ويكون بتنسيق pcm خطي، ويكون بتنسيق عدد صحيح 32 بت، أي نوع Float32Array في JavaScript.

• charIndex

  رقم اختياري

  فهرس الأحرف المرتبط بذاكرة التخزين المؤقت للصوت هذه.

• isLastBuffer

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

  صحيح إذا كان هذا المخزن المؤقت للصوت هو الأخير للنص الذي يتم سماعه.

AudioStreamOptions

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

يحتوي على تنسيق بث الصوت المتوقّع أن ينتج عن محرّك.

أماكن إقامة

• bufferSize

  الرقم

  عدد العيّنات ضمن ذاكرة تخزين مؤقت للصوت

• sampleRate

  الرقم

  معدّل العينة المتوقّع في ذاكرة التخزين المؤقت للصوت

LanguageInstallStatus

في انتظار المراجعة

حالة تثبيت صوت

التعداد

"notInstalled"

"installing"

"تم التثبيت"

"تعذّر"

LanguageStatus

في انتظار المراجعة

حالة تثبيت لغة معيّنة

أماكن إقامة

• خطأ

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

  تفاصيل عن حالات تعذُّر التثبيت يتمّ تعبئتها اختياريًا في حال تعذّر تثبيت اللغة.

• installStatus

  LanguageInstallStatus

  حالة التثبيت

• lang

  سلسلة

  سلسلة اللغة بالتنسيق رمز اللغة-رمز المنطقة، حيث يمكن حذف المنطقة ومن الأمثلة على ذلك en وen-AU وzh-CH.

LanguageUninstallOptions

في انتظار المراجعة

خيارات إلغاء تثبيت لغة معيّنة

أماكن إقامة

• uninstallImmediately

  قيمة منطقية

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

SpeakOptions

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

الخيارات المحدّدة لطريقة tts.speak()‎

أماكن إقامة

• الجنس

  ‫VoiceGender اختياري

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

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

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

• lang

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

  اللغة التي سيتم استخدامها في عملية الإنشاء، على شكل اللغة-المنطقة أمثلة: ‎"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، بما في ذلك. عندما لا تتيح إحدى الأصوات هذا النطاق الكامل من الأسعار، يجب عدم عرض خطأ. بدلاً من ذلك، يمكنك اقتصاص معدّل السرعة إلى النطاق الذي يتيحه الصوت.

• voiceName

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

  اسم الصوت المطلوب استخدامه في عملية التركيب.

• الحجم

  رقم اختياري

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

TtsClient

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

معرّف العميل الذي يطلب معرفة الحالة

أماكن إقامة

• id

  سلسلة

  العميل يقدّم طلبًا لإدارة اللغة. بالنسبة إلى الإضافة، هذا هو المعرّف الفريد للإضافة. بالنسبة إلى ميزات Chrome، هذا هو الاسم السهل القراءة للميزة.

• المصدر

  TtsClientSource

  نوع مقدّم الطلب

TtsClientSource

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

نوع مقدّم الطلب

التعداد

"chromefeature"

"extension"

VoiceGender

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

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

التعداد

"male"

"female"

الطُرق

updateLanguage()

في انتظار المراجعة

chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
)

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

المعلمات

• status

  LanguageStatus

  حالة تثبيت اللغة

updateVoices()

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

chrome.ttsEngine.updateVoices(
  voices: TtsVoice[],
)

يتمّ استدعاء هذا الإجراء من قِبل محرّك لتعديل قائمة الأصوات. تلغي هذه القائمة أي أصوات تم الإعلان عنها في بيان هذه الإضافة.

المعلمات

• الأصوات

  TtsVoice[]

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

الفعاليات

onInstallLanguageRequest

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

chrome.ttsEngine.onInstallLanguageRequest.addListener(
  callback: function,
)

يتم تشغيله عندما يطلب عميل تحويل النص إلى كلام تثبيت لغة جديدة. من المفترض أن يحاول المحرّك تنزيل اللغة وتثبيتها، ثم استدعاء ttsEngine.updateLanguage مع النتيجة. في حال نجاح العملية، من المفترض أن يُطلِق المحرّك أيضًا ttsEngine.updateVoices لتسجيل الأصوات المتوفّرة حديثًا.

المعلمات

• ردّ الاتصال

  دالة

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

  (requestor: TtsClient, lang: string) => void

  • مقدِّم الطلب

    TtsClient

  • lang

    سلسلة

onLanguageStatusRequest

في انتظار المراجعة

chrome.ttsEngine.onLanguageStatusRequest.addListener(
  callback: function,
)

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

المعلمات

• ردّ الاتصال

  دالة

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

  (requestor: TtsClient, lang: string) => void

  • مقدِّم الطلب

    TtsClient

  • lang

    سلسلة

onPause

chrome.ttsEngine.onPause.addListener(
  callback: function,
)

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

المعلمات

• ردّ الاتصال

  دالة

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

  () => void

onResume

chrome.ttsEngine.onResume.addListener(
  callback: function,
)

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

المعلمات

• ردّ الاتصال

  دالة

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

  () => void

onSpeak

chrome.ttsEngine.onSpeak.addListener(
  callback: function,
)

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

المعلمات

• ردّ الاتصال

  دالة

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

  (utterance: string, options: SpeakOptions, sendTtsEvent: function) => void

  • عبارة

    سلسلة

  • الخيارات

    SpeakOptions

  • sendTtsEvent

    دالة

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

    (event: tts.TtsEvent) => void

    • حدث

      tts.TtsEvent

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

onSpeakWithAudioStream

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

chrome.ttsEngine.onSpeakWithAudioStream.addListener(
  callback: function,
)

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

المعلمات

• ردّ الاتصال

  دالة

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

  (utterance: string, options: SpeakOptions, audioStreamOptions: AudioStreamOptions, sendTtsAudio: function, sendError: function) => void

  • عبارة

    سلسلة

  • الخيارات

    SpeakOptions

  • audioStreamOptions

    AudioStreamOptions

  • sendTtsAudio

    دالة

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

    (audioBufferParams: AudioBuffer) => void

    • audioBufferParams

      AudioBuffer

      المَعلمات التي تحتوي على ذاكرة تخزين مؤقت للصوت والبيانات المرتبطة بها

  • sendError

    دالة

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

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

    (errorMessage?: string) => void

    • errorMessage

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

      سلسلة تصف الخطأ

onStop

chrome.ttsEngine.onStop.addListener(
  callback: function,
)

يتم تشغيله عند إجراء مكالمة إلى tts.stop وقد تكون هذه الإضافة في منتصف الكلام. إذا تلقّت الإضافة طلبًا للاتصال بـ onStop وكان قد سبق إيقاف الكلام، من المفترض ألا تتّخذ أي إجراء (وألّا تُظهِر خطأ). إذا كان الكلام في حالة الإيقاف المؤقت، من المفترض أن يؤدي ذلك إلى إلغاء حالة الإيقاف المؤقت.

المعلمات

• ردّ الاتصال

  دالة

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

  () => void

onUninstallLanguageRequest

في انتظار المراجعة

chrome.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

يتم تشغيله عندما يشير أحد عملاء تحويل النص إلى كلام إلى أنّه لم تعُد هناك حاجة إلى لغة معيّنة.

المعلمات

• ردّ الاتصال

  دالة

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

  (requestor: TtsClient, lang: string, uninstallOptions: LanguageUninstallOptions) => void

  • مقدِّم الطلب

    TtsClient

  • lang

    سلسلة

  • uninstallOptions

    LanguageUninstallOptions