browser.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 לא יכול לתזמן ביטויים בתור.

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

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

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

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

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

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

כדי ליצור דיבור לפי בקשת הלקוחות, התוסף צריך לרשום מאזינים גם ל-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)
};

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

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

סוגים

AudioBuffer

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

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

מאפיינים

  • audioBuffer

    ArrayBuffer

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

  • charIndex

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

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

  • isLastBuffer

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

    ‫True אם מאגר האודיו הזה הוא האחרון בטקסט שמוקרא.

AudioStreamOptions

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

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

מאפיינים

  • bufferSize

    number

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

  • sampleRate

    number

    תדירות הדגימה הצפויה במאגר נתונים זמני של אודיו.

LanguageInstallStatus

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

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

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

"notInstalled"

"installing"

"installed"

"failed"

LanguageStatus

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

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

מאפיינים

  • error

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

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

  • installStatus

    LanguageInstallStatus

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

  • lang

    מחרוזת

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

LanguageUninstallOptions

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

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

מאפיינים

  • uninstallImmediately

    בוליאני

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

SpeakOptions

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

אפשרויות שצוינו ל-method‏ tts.speak()‎.

מאפיינים

  • gender

    VoiceGender אופציונלי

    הוצא משימוש בגרסה Chrome 92

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

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

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

  • voiceName

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

    שם הקול שבו רוצים להשתמש להמרת טקסט לדיבור.

  • עוצמת קול

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

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

TtsClient

‫Chrome 131 ואילך ‫browser.* ‎ מגרסת Chrome 148

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

מאפיינים

  • id [מזהה]

    מחרוזת

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

  • סוג המבקש.

TtsClientSource

‫Chrome 131 ואילך ‫browser.* ‎ מגרסת Chrome 148

סוג המבקש.

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

"chromefeature"

"extension"

VoiceGender

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

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

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

"male"

"female"

Methods

updateLanguage()

‫Chrome 132 ואילך ‫‎browser.* ‎ מגרסה Chrome 148 
browser.ttsEngine.updateLanguage(
  status: LanguageStatus,
): void

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

פרמטרים

updateVoices()

Chrome 66 ואילך browser.* ‎ מ-Chrome 148 
browser.ttsEngine.updateVoices(
  voices: TtsVoice[],
): void

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

פרמטרים

  • קולות

    TtsVoice[]

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

אירועים

onInstallLanguageRequest

‫Chrome 131 ואילך ‫browser.* ‎ מגרסת Chrome 148 
browser.ttsEngine.onInstallLanguageRequest.addListener(
  callback: function,
)

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

פרמטרים

  • callback

    פונקציה

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

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

    • שולח הבקשה

      TtsClient

    • lang

      מחרוזת

onLanguageStatusRequest

‫Chrome 132 ואילך ‫‎browser.* ‎ מגרסה Chrome 148 
browser.ttsEngine.onLanguageStatusRequest.addListener(
  callback: function,
)

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

פרמטרים

  • callback

    פונקציה

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

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

    • שולח הבקשה

      TtsClient

    • lang

      מחרוזת

onPause

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

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

פרמטרים

  • callback

    פונקציה

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

    () => void

onResume

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

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

פרמטרים

  • callback

    פונקציה

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

    () => void

onSpeak

browser.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 ואילך ‫browser.* ‎ מגרסה Chrome 148 
browser.ttsEngine.onSpeakWithAudioStream.addListener(
  callback: function,
)

מופעלת כשהמשתמש מבצע קריאה ל-tts.speak()‎ ואחד מהקולות מהמניפסט של התוסף הזה הוא הראשון שתואם לאובייקט האפשרויות. ההבדל מ-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 ואילך ‫browser.* ‎ החל מ-Chrome 148

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

      (errorMessage?: string) => void

      • errorMessage

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

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

onStop

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

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

פרמטרים

  • callback

    פונקציה

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

    () => void

onUninstallLanguageRequest

‫Chrome 132 ואילך ‫‎browser.* ‎ מגרסה Chrome 148 
browser.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

מופעל כשלקוח TTS מציין שאין יותר צורך בשפה.

פרמטרים