browser.tts

תיאור

משתמשים ב-API של chrome.tts כדי להפעיל המרת טקסט לדיבור (TTS) מסונתזת. כדאי גם לעיין ב-API הקשור ttsEngine, שמאפשר לתוסף להטמיע מנוע דיבור.

היכולת הזו זמינה ב-Chrome ב-Windows (באמצעות SAPI 5), ב-Mac OS X וב-ChromeOS, באמצעות יכולות המרת טקסט לדיבור שמספקת מערכת ההפעלה. בכל הפלטפורמות, המשתמש יכול להתקין תוספים שרושמים את עצמם כמנועי דיבור חלופיים.

הרשאות

tts

מושגים ושימוש

יצירת דיבור

כדי לדבר, צריך להתקשר למספר speak() מהשלוחה שלך. לדוגמה:

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

כדי להפסיק את ההקראה באופן מיידי, פשוט אומרים stop():

browser.tts.stop();

אתם יכולים להגדיר אפשרויות ששולטות במאפיינים שונים של הדיבור, כמו הקצב, גובה הצליל ועוד. לדוגמה:

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

מומלץ גם לציין את השפה כדי שהמערכת תבחר סינתיסייזר שתומך בשפה הזו (ובניב האזורי, אם רלוונטי).

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

כברירת מחדל, כל קריאה ל-speak() קוטעת את הדיבור הנוכחי ומתחילה לדבר מיד. כדי לבדוק אם שיחה תפריע למשהו, אפשר להתקשר אל isSpeaking(). בנוסף, אתם יכולים להשתמש באפשרות enqueue כדי להוסיף את הביטוי הזה לתור של ביטויים שיוקראו כשהביטוי הנוכחי יסתיים.

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

תיאור מלא של כל האפשרויות מופיע בקטע tts.speak(). לא כל מנועי הדיבור תומכים בכל האפשרויות.

כדי לזהות שגיאות ולוודא שהקריאה לפונקציה speak() מתבצעת בצורה נכונה, צריך להעביר פונקציית קריאה חוזרת (callback) שלא מקבלת ארגומנטים. בתוך הקריאה החוזרת (callback), בודקים את runtime.lastError כדי לראות אם היו שגיאות.

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

הקריאה החוזרת (callback) מוחזרת מיד, לפני שהמנוע מתחיל ליצור דיבור. מטרת פונקציית ה-callback היא להתריע על שגיאות תחביר בשימוש ב-TTS API, ולא לתפוס את כל השגיאות האפשריות שעלולות להתרחש בתהליך הסינתזה והפלט של הדיבור. כדי לזהות גם את השגיאות האלה, צריך להשתמש ברכיב event listener, שמתואר בקטע הבא.

האזנה לאירועים

כדי לקבל מידע נוסף בזמן אמת על הסטטוס של הדיבור המסונתז, מעבירים רכיב event listener באפשרויות אל speak(), באופן הבא:

browser.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> ברמה העליונה, ולא קטע ממסמך.

לדוגמה:

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

לא כל מנועי הדיבור תומכים בכל תגי ה-SSML, וחלקם לא תומכים ב-SSML בכלל, אבל כל המנועים נדרשים להתעלם מכל תג SSML שהם לא תומכים בו, ועדיין להקריא את הטקסט הבסיסי.

בחירת קול

כברירת מחדל, Chrome בוחר את הקול המתאים ביותר לכל ביטוי שרוצים להקריא, בהתאם לשפה. ברוב המערכות של Windows,‏ macOS ו-ChromeOS, המרת הטקסט לדיבור שמספקת מערכת ההפעלה אמורה להיות מסוגלת להקריא כל טקסט בשפה אחת לפחות. עם זאת, יכול להיות שלחלק מהמשתמשים יהיו מגוון קולות זמינים ממערכת ההפעלה שלהם וממנועי דיבור שמוטמעים בתוספים אחרים ל-Chrome. במקרים כאלה, אתם יכולים להטמיע קוד בהתאמה אישית כדי לבחור את הקול המתאים, או להציג למשתמש רשימה של אפשרויות.

