chrome.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 من جدولة الجُمل المنتظرة في قائمة الانتظار.

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

ملاحظة: إذا كان محرّك تحويل النص إلى كلام لا يتوافق مع نوع الحدث 'end'، لن يتمكّن Chrome من وضع الجُمل في قائمة الانتظار لأنّه لا يمكنه معرفة وقت انتهاء الجملة. للمساعدة في الحدّ من هذه المشكلة، يمرِّر Chrome خيارًا إضافيًا من النوع المنطقي enqueue إلى معالج 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

  number اختيارية

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

• isLastBuffer

  boolean اختياري

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

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

  قيمة منطقية

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

SpeakOptions

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

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

الخصائص

• الجنس

  VoiceGender اختيارية

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

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

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

• 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، بما في ذلك هذان الرقمَان. عندما لا يدعم الصوت هذا النطاق الكامل من المعدّلات، لا تعرض خطأ. بدلاً من ذلك، يمكنك قص المعدّل إلى النطاق الذي يدعمه الصوت.

• 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 لتسجيل الصوت.

المعلمات

• status

  LanguageStatus

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

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,
)

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

المعلمات

• callback

  دالة

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

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

  • مقدّم الطلب

    TtsClient

  • lang

    سلسلة

  • uninstallOptions

    LanguageUninstallOptions