browser.ttsEngine

תיאור

משתמשים ב-chrome.ttsEngine API כדי להטמיע מנוע להמרת טקסט לדיבור(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 הם בפורמט Camel Case: למשל, voiceName, בניגוד לקובץ המניפסט שבו משתמשים ב-voice_name).

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

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

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

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

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

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

סוגים

AudioBuffer

‫Chrome 92 ואילך

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

מאפיינים

  • audioBuffer

    ArrayBuffer

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

  • charIndex

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

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

  • isLastBuffer

    ‫boolean אופציונלי

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

AudioStreamOptions

‫Chrome 92 ואילך

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

מאפיינים

  • bufferSize

    number

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

  • sampleRate

    number

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

LanguageInstallStatus

‫Chrome 132 ואילך

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

ספירה

‫"notInstalled"

"installing"

"installed"

"failed"

LanguageStatus

‫Chrome 132 ואילך

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

מאפיינים

  • error

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

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

  • installStatus

    LanguageInstallStatus

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

  • lang

    מחרוזת

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

LanguageUninstallOptions

‫Chrome 132 ואילך

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

מאפיינים

  • 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 ואילך

סוג הפונה.

ספירה

‫"chromefeature"

‎"extension"

VoiceGender

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

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

ספירה

'male'

‎"female"

Methods

updateLanguage()

‫Chrome 132 ואילך 
chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
): void

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

פרמטרים

updateVoices()

‫Chrome 66 ואילך 
chrome.ttsEngine.updateVoices(
  voices: TtsVoice[],
): void

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

פרמטרים

  • קולות

    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 132 ואילך 
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

    • אמירה

      מחרוזת

    • options

      SpeakOptions

    • sendTtsEvent

      פונקציה

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

      (event: tts.TtsEvent) => void

      • אירוע

        tts.TtsEvent

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

onSpeakWithAudioStream

‫Chrome 92 ואילך 
chrome.ttsEngine.onSpeakWithAudioStream.addListener(
  callback: function,
)

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

פרמטרים

  • callback

    פונקציה

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

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

    • אמירה

      מחרוזת

    • options

      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 132 ואילך 
chrome.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

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

פרמטרים