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);
    }
  }
);

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

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

للحصول على مزيد من المعلومات في الوقت الفعلي عن حالة الكلام المركَّب، يمكنك تمرير متتبِّع أحداث في الخيارات إلى 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

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

Enum

"start"

"end"

"word"

"sentence"

"marker"

"interrupted"

"cancelled"

"error"

"pause"

"resume"

TtsEvent

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

الخصائص

• charIndex

  number اختيارية

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

• errorMessage

  string اختياري

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

• length

  number اختيارية

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

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

• النوع

  EventType

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

TtsOptions

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

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

الخصائص

• desiredEventTypes

  string[] اختياري

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

• enqueue

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

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

• extensionId

  string اختياري

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

• الجنس

  VoiceGender اختيارية

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

• requiredEventTypes

  string[] اختياري

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

• voiceName

  string اختياري

  اسم الصوت المطلوب استخدامه في التركيب في حال ترك هذا الحقل فارغًا، يتم استخدام أي صوت متاح.

• الحجم

  number اختيارية

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

• onEvent

  void اختياري

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

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

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

  • حدث

    TtsEvent

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

TtsVoice

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

الخصائص

• eventTypes

  ‫EventType[] اختيارية

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

• extensionId

  string اختياري

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

• الجنس

  VoiceGender اختيارية

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

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

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

• lang

  string اختياري

  اللغة التي يتوافق معها هذا الصوت، بالتنسيق language-region. أمثلة: "en" و"en-US" و"en-GB" و"zh-CN".

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

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

  إذا كانت القيمة "صحيح"، يكون محرّك التركيب موردًا لشبكة عن بُعد. قد يكون وقت الاستجابة أطول وقد يتم تحصيل تكاليف مقابل معدل نقل البيانات.

• voiceName

  string اختياري

  اسم الصوت

VoiceGender

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

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

Enum

"male"

"female"

الطُرق

getVoices()

Promise

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

تحصل على مصفوفة من جميع الأصوات المتاحة.

المعلمات

• callback

  function اختياري

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

  (voices: TtsVoice[]) => void

  • الأصوات

    TtsVoice[]

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

المرتجعات

• Promise<TtsVoice[]>

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

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

isSpeaking()

Promise

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

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

المعلمات

• callback

  function اختياري

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

  (speaking: boolean) => void

  • التحدّث

    قيمة منطقية

    صحيح إذا كان يتحدث، وخطأ في الحالات الأخرى.

المرتجعات

• Promise<boolean>

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

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

pause()

chrome.tts.pause(): void

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

resume()

chrome.tts.resume(): void

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

speak()

Promise

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

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

المعلمات

• utterance

  سلسلة

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

• الخيارات

  TtsOptions اختياري

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

• callback

  function اختياري

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

  () => 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