chrome.ttsEngine

תיאור

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

הרשאות

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 הם בפורמט CamelCase: למשל, voiceName, בניגוד לקובץ המניפסט שמשתמש ב-voice_name).

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

סוגי האירועים האפשריים שאפשר לשלוח תואמים לסוגי האירועים שהמתודה 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)
};

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

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

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

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

Enum

‫"notInstalled"

"installing"

‫"installed"

'נכשל'

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

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

  השפה שבה רוצים להשתמש לסינתזה, בפורמט שפה-אזור. דוגמאות: '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, זהו השם של התכונה שקריא לאנשים.

• source

  TtsClientSource

  סוג הפונה.

TtsClientSource

‫Chrome 131 ואילך

סוג הפונה.

Enum

‫"chromefeature"

‫"extension"

VoiceGender

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

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

Enum

‎"male"

‎"female"

Methods

updateLanguage()

‫Chrome 132 ואילך

chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
): void

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

פרמטרים

• status

  LanguageStatus

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

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 הוא ש-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 מציין ששפה מסוימת כבר לא נדרשת.

פרמטרים

• callback

  פונקציה

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

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

  • מגיש הבקשה

    TtsClient

  • lang

    מחרוזת

  • uninstallOptions

    LanguageUninstallOptions