chrome.ttsEngine

תיאור

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

הרשאות

ttsEngine

סקירה כללית

תוסף יכול לרשום את עצמו כמנוע דיבור. כך הוא יכול ליירט חלק מהקריאות או את כולן לפונקציות כמו tts.speak ו-tts.stop ולספק הטמעה חלופית. תוספים יכולים להשתמש בכל טכנולוגיית אינטרנט זמינה כדי לספק דיבור, כולל אודיו בסטרימינג משרת, אודיו ב-HTML5. תוסף יכול גם לבצע פעולה שונה עם ההצהרות, כמו להציג כתוביות בחלון קופץ או לשלוח אותן כהודעות ביומן לשרת מרוחק.

מניפסט

כדי להטמיע מנוע TTS, התוסף צריך להצהיר על ההרשאה ttsEngine ואז להצהיר על כל הקולות שהוא מספק במניפסט של התוסף, באופן הבא:

{
  "name": "My TTS Engine",
  "version": "1.0",
  "permissions": ["ttsEngine"],
  "tts_engine": {
    "voices": [
      {
        "voice_name": "Alice",
        "lang": "en-US",
        "event_types": ["start", "marker", "end"]
      },
      {
        "voice_name": "Pat",
        "lang": "en-US",
        "event_types": ["end"]
      }
    ]
  },
  "background": {
    "page": "background.html",
    "persistent": false
  }
}

אפשר לציין מספר בלתי מוגבל של קולות בתוסף.

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

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

לבסוף, הפרמטר event_types נדרש אם המנוע יכול לשלוח אירועים כדי לעדכן את הלקוח לגבי התקדמות סינתז הדיבור. מומלץ מאוד לתמוך בסוג האירוע 'end' כדי לציין מתי הדיבור מסתיים, אחרת Chrome לא יוכל לתזמן משפטים שנמצאים בתור.

אחרי הטעינה, תוסף יכול להחליף את רשימת הקולות שצוינו באמצעות קריאה ל-chrome.ttsEngine.updateVoices. (שימו לב שהפרמטרים שמשמשים בקריאה הפרוגרמטית ל-updateVoices הם באותיות רישיות (case-sensitive) בסגנון camel case: למשל, voiceName, בניגוד לקובץ המניפסט שבו נעשה שימוש ב-voice_name).

סוגי האירועים האפשריים שאפשר לשלוח תואמים לסוגים של האירועים שהשיטה speak() מקבלת:

  • 'start': המנוע התחיל לדבר את ההבעה.
  • 'word': הגעתם לקצה המילה. משתמשים ב-event.charIndex כדי לקבוע את מיקום הדיבור הנוכחי.
  • 'sentence': הגעתם לקצה המשפט. משתמשים ב-event.charIndex כדי לקבוע את מיקום הדיבור הנוכחי.
  • 'marker': הגעתם לסמן SSML. משתמשים ב-event.charIndex כדי לקבוע את מיקום הדיבור הנוכחי.
  • 'end': המנוע סיים לומר את ההבעה.
  • 'error': אירעה שגיאה ספציפית למנוע ולא ניתן לבטא את המשפט הזה. מעבירים מידע נוסף ב-event.errorMessage.

אירועי 'interrupted' ו-'cancelled' לא נשלחים על ידי מנוע הדיבור, אלא נוצרים באופן אוטומטי על ידי Chrome.

לקוחות של Text-to-speech יכולים לקבל את פרטי הקול מהמניפסט של התוסף באמצעות קריאה ל-tts.getVoices, בהנחה שרשמת מאזינים לאירועי דיבור כפי שמתואר בהמשך.

טיפול באירועי דיבור

כדי ליצור דיבור לפי בקשה של לקוחות, התוסף צריך לרשום מאזינים גם ל-onSpeak וגם ל-onStop, כך:

const speakListener = (utterance, options, sendTtsEvent) => {
  sendTtsEvent({type: 'start', charIndex: 0})

  // (start speaking)

  sendTtsEvent({type: 'end', charIndex: utterance.length})
};

const stopListener = () => {
  // (stop all speech)
};

chrome.ttsEngine.onSpeak.addListener(speakListener);
chrome.ttsEngine.onStop.addListener(stopListener);

ההחלטה אם לשלוח בקשת דיבור מסוימת לתוסף או לא מבוססת אך ורק על כך שהתוסף תומך בפרמטרים הקוליים הנתונים במניפסט שלו ושיש לו מאזינים רשומים ל-onSpeak ול-onStop. במילים אחרות, אין דרך להרחבה לקבל בקשה לדיבור ולהחליט באופן דינמי אם לטפל בה.

סוגים

AudioBuffer

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

פרמטרים שמכילים מאגר אודיו ונתונים משויכים.

מאפיינים

  • audioBuffer

    ArrayBuffer

    מאגר האודיו ממנוע המרת הטקסט לדיבור. האורך שלו צריך להיות בדיוק audioStreamOptions.bufferSize, והוא צריך להיות מקודד כמונו, ב-audioStreamOptions.sampleRate וכ-PCM ליניארי, 32-bit signed float, כלומר הסוג Float32Array ב-JavaScript.

  • charIndex

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

    אינדקס התווים שמשויך למאגר האודיו הזה.

  • isLastBuffer

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

    הערך True מוחזר אם מאגר האודיו הזה הוא האחרון של הטקסט שנאמר.

AudioStreamOptions

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

מכיל את הפורמט של ערוץ האודיו שצפוי להיווצר על ידי מנוע.

מאפיינים

  • bufferSize

    number

    מספר הדגימות במאגר אודיו.

  • sampleRate

    number

    תדירות הדגימה הצפויה במאגר אודיו.

