chrome.tts

תיאור

משתמשים ב-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() בצורה נכונה, יש להעביר פונקציית קריאה חוזרת (callback) לא לוקחת ארגומנטים. בתוך הקריאה החוזרת, בודקים את runtime.lastError כדי לראות אם היו שגיאות.

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

הקריאה החוזרת חוזרת (callback) באופן מיידי, לפני שהמנוע מתחיל ליצור דיבור. המטרה של היא להתריע בפניכם על שגיאות תחביר בשימוש ב-TTS API, ולא כדי לקלוט את כל האפשרויות שעלולות להתרחש בתהליך הסינתוז והפלט של דיבור. כדי לזהות את השגיאות האלה גם עליכם להשתמש ב-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 הזה עשויות לכלול תגי עיצוב באמצעות שפת הסימון של סינתזת הדיבור (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+

Enum

"start"

"end"

"מילה"

"משפט"

"סמן"

"הפרעה"

"בוטל"

"שגיאה"

"pause"

"resume"

TtsEvent

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

מאפיינים

  • charIndex

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

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

  • errorMessage

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

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

  • length

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

    Chrome מגרסה 74 ואילך

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

  • סוג

    EventType

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

TtsOptions

Chrome 77 ואילך

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

מאפיינים

  • desiredEventTypes

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

    סוגי האירועים TTS שברצונך להאזין להם. אם חסרים אירועים, יכול להיות שיישלחו כל סוגי האירועים.

  • להוסיף לתור

    ערך בוליאני אופציונלי

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

  • extensionId

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

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

  • gender

    VoiceGender אופציונלי

    הוצא משימוש מאז Chrome 77

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

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

  • lang

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

    השפה שתשמש לסינתזה, בפורמט שפה-אזור. דוגמאות: 'en', 'en-US', 'en-GB', 'zh-CN'.

  • הגשה

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

    גובה הצליל בדיבור בין 0 ל-2 כולל, כאשר 0 הוא הנמוך ביותר ו-2 הוא הגבוה ביותר. הספרה 1.0 תואמת לגובה הצליל שמוגדר כברירת מחדל לקול.

  • שיעור

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

    קצב הדיבור ביחס לקצב ברירת המחדל של הקול הזה. 1.0 הוא קצב ברירת המחדל, בדרך כלל בערך 180 עד 220 מילים לדקה. 2.0 הוא המהירות הגבוהה פי 2, ו-0.5 מציין את המהירות בחצי. אסור בהחלט להשתמש בערכים נמוכים מ-0.1 או מעל 10.0, אבל קולות רבים יגבילו עוד יותר את קצב המינימום והמקסימום. לדוגמה, ייתכן שקול מסוים לא ידבר מהר יותר מפי 3 מהרגיל גם אם מציינים ערך גדול מ-3.0.

  • requiredEventTypes

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

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

  • voiceName

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

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

  • עוצמת קול

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

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

  • onEvent

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

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

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

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

    • אירוע

      TtsEvent

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

TtsVoice

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

מאפיינים

  • eventTypes

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

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

  • extensionId

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

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

  • gender

    VoiceGender אופציונלי

    הוצא משימוש מאז Chrome 70

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

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

  • lang

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

    השפה שהקול הזה תומך בה, בתבנית שפה-אזור. דוגמאות: 'en', 'en-US', 'en-GB', 'zh-CN'.

  • שלט רחוק

    ערך בוליאני אופציונלי

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

  • voiceName

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

    שם הקול.

VoiceGender

Chrome 54+ הוצא משימוש מאז Chrome 70

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

Enum

"זכר"

"female"

שיטות

getVoices()

הבטחה 
chrome.tts.getVoices(
  callback?: function,
)

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    (voices: TtsVoice[]) => void

    • קולות

      TtsVoice[]

      מערך של tts.TtsVoice אובייקטים שמייצגים את הקולות הזמינים לסינתזת דיבור.

החזרות

  • Promise&lt;TtsVoice[]&gt;

    Chrome 101 ואילך

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

isSpeaking()

הבטחה 
chrome.tts.isSpeaking(
  callback?: function,
)

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    (speaking: boolean) => void

    • מדבר

      בוליאני

      True אם מדבר, False אם לא.

החזרות

  • Promise&lt;boolean&gt;

    Chrome 101 ואילך

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

pause()

chrome.tts.pause()

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

resume()

chrome.tts.resume()

אם הדיבור הושהה, הדיבור ימשיך מהנקודה שבו נעצר.

speak()

הבטחה 
chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
)

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

פרמטרים

  • התבטאות

    מחרוזת

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

  • אפשרויות

    TtsOptions אופציונלי

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 101 ואילך

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

stop()

chrome.tts.stop()

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

אירועים

onVoicesChanged

Chrome 124 ואילך 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

בוצעה שיחה כאשר הרשימה של tts.TtsVoice שתוחזר על ידי getVoices תשתנה.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

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

    () => void