chrome.tts

תיאור

יש להשתמש ב-API chrome.tts כדי להפעיל המרת טקסט לדיבור (TTS) מסונתז. למידע נוסף, ניתן לעיין ב-API הרלוונטי של 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);
    }
  }
);

הקריאה החוזרת חוזרת מיד, לפני שהמנוע מתחיל להפיק דיבור. מטרת הקריאה החוזרת היא להתריע בפניך מפני שגיאות תחביר בשימוש שלך ב-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

Chrome בגרסה 54 ומעלה

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

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

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

  השפה שמשמשת לסינתזה, בפורמט 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)=> {...}

  • אירוע

    TtsEvent

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

TtsVoice

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

תכונות

• eventTypes

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

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

• extensionId

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

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

• gender

  VoiceGender אופציונלי

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

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

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

• lang

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

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

• עבודה מרחוק

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

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

• voiceName

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

  שם הקול.

VoiceGender

Chrome 54 ואילך הוצא משימוש מאז Chrome 70

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

טיפוסים בני מנייה (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 124 ומעלה

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

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

פרמטרים

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

  פונקציה

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

  ()=>void