LanguageInstallStatus

בהמתנה

סטטוס ההתקנה של קול.

Enum

"notInstalled"

"installing"

"installed"

"failed"

LanguageStatus

בהמתנה

סטטוס ההתקנה של שפה.

מאפיינים

  • error

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

    פרטים על כשלים בהתקנה. אפשר לאכלס את השדה הזה אם התקנת השפה נכשלה.

  • installStatus

    LanguageInstallStatus

    סטטוס ההתקנה.

  • lang

    מחרוזת

    מחרוזת שפה בפורמט קוד שפה-קוד אזור, כאשר אפשר להשמיט את האזור. דוגמאות: en, ‏ en-AU, ‏ zh-CH.

LanguageUninstallOptions

בהמתנה

אפשרויות להסרת שפה מסוימת.

מאפיינים

  • uninstallImmediately

    בוליאני

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

SpeakOptions

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

האפשרויות שצוינו לשיטה tts.speak().

מאפיינים

  • gender

    VoiceGender אופציונלי

    הוצאה משימוש החל מ-Chrome 92

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

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

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

  • voiceName

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

    השם של הקול שרוצים להשתמש בו לסינתזה.

  • עוצמת קול

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

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

TtsClient

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

המזהה של הלקוח שמבקש את הסטטוס.

מאפיינים

  • id [מזהה]

    מחרוזת

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

  • סוג מבקש הבקשה.

TtsClientSource

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

סוג מבקש הבקשה.

Enum

"chromefeature"

"extension"

VoiceGender

Chrome מגרסה 54 ואילך הוצאה משימוש החל מגרסה Chrome 70

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

Enum

"male"

"female"

Methods

updateLanguage()

בהמתנה
chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
)

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

פרמטרים

updateVoices()

Chrome מגרסה 66 ואילך 
chrome.ttsEngine.updateVoices(
  voices: TtsVoice[],
)

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

פרמטרים

  • קולות

    TtsVoice[]

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

אירועים

onInstallLanguageRequest

Chrome מגרסה 131 ואילך 
chrome.ttsEngine.onInstallLanguageRequest.addListener(
  callback: function,
)

האירוע הזה מופעל כשלקוח TTS מבקש להתקין שפה חדשה. המנוע אמור לנסות להוריד ולהתקין את השפה, ולקרוא ל-ttsEngine.updateLanguage עם התוצאה. אם הפעולה תתבצע בהצלחה, המנוע צריך גם לבצע קריאה ל-ttsEngine.updateVoices כדי לרשום את הקולות החדשים שזמינים.

פרמטרים

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

    פונקציה

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

    (requestor: TtsClient, lang: string) => void

    • מגיש הבקשה

      TtsClient

    • lang

      מחרוזת

onLanguageStatusRequest

בהמתנה
chrome.ttsEngine.onLanguageStatusRequest.addListener(
  callback: function,
)

האירוע מופעל כשלקוח TTS מבקש את סטטוס ההתקנה של שפה.

פרמטרים

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

    פונקציה

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

    (requestor: TtsClient, lang: string) => void

    • מגיש הבקשה

      TtsClient

    • lang

      מחרוזת

onPause

chrome.ttsEngine.onPause.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    () => void

onResume

chrome.ttsEngine.onResume.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    () => void

onSpeak

chrome.ttsEngine.onSpeak.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    (utterance: string, options: SpeakOptions, sendTtsEvent: function) => void

    • משפט

      מחרוזת

    • אפשרויות

      SpeakOptions

    • sendTtsEvent

      פונקציה

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

      (event: tts.TtsEvent) => void

      • אירוע

        tts.TtsEvent

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

onSpeakWithAudioStream

Chrome מגרסה 92 ואילך 
chrome.ttsEngine.onSpeakWithAudioStream.addListener(
  callback: function,
)

הפונקציה הזו נקראת כשהמשתמש מבצע קריאה ל-tts.speak() ואחת מהקולות מהמניפסט של התוסף הזה היא הראשונה שתתאים לאובייקט האפשרויות. ההבדל בין ttsEngine.onSpeak לבין ttsEngine.onSpeak הוא ש-Chrome מספק שירותי הפעלת אודיו ומטפל בשליחת אירועי TTS.

פרמטרים

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

    פונקציה

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

    (utterance: string, options: SpeakOptions, audioStreamOptions: AudioStreamOptions, sendTtsAudio: function, sendError: function) => void

    • משפט

      מחרוזת

    • אפשרויות

      SpeakOptions

    • audioStreamOptions

      AudioStreamOptions

    • sendTtsAudio

      פונקציה

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

      (audioBufferParams: AudioBuffer) => void

      • audioBufferParams

        AudioBuffer

        פרמטרים שמכילים מאגר אודיו ונתונים משויכים.

    • sendError

      פונקציה

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

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

      (errorMessage?: string) => void

      • errorMessage

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

        מחרוזת שמתארת את השגיאה.

onStop

chrome.ttsEngine.onStop.addListener(
  callback: function,
)

האירוע מופעל כשמתבצעת קריאה ל-tts.stop והתוסף הזה עשוי להיות באמצע דיבור. אם תוסף מקבל קריאה ל-onStop והדיבור כבר הופסק, הוא לא אמור לעשות שום דבר (לא להעלות שגיאה). אם הדיבור נמצא במצב מושהה, הפעולה הזו אמורה לבטל את המצב המושהה.

פרמטרים

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

    פונקציה

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

    () => void

onUninstallLanguageRequest

בהמתנה
chrome.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

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

פרמטרים