chrome.ttsEngine

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأذونات

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

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

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

الخصائص

  • audioBuffer

    ArrayBuffer

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

  • charIndex

    number اختياري

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

  • isLastBuffer

    boolean اختياري

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

AudioStreamOptions

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

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

الخصائص

  • bufferSize

    الرقم

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

  • sampleRate

    الرقم

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

LanguageInstallStatus

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

تمثّل هذه السمة حالة تثبيت صوت.

تعداد

"notInstalled"

"installing"

"installed"

"تعذّر"

LanguageStatus

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

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

الخصائص

  • خطأ

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

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

  • installStatus

    LanguageInstallStatus

    حالة التثبيت

  • lang

    سلسلة

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

LanguageUninstallOptions

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

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

الخصائص

  • uninstallImmediately

    قيمة منطقية

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

SpeakOptions

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

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

الخصائص

  • الجنس

    ‫VoiceGender اختيارية

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

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

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

  • 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

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

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

الخصائص

  • id

    سلسلة

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

  • المصدر

    TtsClientSource

    تمثّل هذه السمة نوع مقدّم الطلب.

TtsClientSource

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

تمثّل هذه السمة نوع مقدّم الطلب.

تعداد

"chromefeature"

"extension"

VoiceGender

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

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

تعداد

"male"

"female"

الطُرق

updateLanguage()

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

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

المعلمات

updateVoices()

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

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

المعلمات

  • الأصوات

    TtsVoice[]

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

الفعاليات

onInstallLanguageRequest

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

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

المعلمات

  • callback

    دالة

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

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

    • مقدّم الطلب

      TtsClient

    • lang

      سلسلة

onLanguageStatusRequest

‫Chrome 132 والإصدارات الأحدث 
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

Chrome 92 والإصدارات الأحدث 
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

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

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

المعلمات