chrome.ttsEngine

refresh date: 2026-09-25 robots: noindex

תיאור

משתמשים ב-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 הם בקאמל קייס: למשל, 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)
};

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

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

סוגים

AudioBuffer

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

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

מאפיינים

  • audioBuffer

    ArrayBuffer

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

  • charIndex

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

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

  • isLastBuffer

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

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

AudioStreamOptions

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

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

מאפיינים

  • bufferSize

    number

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

  • sampleRate

    number

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

LanguageInstallStatus

‫Chrome מגרסה 132 ואילך

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

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

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

אפשרויות שצוינו ל-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 ואילך

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

מאפיינים

  • id [מזהה]

    מחרוזת

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

  • סוג המבקש.

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 כדי לרשום את הקול.

פרמטרים

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

    • ביטוי

      מחרוזת

    • אפשרויות

      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

    • ביטוי

      מחרוזת

    • אפשרויות

      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 מציין שאין יותר צורך בשפה.

פרמטרים