chrome.tts

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأذونات

tts

نظرة عامة

يتوافق Chrome تلقائيًا مع الكلام على أجهزة Windows (باستخدام SAPI 5) وMac OS X وChromeOS، وذلك باستخدام إمكانات تركيب الكلام التي يوفّرها نظام التشغيل. على جميع الأنظمة الأساسية، يمكن للمستخدم تثبيت إضافات تسجّل نفسها كمحركات بديلة للتعرّف على الكلام.

إنشاء الكلام

اتّصِل بالرقم speak() من الإضافة للتحدّث. على سبيل المثال:

chrome.tts.speak('Hello, world.');

لإيقاف التحدّث على الفور، ما عليك سوى الاتصال بالرقم stop():

chrome.tts.stop();

يمكنك تقديم خيارات تتحكّم في خصائص مختلفة للكلام، مثل سرعته ونبرته وغير ذلك. على سبيل المثال:

chrome.tts.speak('Hello, world.', {'rate': 2.0});

من المستحسن أيضًا تحديد اللغة ليتم اختيار برنامج تركيب صوتي يتوافق مع تلك اللغة (واللهجة الإقليمية، إذا كان ذلك منطبقًا).

chrome.tts.speak('Hello, world.', {'lang': 'en-US', 'rate': 2.0});

بشكلٍ تلقائي، يؤدي كل طلب إلى speak() إلى مقاطعة أي كلام جارٍ والتحدث على الفور. لتحديد ما إذا كانت المكالمة ستتسبّب في مقاطعة أي شيء، يمكنك الاتصال بالرقم isSpeaking(). بالإضافة إلى ذلك، يمكنك استخدام الخيار enqueue لإضافة هذه الجملة إلى قائمة انتظار من الجمل التي سيتم نطقها عند الانتهاء من الجملة الحالية.

chrome.tts.speak('Speak this first.');
chrome.tts.speak(
    'Speak this next, when the first sentence is done.', {'enqueue': true});

يمكنك الاطّلاع على وصف كامل لجميع الخيارات في tts.speak أدناه. لن تتوافق بعض محركات تحويل الكلام إلى نص مع جميع الخيارات.

لرصد الأخطاء والتأكّد من أنّك تستدعي speak() بشكل صحيح، مرِّر دالّة رد الاتصال لا تأخذ أي وسيطات. داخل دالة الاستدعاء، تحقَّق من runtime.lastError لمعرفة ما إذا حدثت أي أخطاء.

chrome.tts.speak(
  utterance,
  options,
  function() {
    if (chrome.runtime.lastError) {
      console.log('Error: ' + chrome.runtime.lastError.message);
    }
  }
);

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

الاستماع إلى الأحداث

للحصول على مزيد من المعلومات في الوقت الفعلي حول حالة الكلام المركّب، مرِّر متتبِّع الأحداث في الخيارات إلى speak()، على النحو التالي:

chrome.tts.speak(
  utterance,
  {
    onEvent: function(event) {
      console.log('Event ' + event.type + ' at position ' + event.charIndex);
      if (event.type == 'error') {
        console.log('Error: ' + event.errorMessage);
      }
    }
  },
  callback
);

يتضمّن كل حدث نوع الحدث وفهرس الحرف الخاص بالكلام الحالي بالنسبة إلى الجملة، بالإضافة إلى رسالة خطأ اختيارية لأحداث الخطأ. أنواع الأحداث هي:

  • ‫'start': بدأ المحرّك بنطق العبارة.
  • ‫'word': تم بلوغ حدّ الكلمة. استخدِم event.charIndex لتحديد موضع الكلام الحالي.
  • ‫'sentence': تم بلوغ نهاية الجملة. استخدِم event.charIndex لتحديد موضع الكلام الحالي.
  • ‫'marker': تم الوصول إلى علامة SSML. استخدِم event.charIndex لتحديد موضع الكلام الحالي.
  • ‫'end': يشير إلى أنّ المحرّك انتهى من نطق العبارة.
  • 'interrupted': تمّت مقاطعة هذه العبارة من خلال طلب آخر إلى speak() أو stop() ولم تنتهِ.
  • ‫'cancelled': تم وضع هذه العبارة في قائمة الانتظار، ولكن تم إلغاؤها بعد ذلك من خلال طلب آخر إلى speak() أو stop() ولم يتم بدء نطقها على الإطلاق.
  • ‫'error': حدث خطأ خاص بمحرك معيّن ولا يمكن نطق هذه العبارة. يُرجى الاطّلاع على event.errorMessage لمزيد من التفاصيل.

