תיאור
יש להשתמש ב-API chrome.tts
כדי להפעיל המרת טקסט לדיבור (TTS) מסונתז. למידע נוסף, ניתן לעיין ב-API הרלוונטי של 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);
}
}
);
הקריאה החוזרת חוזרת מיד, לפני שהמנוע מתחיל להפיק דיבור. מטרת הקריאה החוזרת היא להתריע בפניך מפני שגיאות תחביר בשימוש שלך ב-API של TTS, ולא כדי לאתר את כל השגיאות האפשריות שעשויות להתרחש בתהליך הסינתזה ופלט הדיבור. כדי לקלוט גם את השגיאות האלה, צריך להשתמש ב-Event listener, שמתואר בהמשך.
האזנה לאירועים
על מנת לקבל מידע נוסף בזמן אמת על הסטטוס של דיבור מסונתז, צריך להעביר event listener באפשרויות אל 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
ביטויים שמשמשים ב-API הזה עשויים לכלול תגי עיצוב באמצעות Speech Synthesis Markup Language
(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
טיפוסים בני מנייה (enum)
TtsEvent
אירוע ממנוע ה-TTS להעברת הסטטוס של דיבור.
תכונות
-
charIndex
מספר אופציונלי
האינדקס של התו הנוכחי בהגייה. באירועי מילוליות, האירוע מופעל בסוף מילה אחת ולפני תחילת המילה הבאה.
charIndex
מייצג נקודה בטקסט בתחילת המילה הבאה שיש לומר. -
errorMessage
מחרוזת אופציונלי
תיאור השגיאה, אם סוג האירוע הוא
error
. -
length
מספר אופציונלי
Chrome 74 ומעלהאורך החלק הבא של הביטוי. למשל, באירוע
word
, זהו אורך המילה שיושמעה לאחר מכן. אם לא הוגדר על ידי מנוע הדיבור, היא תוגדר לערך 1-. -
סוג
הסוג יכול להיות
start
ברגע שהדיבור מתחיל,word
כשמגיעים לגבול של מילה,sentence
כשמגיעים לגבול של משפט,marker
כשמגיעים לרכיב של סימן SSML,end
כשמגיעים לסוף הביטוי,interrupted
כשהביטוי נעצר או נעצר לפני שהוא מגיע לסופה,cancelled
אם הוא הוסר מהתור לפני הסינתזה, אוerror
כשמתרחשת שגיאה אחרת. כשמשהים דיבור, האירועpause
מופעל אם מבטא מסוים מושהה באמצע וresume
אם הביטוי מחדש מתחיל את הדיבור. שים לב: ייתכן שאירועי השהיה והמשך לא יופעלו אם הדיבור מושהה בין המילים.
TtsOptions
אפשרויות הדיבור למנוע ה-TTS.
תכונות
-
desiredEventTypes
string[] אופציונלי
סוגי אירועי ה-TTS שברצונך להאזין להם. אם חסרים אירועים, ייתכן שכל סוגי האירועים יישלחו.
-
להכניס לתור
בוליאני אופציונלי
אם הערך הוא true, הביטוי הזה נוסף לתור אם TTS כבר מתבצע. אם FALSE (ברירת המחדל), מפריע לדיבור הנוכחי ומוחק את תור הדיבור לפני שאומרים את הביטוי החדש.
-
extensionId
מחרוזת אופציונלי
מזהה התוסף של מנוע הדיבור שבו צריך להשתמש, אם ידוע.
-
gender
VoiceGender אופציונלי
הוצא משימוש מאז Chrome 77המגדר הוצא משימוש והמערכת תתעלם ממנו.
מגדר הקול לדיבור מסונתז.
-
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.0 כרגיל, גם אם ציינתם ערך גדול מ-3.0.
-
requiredEventTypes
string[] אופציונלי
סוגי אירוע ה-TTS שהקול חייב לתמוך בהם.
-
voiceName
מחרוזת אופציונלי
שם הקול שישמש לסינתזה. אם השדה ריק, ייעשה שימוש בכל קול זמין.
-
עוצמת קול
מספר אופציונלי
נפח הדיבור בין 0 ל-1 כולל, כאשר 0 הוא הנמוך ביותר ו-1 הוא הגבוה ביותר, עם ברירת מחדל של 1.0.
-
onEvent
ביטול אופציונלי
הפונקציה הזו נקראת עם אירועים שמתרחשים בתהליך של אמירת הביטוי.
הפונקציה
onEvent
נראית כך:(event: TtsEvent) => {...}
-
אירוע
אירוע העדכון ממנוע המרת הטקסט לדיבור (TTS) שמציין את הסטטוס של הביטוי הזה.
-
TtsVoice
תיאור של קול שזמין לסינתזת דיבור.
תכונות
-
eventTypes
EventType[] אופציונלי
כל הסוגים של אירועי קריאה חוזרת שהקול הזה יכול לשלוח.
-
extensionId
מחרוזת אופציונלי
המזהה של התוסף שמספק את הקול הזה.
-
gender
VoiceGender אופציונלי
הוצא משימוש מאז Chrome 70המגדר הוצא משימוש והמערכת תתעלם ממנו.
המגדר של הקול.
-
lang
מחרוזת אופציונלי
השפה שבה הקול הזה תומך, בצורת language-region. דוגמאות: 'en', 'en-US', 'en-GB', 'zh-CN'.
-
עבודה מרחוק
בוליאני אופציונלי
אם הערך הוא True, מנוע הסינתזה הוא משאב רשת מרוחקת. זמן האחזור עשוי להיות גבוה יותר והחיוב עשוי להיות כרוך בעלויות רוחב פס.
-
voiceName
מחרוזת אופציונלי
שם הקול.
VoiceGender
המגדר הוצא משימוש והמערכת תתעלם ממנו.
טיפוסים בני מנייה (enum)
שיטות
getVoices()
chrome.tts.getVoices(
callback?: function,
)
מקבלת מערך של כל הקולות הזמינים.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(voices: TtsVoice[]) => void
-
קולות
TtsVoice[]
מערך של אובייקטים
tts.TtsVoice
שמייצגים את הקולות הזמינים לסינתזת הדיבור.
-
החזרות
-
Promise<TtsVoice[]>
Chrome 101 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
isSpeaking()
chrome.tts.isSpeaking(
callback?: function,
)
הפונקציה בודקת אם המנוע מדבר כרגע. ב-Mac OS X, התוצאה תתקבל בכל פעם שמנוע הדיבור של המערכת ידבר, גם אם הדיבור לא הופעל על ידי Chrome.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(speaking: boolean) => void
-
מדבר
boolean
True אם מדברים, או FALSE אם לא.
-
החזרות
-
Promise<boolean>
Chrome 101 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
pause()
chrome.tts.pause()
השהיה של סינתזת הדיבור, אולי באמצע הביטוי. קריאה להמשך או לעצירה תבטל את השהיית הדיבור.
resume()
chrome.tts.resume()
אם הדיבור הושהה, הדיבור ימשיך מהמקום שבו הופסק.
speak()
chrome.tts.speak(
utterance: string,
options?: TtsOptions,
callback?: function,
)
הקראת טקסט באמצעות מנוע המרת טקסט לדיבור (TTS).
פרמטרים
-
מבטא
string
הטקסט שצריך לומר, טקסט פשוט או מסמך SSML מלא בפורמט תקין. מנועי דיבור שלא תומכים ב-SSML ימחקו את התגים ויאמרו את הטקסט. האורך המקסימלי של הטקסט הוא 32,768 תווים.
-
אפשרויות
TtsOptions אופציונלי
אפשרויות הדיבור.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 101 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
stop()
chrome.tts.stop()
מפסיק את הדיבור הנוכחי ומוחק את התור של ביטויים בהמתנה. בנוסף, אם הדיבור הושהה, ההשהיה תבוטל למשך השיחה הבאה.
אירועים
onVoicesChanged
chrome.tts.onVoicesChanged.addListener(
callback: function,
)
היא הופעלה כשיש שינוי ברשימת tts.TtsVoice
שיוחזרו על ידי getVoices.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:() => void