chrome.ttsEngine

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم واجهة برمجة التطبيقات 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 تكون بتنسيق Camel Case: على سبيل المثال، 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

  قيمة منطقية اختيارية

  صحيح إذا كان مخزن الصوت المؤقت هذا هو الأخير للنص الذي يتم قوله.

AudioStreamOptions

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

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

الخصائص

• bufferSize

  الرقم

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

• sampleRate

  الرقم

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

LanguageInstallStatus

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

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

Enum

"notInstalled"

"installing"

"installed"

"failed"

LanguageStatus

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

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

الخصائص

• خطأ

  string اختياري

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

• installStatus

  LanguageInstallStatus

  حالة التثبيت

• lang

  سلسلة

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

LanguageUninstallOptions

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

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

الخصائص

• uninstallImmediately

  قيمة منطقية

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

SpeakOptions

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

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

الخصائص

• الجنس

  VoiceGender اختيارية

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

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

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

• lang

  string اختياري

  اللغة التي سيتم استخدامها في التركيب، بالتنسيق language-region. أمثلة: "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

  string اختياري

  اسم الصوت المطلوب استخدامه في التركيب

• الحجم

  number اختيارية

  مستوى صوت الكلام بين 0 و1 ضِمنًا، حيث يمثّل 0 أدنى مستوى و1 أعلى مستوى، والقيمة التلقائية هي 1.0.

TtsClient

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

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

الخصائص

• id

  سلسلة

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

• المصدر

  TtsClientSource

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

TtsClientSource

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

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

Enum

"chromefeature"

"extension"

VoiceGender

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

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

Enum

"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

  • utterance

    سلسلة

  • الخيارات

    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

  • utterance

    سلسلة

  • الخيارات

    SpeakOptions

  • audioStreamOptions

    AudioStreamOptions

  • sendTtsAudio

    دالة

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

    (audioBufferParams: AudioBuffer) => void

    • audioBufferParams

      AudioBuffer

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

  • sendError

    دالة

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

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

    (errorMessage?: string) => void

    • errorMessage

      string اختياري

      سلسلة تصف الخطأ

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