أربعة من أنواع الأحداث، وهي 'end' و'interrupted' و'cancelled' و'error'، هي نهائية. بعد تلقّي أحد هذه الأحداث، لن يتم نطق هذا الردّ ولن يتم تلقّي أي أحداث جديدة منه.

قد لا تتوافق بعض الأصوات مع جميع أنواع الأحداث، وقد لا ترسل بعض الأصوات أي أحداث على الإطلاق. إذا كنت لا تريد استخدام صوت ما إلا إذا كان يرسل أحداثًا معيّنة، مرِّر الأحداث التي تحتاج إليها في العنصر requiredEventTypes من عنصر الخيارات، أو استخدِم getVoices() لاختيار صوت يستوفي متطلباتك. تم توثيقهما أدناه.

ترميز SSML

قد تتضمّن العبارات المستخدَمة في واجهة برمجة التطبيقات هذه ترميزًا باستخدام لغة ترميز تركيب الكلام (SSML). في حال استخدام SSML، يجب أن تكون الوسيطة الأولى للدالة speak() مستند SSML كاملاً يتضمّن عنوان XML وعلامة <speak> ذات مستوى أعلى، وليس جزءًا من مستند.

على سبيل المثال:

chrome.tts.speak(
  '<?xml version="1.0"?>' +
  '<speak>' +
  '  The <emphasis>second</emphasis> ' +
  '  word of this sentence was emphasized.' +
  '</speak>'
);

لن تتوافق بعض محركات تحويل النص إلى كلام مع جميع علامات SSML، وقد لا تتوافق بعضها مع SSML على الإطلاق، ولكن يجب أن تتجاهل جميع المحركات أي علامات SSML غير متوافقة معها وأن تواصل نطق النص الأساسي.

اختيار صوت

يختار Chrome تلقائيًا الصوت الأنسب لكل عبارة تريد التحدّث بها، وذلك استنادًا إلى اللغة. على معظم أنظمة التشغيل Windows وMac OS X وChromeOS، من المفترض أن تتمكّن ميزة تركيب الكلام التي يوفّرها نظام التشغيل من قراءة أي نص بلغة واحدة على الأقل. قد يتوفّر لبعض المستخدمين مجموعة متنوعة من الأصوات من نظام التشغيل ومن محركات تحويل النص إلى كلام التي تنفّذها إضافات Chrome الأخرى. في هذه الحالات، يمكنك تنفيذ رمز مخصّص لاختيار الصوت المناسب أو لتقديم قائمة خيارات للمستخدم.

للحصول على قائمة بجميع الأصوات، استدعِ getVoices() ومرِّر إليها دالة تتلقّى مصفوفة من عناصر TtsVoice كوسيطة:

chrome.tts.getVoices(
  function(voices) {
    for (var i = 0; i < voices.length; i++) {
      console.log('Voice ' + i + ':');
      console.log('  name: ' + voices[i].voiceName);
      console.log('  lang: ' + voices[i].lang);
      console.log('  extension id: ' + voices[i].extensionId);
      console.log('  event types: ' + voices[i].eventTypes);
    }
  }
);

الأنواع

EventType

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

تعداد

"start"

"end"

"word"

"sentence"

"marker"

"interrupted"

"cancelled"

"error"