כדי לקבל רשימה של כל הקולות, צריך להפעיל את getVoices() ולהעביר לה פונקציה שמקבלת מערך של אובייקטים מסוג TtsVoice כארגומנט:

browser.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 ואילך browser.* ‎ מגרסה 148 של Chrome

טיפוסים בני מנייה (enum)

"start"

"end"

"מילה"

"משפט"

"marker"

"interrupted"

"cancelled"

"error"

"pause"

"resume"

TtsEvent

אירוע ממנוע ה-TTS שמעביר את הסטטוס של ביטוי.

מאפיינים

• charIndex

  מספר אופציונלי

  האינדקס של התו הנוכחי באמירה. באירועי מילים, האירוע מופעל בסוף מילה אחת ולפני תחילת המילה הבאה. התג charIndex מייצג נקודה בטקסט בתחילת המילה הבאה שתושמע.

• errorMessage

  מחרוזת אופציונלי

  תיאור השגיאה, אם סוג האירוע הוא error.

• length

  מספר אופציונלי

  Chrome 74 ואילך browser.* ‎ מ-Chrome 148

  האורך של החלק הבא של הביטוי. לדוגמה, באירוע word, זהו אורך המילה שתוקרא בהמשך. אם מנוע הדיבור לא מגדיר את הערך, הוא יהיה ‎-1.

• סוג

  EventType

  הסוג יכול להיות start ברגע שהדיבור מתחיל, word כשמגיעים לגבול של מילה, sentence כשמגיעים לגבול של משפט, marker כשמגיעים לרכיב סימון SSML,‏ end כשמגיעים לסוף הביטוי, interrupted כשהביטוי נעצר או מופסק לפני שמגיעים לסוף, cancelled כשהוא מוסר מהתור לפני שהוא מסונתז, או error כשמתרחשת שגיאה אחרת. כשמשהים את הדיבור, מופעל אירוע pause אם ביטוי מסוים מושהה באמצע, ומופעל אירוע resume אם ביטוי ממשיך את הדיבור. שימו לב שאירועי השהיה והמשך לא יופעלו אם הדיבור מושהה בין ביטויים.

TtsOptions

‫Chrome 77 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

אפשרויות הדיבור של מנוע ה-TTS.

מאפיינים

• desiredEventTypes

  string[] אופציונלי

  סוגי האירועים של TTS שאתם רוצים להאזין להם. אם הפרמטר הזה חסר, יכול להיות שיישלחו כל סוגי האירועים.

• הוספה לתור

  בוליאני אופציונלי

  אם הערך הוא True, ההתבטאות הזו תתווסף לתור אם המרת הטקסט לדיבור (TTS) כבר מתבצעת. אם הערך הוא false (ברירת המחדל), המערכת קוטעת את הדיבור הנוכחי ומנקה את תור הדיבור לפני שהיא משמיעה את הביטוי החדש.

• extensionId

  מחרוזת אופציונלי

  מזהה התוסף של מנוע הדיבור שבו רוצים להשתמש, אם הוא ידוע.

• gender

  VoiceGender אופציונלי

  הוצא משימוש ב-Chrome 77

  השדה "מגדר" הוצא משימוש והמערכת תתעלם ממנו.

  המגדר של הקול המסונתז.

• lang

  מחרוזת אופציונלי

  השפה שבה משתמשים להמרת טקסט לדיבור, בפורמט language-region. דוגמאות: "he",‏ "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

  string[] אופציונלי

  סוגי האירועים של המרת טקסט לדיבור שהקול חייב לתמוך בהם.

• voiceName

  מחרוזת אופציונלי

  שם הקול שבו רוצים להשתמש להמרת טקסט לדיבור. אם השדה ריק, המערכת משתמשת בכל קול זמין.

• עוצמת קול

  מספר אופציונלי

  עוצמת הדיבור היא בין 0 ל-1 (כולל), כאשר 0 הוא הנמוך ביותר ו-1 הוא הגבוה ביותר, עם ברירת מחדל של 1.0.

