chrome.ttsEngine (original) (raw)

الوصف

استخدِم واجهة برمجة التطبيقات 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 والإصدارات الأحدث

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

الخصائص

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

AudioStreamOptions

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

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

الخصائص

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

LanguageInstallStatus

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

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

Enum

"notInstalled"

"installing"

"تم التثبيت"

"تعذّر"

LanguageStatus

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

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

الخصائص

• تفاصيل عن حالات تعذُّر التثبيت يتمّ تعبئتها اختياريًا في حال تعذّر تثبيت اللغة.
• حالة التثبيت
• سلسلة اللغة بالتنسيق رمز اللغة-رمز المنطقة، حيث يمكن حذف المنطقة ومن الأمثلة على ذلك en وen-AU وzh-CH.

LanguageUninstallOptions

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

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

الخصائص

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

SpeakOptions

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

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

الخصائص

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

TtsClient

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

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

الخصائص

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

TtsClientSource

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

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

Enum

"chromefeature"

"extension"

VoiceGender

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

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

Enum

الطُرق

updateLanguage()

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

chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
): void

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

المعلمات

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

updateVoices()

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

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

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

المعلمات

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

الفعاليات

onInstallLanguageRequest

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

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

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

المعلمات

• تظهر المَعلمة callback على النحو التالي:
  (requestor: TtsClient, lang: string) => void

onLanguageStatusRequest

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

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

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

المعلمات

• تظهر المَعلمة callback على النحو التالي:
  (requestor: TtsClient, lang: string) => void

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
  • تظهر المَعلمة sendTtsEvent على النحو التالي:
    (event: tts.TtsEvent) => void
    * الحدث من محرّك تحويل النص إلى كلام الذي يشير إلى حالة هذا التعبير.

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
  • تظهر المَعلمة sendTtsAudio على النحو التالي:
    (audioBufferParams: AudioBuffer) => void
    * المَعلمات التي تحتوي على ذاكرة تخزين مؤقت للصوت والبيانات المرتبطة بها
  • Chrome 94 والإصدارات الأحدث
    تظهر المَعلمة sendError على النحو التالي:
    (errorMessage?: string) => void
    * errorMessage
    سلسلة اختيارية
    سلسلة تصف الخطأ

onStop

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

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

المعلمات

• تظهر المَعلمة callback على النحو التالي:
  () => void

onUninstallLanguageRequest

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

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

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

المعلمات

• تظهر المَعلمة callback على النحو التالي:
  (requestor: TtsClient, lang: string, uninstallOptions: LanguageUninstallOptions) => void