"pause"

"resume"

TtsEvent

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

الخصائص

  • charIndex

    number اختياري

    فهرس الحرف الحالي في الجملة المنطوقة بالنسبة إلى أحداث الكلمات، يتم تشغيل الحدث في نهاية كلمة واحدة وقبل بداية الكلمة التالية. يمثّل الرمز charIndex نقطة في النص في بداية الكلمة التالية التي سيتم نطقها.

  • errorMessage

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

    وصف الخطأ، إذا كان نوع الحدث error

  • length

    number اختياري

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

    تمثّل هذه السمة طول الجزء التالي من الجملة. على سبيل المثال، في حدث word، يمثّل هذا الحقل طول الكلمة التي سيتم نطقها بعد ذلك. سيتم ضبطها على -1 إذا لم يتم ضبطها من خلال محرّك تحويل الكلام إلى نص.

  • النوع

    EventType

    يمكن أن يكون النوع start عند بدء الكلام، أو word عند الوصول إلى حدود الكلمات، أو sentence عند الوصول إلى حدود الجمل، أو marker عند الوصول إلى عنصر علامة SSML، أو end عند الوصول إلى نهاية الجملة، أو interrupted عند إيقاف الجملة أو مقاطعتها قبل الوصول إلى نهايتها، أو cancelled عند إزالتها من قائمة الانتظار قبل تركيبها، أو error عند حدوث أي خطأ آخر. عند إيقاف الكلام مؤقتًا، يتم إطلاق الحدث pause إذا تم إيقاف جملة معيّنة مؤقتًا في منتصفها، والحدث resume إذا تم استئناف الكلام. يُرجى العِلم أنّه قد لا يتم تشغيل أحداث الإيقاف المؤقت والاستئناف إذا تم إيقاف الكلام مؤقتًا بين الجُمل.

TtsOptions

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

خيارات الكلام لمشغّل تحويل النص إلى كلام

الخصائص

  • desiredEventTypes

    string[] اختياري

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

  • إضافة إلى قائمة الانتظار

    boolean اختياري

    إذا كانت القيمة صحيحة، يتم وضع هذا النص في قائمة الانتظار إذا كان تحويل النص إلى كلام قيد التنفيذ. إذا كانت القيمة false (وهي القيمة التلقائية)، سيتم إيقاف أي كلام حالي وإفراغ قائمة انتظار الكلام قبل نطق هذه الجملة الجديدة.

  • extensionId

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

    معرّف إضافة محرّك الكلام المطلوب استخدامه، إذا كان معروفًا

  • الجنس

    ‫VoiceGender اختيارية

    تم إيقافها نهائيًا منذ الإصدار 77 من 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، ولكن العديد من الأصوات ستفرض قيودًا إضافية على الحد الأدنى والحد الأقصى للمعدلات، على سبيل المثال، قد لا يتحدث صوت معيّن أسرع من 3 مرات من السرعة العادية حتى إذا حددت قيمة أكبر من 3.0.

  • requiredEventTypes

    string[] اختياري

    أنواع أحداث تحويل النص إلى كلام التي يجب أن يدعمها الصوت

  • voiceName

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

    تمثّل هذه السمة اسم الصوت المطلوب استخدامه في عملية التوليف. في حال تركها فارغة، يتم استخدام أي صوت متاح.

  • الحجم

    number اختياري

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

  • onEvent

    void اختياري

    يتم استدعاء هذه الدالة مع الأحداث التي تحدث أثناء نطق العبارة.

    تبدو الدالة onEvent على النحو التالي: 

    (event: TtsEvent) => {...}

    • حدث

      TtsEvent

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

TtsVoice

وصف لصوت متاح لتركيب الكلام

