chrome.ttsEngine

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

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

אחרי שהתוסף נטען, הוא יכול להחליף את רשימת הקולות שהוגדרו על ידי קריאה אל chrome.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)
};

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

    ‫boolean אופציונלי

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

AudioStreamOptions

‫Chrome 92 ואילך

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

מאפיינים

  • bufferSize

    number

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

  • sampleRate

    number

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

LanguageInstallStatus

‫Chrome 132 ואילך

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

ספירה

‎"notInstalled"

'התקנה'

'התקנה'

‫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

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

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

'תוסף'

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

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

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

פרמטרים