• onEvent

  void אופציונלי

  הפונקציה הזו נקראת עם אירועים שמתרחשים בתהליך של אמירת הביטוי.

  הפונקציה onEvent נראית כך:

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

  • אירוע

    TtsEvent

    אירוע העדכון ממנוע המרת הטקסט לדיבור (TTS) שמציין את הסטטוס של ההגייה הזו.

TtsVoice

תיאור של קול שזמין לסינתזת דיבור.

מאפיינים

• eventTypes

  ‫EventType[] אופציונלי

  כל סוגי האירועים של הקריאה החוזרת (callback) שהקול הזה יכול לשלוח.

• extensionId

  מחרוזת אופציונלי

  המזהה של התוסף שמספק את הקול הזה.

• gender

  VoiceGender אופציונלי

  הוצא משימוש ב-Chrome 70

  השדה "מגדר" הוצא משימוש והמערכת תתעלם ממנו.

  המגדר של הקול הזה.

• lang

  מחרוזת אופציונלי

  השפה שהקול הזה תומך בה, בפורמט language-region. דוגמאות: "he",‏ "en-US",‏ "en-GB",‏ "zh-CN".

• שלט רחוק

  בוליאני אופציונלי

  אם הערך הוא True, מנוע הסינתזה הוא משאב רשת מרוחק. יכול להיות שזמן האחזור יהיה ארוך יותר ושתחויבו בעלויות על רוחב הפס.

• voiceName

  מחרוזת אופציונלי

  שם הקול.

VoiceGender

Chrome 54 ואילך browser.* ‎ מגרסה 148 של Chrome הוצא משימוש מגרסה 70 של Chrome

המאפיין "מגדר" הוצא משימוש והמערכת מתעלמת ממנו.

טיפוסים בני מנייה (enum)

"male"

"female"

Methods

getVoices()

browser.tts.getVoices(): Promise<TtsVoice[]>

מקבל מערך של כל הקולות הזמינים.

החזרות

• Promise<TtsVoice[]>

  ‫Chrome 101 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

isSpeaking()

browser.tts.isSpeaking(): Promise<boolean>

בודק אם המנוע מדבר כרגע. ב-Mac OS X, התוצאה היא True בכל פעם שמנוע הדיבור של המערכת פועל, גם אם הדיבור לא הופעל על ידי Chrome.

החזרות

• Promise<boolean>

  ‫Chrome 101 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

pause()

browser.tts.pause(): void

השהיית המרת הטקסט לדיבור, יכול להיות שבאמצע הדיבור. כדי להמשיך או להפסיק את הדיבור, צריך להפעיל את הפונקציה המתאימה.

resume()

browser.tts.resume(): void

אם הדיבור הושהה, הוא ימשיך מהמקום שבו הוא הופסק.

speak()

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

הקראת טקסט באמצעות מנוע המרת טקסט לדיבור (TTS).

פרמטרים

• ביטוי

  מחרוזת

  הטקסט שרוצים להקריא, כטקסט פשוט או כמסמך SSML מלא ותקין. מנועי דיבור שלא תומכים ב-SSML יסירו את התגים ויקריאו את הטקסט. האורך המקסימלי של הטקסט הוא 32,768 תווים.

• אפשרויות

  ‫TtsOptions אופציונלי

  אפשרויות הדיבור.

החזרות

• Promise<void>

  ‫Chrome 101 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

  הפעולה מתבצעת מיד, לפני שהדיבור מסתיים. אם תתרחש שגיאה, ההבטחה תידחה. כדי לקבל משוב מפורט יותר, אפשר להשתמש ב-options.onEvent.

stop()

browser.tts.stop(): void

מפסיק את הדיבור שפועל כרגע ומנקה את התור של כל הביטויים בהמתנה. בנוסף, אם הדיבור הושהה, הוא יופעל מחדש בקריאה הבאה לדיבור.

אירועים

onVoicesChanged

‫Chrome 124 ואילך ‫browser.* ‎ החל מ-Chrome 148

browser.tts.onVoicesChanged.addListener(
  callback: function,
)

מופעלת כשרשימת ה-tts.TtsVoice שמוחזרת על ידי getVoices משתנה.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

  () => void