الوصف
استخدِم واجهة برمجة تطبيقات chrome.tts
لتشغيل تقنية "تحويل النص إلى كلام" (TTS). يمكنك أيضًا الاطّلاع على واجهة برمجة التطبيقات ttsEngine
ذات الصلة، والتي تسمح للإضافة بتنفيذ محرّك كلام.
ويوفّر Chrome هذه الإمكانية على Windows (باستخدام SAPI 5) وMac OS X وChromeOS، باستخدام إمكانيات تجميع الكلام التي يوفّرها نظام التشغيل. على جميع الأنظمة الأساسية، يمكن للمستخدم تثبيت الإضافات التي تُسجِّل نفسه كمحركات كلام بديلة.
الأذونات
tts
المفاهيم والاستخدام
إنشاء كلام
يمكنك الاتصال بالرقم 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، وليس اكتشاف جميع الأخطاء المحتملة التي قد تحدث في عملية تجميع وإخراج الكلام. لاكتشاف هذه الأخطاء أيضًا، تحتاج إلى استخدام أداة معالجة الحدث، كما هو موضح في القسم التالي.
الاستماع إلى الأحداث
للحصول على مزيد من المعلومات في الوقت الفعلي حول حالة الكلام المركَّب، مرِّر أداة معالجة الحدث في الخيارات إلى 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
التعداد
"end"
TtsEvent
حدث من محرك تحويل النص إلى كلام للإعلان عن حالة الكلام.
أماكن إقامة
-
charIndex
الرقم اختياري
فهرس الحرف الحالي في اللفظ. بالنسبة إلى أحداث الكلمات، يتم تنشيط الحدث في نهاية كلمة وقبل بداية الكلمة التالية. تمثل العلامة
charIndex
نقطة في النص في بداية الكلمة التالية المراد قولها. -
errorMessage
سلسلة اختيارية
وصف الخطأ إذا كان نوع الحدث
error
. -
length
الرقم اختياري
الإصدار 74 من Chrome والإصدارات الأحدثتمثّل هذه السمة طول الجزء التالي من الكلام. على سبيل المثال، في حدث
word
، هذا هو طول الكلمة التي سيتم قولها بعد ذلك. سيتم ضبطه على -1 إذا لم يتم ضبطه من خلال محرّك الكلام. -
كتابة
يمكن أن يكون النوع
start
بعد بدء الكلام، أوword
عند الوصول إلى حد الكلمة، أوsentence
عند الوصول إلى حد الجملة، أوmarker
عند الوصول إلى عنصر علامة SSML، أوend
عند الوصول إلى نهاية العبارة، أوinterrupted
عند إيقاف الكلام أو مقاطعته قبل الوصول إليه، أوcancelled
عند إزالته من قائمة الانتظار قبل أن يتم تجميعه، أوerror
عند حدوث أي خطأ آخر. عند إيقاف الكلام مؤقتًا، يتم تنشيط حدثpause
إذا توقّف كلام معيّن مؤقتًا في المنتصف، وresume
إذا استأنف كلام الكلام الكلام. تجدر الإشارة إلى أنّه قد لا يتم تنشيط أحداث الإيقاف المؤقت والاستئناف في حال إيقاف الكلام مؤقتًا بين الكلمات.
TtsOptions
خيارات الكلام في محرك تحويل النص إلى كلام
أماكن إقامة
-
desiredEventTypes
سلسلة[] اختيارية
أنواع أحداث تحويل النص إلى كلام التي تهتم بالاستماع إليها. وفي حال عدم توفّر هذه الأحداث، يمكن إرسال جميع أنواع الأحداث.
-
إدراج في قائمة الانتظار
منطقية اختيارية
إذا كانت الإجابة "صحيح"، يتم إدراج هذا اللفظ في قائمة الانتظار إذا كان تحويل النص إلى كلام قيد التنفيذ. في حال اختيار القيمة "false" (الخيار التلقائي)، ستتم مقاطعة أي كلام حالي ومحو قائمة انتظار الكلام قبل قول هذا الكلام الجديد.
-
extensionId
سلسلة اختيارية
تمثّل هذه السمة رقم تعريف الإضافة لمحرّك الكلام المطلوب استخدامه، إذا كان معروفًا.
-
gender
VoiceGender اختيارية
تم إيقافه منذ إصدار 77 من Chromeتم إيقاف سمة "الجنس" نهائيًا وسيتم تجاهلها.
جنس الصوت للكلام المركَّب.
-
lang
سلسلة اختيارية
تمثّل هذه السمة اللغة المطلوب استخدامها في التركيب، وتكون بالتنسيق language-region. أمثلة: "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 غير مسموح بها إطلاقًا، إلا أن العديد من الأصوات ستفرض قيودًا على الحد الأدنى والأقصى للمعدلات بشكل أكبر، على سبيل المثال، قد لا يتحدث صوت معيَّن بشكل أسرع من 3 مرات في الواقع حتى إذا حددت قيمة أكبر من 3.0.
-
requiredEventTypes
سلسلة[] اختيارية
أنواع أحداث تحويل النص إلى كلام التي يجب أن يتوافق الصوت معها.
-
voiceName
سلسلة اختيارية
اسم الصوت المستخدم في عملية التركيب. في حال ترك الحقل فارغًا، يتم استخدام أي صوت متاح.
-
الحجم
الرقم اختياري
مستوى صوت التحدث بين 0 و1 بشكل شامل، حيث يشير الرقم 0 إلى أدنى مستوى و1 يمثل أعلى مستوى، ويكون العدد التلقائي 1.0.
-
onEvent
باطل اختياري
يتم استدعاء هذه الدالة مع الأحداث التي تحدث في عملية نطق الكلام.
تبدو الدالة
onEvent
على النحو التالي:(event: TtsEvent) => {...}
-
حدث
حدث التعديل من محرّك تحويل النص إلى كلام الذي يشير إلى حالة هذا اللفظ.
-
TtsVoice
وصف لصوت متاح لتجميع الكلام.
أماكن إقامة
-
eventTypes
EventType[] اختيارية
جميع أنواع أحداث معاودة الاتصال التي يمكن لهذا الصوت إرسالها
-
extensionId
سلسلة اختيارية
رقم تعريف الإضافة التي توفّر هذا الصوت.
-
gender
VoiceGender اختيارية
تم إيقافه منذ إصدار 70 Chromeتم إيقاف سمة "الجنس" نهائيًا وسيتم تجاهلها.
جنس هذا الصوت
-
lang
سلسلة اختيارية
اللغة التي يتيحها هذا الصوت، على شكل language-region أمثلة: "en" و"en-US" و"en-GB" و"zh-CN"
-
عمل عن بُعد
منطقية اختيارية
إذا كانت الإجابة صواب، فإن المحرك التجميعي يكون موردًا لشبكة بعيدة. وقد يؤدي ذلك إلى زيادة وقت الاستجابة وقد تترتّب رسوم على استخدام معدل نقل البيانات.
-
voiceName
سلسلة اختيارية
تمثّل هذه السمة اسم الصوت.
VoiceGender
تم إيقاف سمة الجنس نهائيًا وتجاهله.
التعداد
الطُرق
getVoices()
chrome.tts.getVoices(
callback?: function,
)
الحصول على مجموعة من جميع الأصوات المتاحة
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(voices: TtsVoice[]) => void
-
الأصوات
TtsVoice[]
مصفوفة من عناصر
tts.TtsVoice
تمثِّل الأصوات المتاحة لتجميع الكلام.
-
المرتجعات
-
Promise<TtsVoice[]>
Chrome 101 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
isSpeaking()
chrome.tts.isSpeaking(
callback?: function,
)
للتحقق مما إذا كان المحرك يعمل حاليًا أم لا. في نظام التشغيل Mac OS X، تكون النتيجة صحيحة عندما يتحدث محرك الكلام للنظام، حتى إذا لم يبدأ Chrome في بدء الكلام.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(speaking: boolean) => void
-
يتحدث
boolean
True في حالة التحدث، أو false في الحالات الأخرى.
-
المرتجعات
-
Promise<boolean>
Chrome 101 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
pause()
chrome.tts.pause()
لإيقاف تركيب الكلام مؤقتًا، من المحتمل أن يتم ذلك في منتصف الكلام. ستؤدي مكالمة للاستئناف أو الإيقاف إلى إلغاء الإيقاف المؤقت للكلام.
resume()
chrome.tts.resume()
في حال تم إيقاف الكلام مؤقتًا، يستأنف التحدث من حيث توقف.
speak()
chrome.tts.speak(
utterance: string,
options?: TtsOptions,
callback?: function,
)
قراءة النص باستخدام محرك تحويل النص إلى كلام
المَعلمات
-
اللفظ
سلسلة
النص المطلوب قوله، إما نص عادي أو مستند SSML كامل ومكتوب بشكل جيد. وستعمل محركات الكلام التي لا تتيح استخدام SSML على إزالة العلامات ونطق النص. يبلغ الحد الأقصى لطول النص 32,768 حرفًا.
-
الخيارات
TtsOptions اختيارية
خيارات الكلام.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 101 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
stop()
chrome.tts.stop()
إيقاف أي كلام حالي ومحو قائمة الانتظار لأي كلام في انتظار المراجعة. بالإضافة إلى ذلك، إذا تم إيقاف ميزة "التعرّف على الكلام مؤقتًا"، سيتم الآن استئنافها أثناء المكالمة التالية للتحدّث.
فعاليات
onVoicesChanged
chrome.tts.onVoicesChanged.addListener(
callback: function,
)
يتم استدعاؤه عند تغيير قائمة tts.TtsVoice
التي سيعرضها getVoices.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:() => void