browser.ttsEngine

الوصف

استخدِم واجهة برمجة التطبيقات chrome.ttsEngine لتنفيذ محرّك تحويل النص إلى كلام(TTS) باستخدام إضافة. إذا سجّلت الإضافة باستخدام واجهة برمجة التطبيقات هذه، ستتلقّى أحداثًا تحتوي على عبارة ليتم نطقها ومَعلمات أخرى عندما تستخدم أي إضافة أو تطبيق 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 من جدولة الجُمل المنطوقة في قائمة الانتظار.

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

تتطابق أنواع الأحداث المحتملة التي يمكنك إرسالها مع أنواع الأحداث التي تتلقّاها الطريقة 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)
};

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

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

الأنواع

AudioBuffer

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

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

الخصائص

  • audioBuffer

    ArrayBuffer

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

  • charIndex

    number اختياري

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

  • isLastBuffer

    boolean اختياري

    تعرض القيمة "صحيح" إذا كان مخزن الصوت المؤقت هذا هو الأخير للنص الذي يتم التحدث به.

AudioStreamOptions

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

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

الخصائص

  • bufferSize

    الرقم

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

  • sampleRate

    الرقم

    معدّل البيانات المتوقّع في مخزن مؤقت للصوت

LanguageInstallStatus

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

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

تعداد

"notInstalled"

"installing"

"installed"

"تعذّر"

LanguageStatus

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

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

الخصائص

  • خطأ

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

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

  • installStatus

    LanguageInstallStatus

    حالة التثبيت

  • lang

    سلسلة

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

LanguageUninstallOptions

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

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

الخصائص

  • uninstallImmediately

    قيمة منطقية

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

SpeakOptions

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

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

الخصائص

  • الجنس

    ‫VoiceGender اختيارية

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

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

    جنس الصوت المستخدَم في الكلام المركَّب

  • lang

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

    اللغة التي سيتم استخدامها في التوليف، بالتنسيق اللغة-المنطقة أمثلة: "ar" و"ar-SA" و"ar-AE" و"zh-CN".

  • رمية

    number اختياري

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

  • المعدّل

    number اختياري

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

  • voiceName

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

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

  • الحجم

    number اختياري

    مستوى الصوت بين 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()

الإصدار 132 من Chrome والإصدارات الأحدث 
chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
): void

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

المعلمات

updateVoices()

الإصدار 66 من Chrome والإصدارات الأحدث 
chrome.ttsEngine.updateVoices(
  voices: TtsVoice[],
): void

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

المعلمات

  • الأصوات

    TtsVoice[]

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

الفعاليات

onInstallLanguageRequest

الإصدار 131 من Chrome والإصدارات الأحدث 
chrome.ttsEngine.onInstallLanguageRequest.addListener(
  callback: function,
)

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

المعلمات

  • callback

    دالة

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

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

    • مقدّم الطلب

      TtsClient

    • lang

      سلسلة

onLanguageStatusRequest

الإصدار 132 من Chrome والإصدارات الأحدث 
chrome.ttsEngine.onLanguageStatusRequest.addListener(
  callback: function,
)

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

المعلمات

  • callback

    دالة

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

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

    • مقدّم الطلب

      TtsClient

    • lang

      سلسلة

onPause

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

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

المعلمات

  • callback

    دالة

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

    () => void

onResume

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

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

المعلمات

  • callback

    دالة

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

    () => void

onSpeak

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة 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 يوفّر خدمات تشغيل الصوت ويتعامل مع إرسال أحداث تحويل النص إلى كلام.

المعلمات

  • callback

    دالة

    تظهر المَعلمة 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

    دالة

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

    () => void

onUninstallLanguageRequest

الإصدار 132 من Chrome والإصدارات الأحدث 
chrome.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

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

المعلمات