الخصائص

  • eventTypes

    EventType[] اختيارية

    جميع أنواع أحداث معاودة الاتصال التي يمكن لهذا الصوت إرسالها.

  • extensionId

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

    معرّف الإضافة التي توفّر هذا الصوت

  • الجنس

    ‫VoiceGender اختيارية

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

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

    جنس صاحب هذا الصوت

  • lang

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

    اللغة التي يتوافق معها هذا الصوت، بالتنسيق اللغة-المنطقة أمثلة: "ar" و"ar-SA" و"ar-AE" و"zh-CN".

  • جهاز تحكّم عن بُعد

    boolean اختياري

    إذا كانت القيمة صحيحة، يكون محرّك التوليف مصدرًا بعيدًا على الشبكة. قد يؤدي ذلك إلى زيادة وقت الاستجابة وقد يتم تحصيل رسوم منك مقابل معدل نقل البيانات.

  • voiceName

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

    اسم الصوت

VoiceGender

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

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

تعداد

"male"

"female"

الطُرق

getVoices()

وعد 
chrome.tts.getVoices(
  callback?: function,
): Promise<TtsVoice[]>

تعرض هذه السمة مصفوفة تتضمّن جميع الأصوات المتاحة.

المعلمات

  • callback

    الدالة اختيارية

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

    (voices: TtsVoice[]) => void

    • الأصوات

      TtsVoice[]

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

المرتجعات

  • Promise<TtsVoice[]>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

isSpeaking()

وعد 
chrome.tts.isSpeaking(
  callback?: function,
): Promise<boolean>

تتحقّق هذه السمة مما إذا كان المحرّك يتحدث حاليًا. على نظام التشغيل Mac OS X، تكون النتيجة صحيحة عندما يكون محرّك تحويل النص إلى كلام في النظام يتحدث، حتى إذا لم يبدأ Chrome عملية تحويل النص إلى كلام.

المعلمات

  • callback

    الدالة اختيارية

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

    (speaking: boolean) => void

    • التحدّث

      قيمة منطقية

      يتم عرض القيمة "صحيح" إذا كان المستخدم يتحدث، و"خطأ" في الحالات الأخرى.

المرتجعات

  • Promise<boolean>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

pause()

chrome.tts.pause(): void

توقِف عملية تركيب الكلام مؤقتًا، ربما في منتصف الجملة سيؤدي إجراء مكالمة لاستئناف الكلام أو إيقافه إلى إلغاء الإيقاف المؤقت للكلام.

resume()

chrome.tts.resume(): void

إذا تم إيقاف الكلام مؤقتًا، يستأنف الكلام من حيث توقّف.

speak()

وعد 
chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
): Promise<void>

تتحدث باستخدام محرّك تحويل النص إلى كلام.

المعلمات

  • عبارة

    سلسلة

    النص المطلوب تحويله إلى كلام، سواء كان نصًا عاديًا أو مستند SSML كاملاً ومنسَّقًا بشكل جيد ستزيل محركات تحويل النص إلى كلام التي لا تتوافق مع SSML العلامات وتتلو النص. يبلغ الحد الأقصى لطول النص 32,768 حرفًا.

  • الخيارات

    TtsOptions اختيارية

    خيارات الكلام

  • callback

    الدالة اختيارية

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

    () => void

المرتجعات

  • Promise<void>

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

    يتم حلّها على الفور قبل انتهاء الكلام. في حال حدوث خطأ، سيتم رفض الوعد. استخدِم options.onEvent للحصول على ملاحظات أكثر تفصيلاً.

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

stop()

chrome.tts.stop(): void

يوقف أي كلام حالي ويمحو قائمة الانتظار لأي عبارات معلّقة. بالإضافة إلى ذلك، إذا تم إيقاف الكلام مؤقتًا، ستتم إعادة تشغيله الآن للمكالمة التالية.

الفعاليات

onVoicesChanged

الإصدار 124 من Chrome والإصدارات الأحدث 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

يتم استدعاؤها عندما تتغير قائمة tts.TtsVoice التي سيتم عرضها من خلال getVoices.

المعلمات

  • callback

    دالة

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

    () => void