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

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

الأنواع

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

المعلمات

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

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

المعلمات