chrome.ttsEngine

refresh date: 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 به‌صورت نگارش شتری هستند: برای مثال، 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 نسخه ۹۲ و بالاتر

پارامترهای حاوی میان‌گیر صوتی و داده‌های مرتبط.

مشخصات

  • audioBuffer

    ArrayBuffer

    بافر صوتی از موتور نوشتار به گفتار. طول آن باید دقیقاً audioStreamOptions.bufferSize باشد و به‌صورت مونو، در audioStreamOptions.sampleRate، و به‌عنوان pcm خطی، اعشاری علامت‌دار ۳۲ بیتی، یعنی نوع Float32Array در جاوا اسکریپت کدگذاری شده باشد.

  • charIndex

    شماره اختیاری

    نمایه نویسه مرتبط با این میان‌گیر صوتی.

  • isLastBuffer

    بولی اختیاری

    اگر این میان‌گیر صوتی آخرین میان‌گیر برای نوشتار درحال خوانده شدن باشد، «درست» است.

AudioStreamOptions

Chrome نسخه ۹۲ و بالاتر

حاوی قالب جاری‌سازی صوتی است که انتظار می‌رود توسط موتور تولید شود.

مشخصات

  • bufferSize

    شماره

    تعداد نمونه‌ها در میان‌گیر صدا.

  • sampleRate

    شماره

    نرخ نمونه‌برداری موردانتظار در میان‌گیر صوتی.

LanguageInstallStatus

Chrome نسخه ۱۳۲ و بالاتر

وضعیت نصب صدا.

شمارشی

"notInstalled"

«درحال نصب»

"installed"

«failed»

LanguageStatus

Chrome نسخه ۱۳۲ و بالاتر

وضعیت نصب زبان.

مشخصات

  • خطا

    رشته اختیاری

    جزئیات مربوط به نصب‌های ناموفق. اگر زبان نصب نشود، به‌صورت اختیاری پر می‌شود.

  • installStatus

    LanguageInstallStatus

    وضعیت نصب.

  • lang

    رشته

    رشته زبان به‌صورت کد زبان-کد منطقه، که ممکن است منطقه حذف شود. نمونه‌ها عبارت‌اند از en،‏ en-AU،‏ zh-CH.

LanguageUninstallOptions

Chrome نسخه ۱۳۲ و بالاتر

گزینه‌های حذف نصب زبان موردنظر.

مشخصات

  • uninstallImmediately

    بولی

    اگر سرویس‌گیرنده TTS بخواهد زبان فوراً حذف نصب شود، True است. موتور ممکن است براساس این پارامتر و اطلاعات درخواست‌کننده، انتخاب کند که زبان را حذف نصب کند یا نه و چه زمانی این کار را انجام دهد. اگر نادرست باشد، ممکن است از معیارهای دیگری مانند استفاده اخیر برای تعیین زمان حذف نصب استفاده کند.

SpeakOptions

Chrome نسخه ۹۲ و بالاتر

گزینه‌های مشخص‌شده برای روش tts.speak().

مشخصات

  • جنسیت

    VoiceGender اختیاری

    از Chrome 92 منسوخ شده است

    جنسیت منسوخ شده است و نادیده گرفته خواهد شد.

    جنسیت صدا برای گفتار ترکیبی.

  • lang

    رشته اختیاری

    زبانی که برای ترکیب استفاده می‌شود، در قالب زبان-منطقه. مثال: «en»،‏ «en-US»،‏ «en-GB»،‏ «zh-CN».

  • آهنگ پیشنهاد دادن

    شماره اختیاری

    زیروبمی گفتار بین ۰ و ۲ (شامل این دو عدد)، که ۰ پایین‌ترین و ۲ بالاترین است. ‫۱٫۰ با زیروبمی پیش‌فرض این صدا مطابقت دارد.

  • رده‌بندی کردن

    شماره اختیاری

    سرعت گفتار نسبت به سرعت پیش‌فرض برای این صدا. ‫۱.۰ نرخ پیش‌فرض است که معمولاً حدود ۱۸۰ تا ۲۲۰ کلمه در دقیقه است. ‫۲٫۰ دو برابر سریع‌تر است و ۰٫۵ نصف سرعت است. این مقدار تضمین می‌شود که بین ۰٫۱ و ۱۰٫۰ باشد. وقتی صدایی از این محدوده کامل نرخ‌ها پشتیبانی نمی‌کند، خطا برنگردانید. درعوض، نرخ را به محدوده‌ای که صدا پشتیبانی می‌کند محدود کنید.

  • voiceName

    رشته اختیاری

    نام صدایی که برای ترکیب استفاده می‌شود.

  • میزان صدا

    شماره اختیاری

    میزان صدای صحبت کردن بین ۰ و ۱ (شامل این دو عدد)، که ۰ کمترین و ۱ بیشترین است، و مقدار پیش‌فرض ۱٫۰ است.

TtsClient

Chrome نسخه ۱۳۱ و بالاتر

شناسه برای مشتری درخواست‌کننده وضعیت.

مشخصات

  • id

    رشته

    کارخواه درخواست مدیریت زبان می‌کند. برای افزونه، این شناسه افزونه یکتا است. برای ویژگی‌های Chrome، این نام قابل‌خواندن برای انسان از ویژگی است.

  • منبع

    TtsClientSource

    نوع درخواست‌کننده.

TtsClientSource

Chrome نسخه ۱۳۱ و بالاتر

نوع درخواست‌کننده.

شمارشی

"chromefeature"

«افزونه»

VoiceGender

Chrome نسخه ۵۴ و بالاتر از Chrome نسخه ۷۰ منسوخ شده است

جنسیت منسوخ شده است و نادیده گرفته خواهد شد.

شمارشی

"male"

"female"

روش‌ها

updateLanguage()

Chrome نسخه ۱۳۲ و بالاتر 
chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
): void

وقتی نصب زبان امتحان می‌شود و وقتی زبان حذف نصب می‌شود، توسط موتور فراخوانی می‌شود. همچنین در پاسخ به درخواست وضعیت از کارخواه فراخوانی می‌شود. وقتی صدایی نصب یا حذف نصب می‌شود، موتور باید ttsEngine.updateVoices را نیز فراخوانی کند تا صدا را ثبت کند.

پارامترها

updateVoices()

Chrome نسخه ۶۶ و بالاتر 
chrome.ttsEngine.updateVoices(
  voices: TtsVoice[],
): void

توسط موتور برای به‌روزرسانی فهرست صداهایش فراخوانی می‌شود. این فهرست بر هر صدایی که در مانیفست این افزونه اعلام شده است اولویت دارد.

پارامترها

  • صداها

    TtsVoice[]

    آرایه‌ای از اشیا tts.TtsVoice که نشان‌دهنده صداهای دردسترس برای ترکیب گفتار است.

رویدادها

onInstallLanguageRequest

Chrome نسخه ۱۳۱ و بالاتر 
chrome.ttsEngine.onInstallLanguageRequest.addListener(
  callback: function,
)

وقتی کلاینت TTS درخواست نصب زبان جدیدی می‌کند، فعال می‌شود. موتور باید برای بارگیری و نصب زبان تلاش کند و ttsEngine.updateLanguage را با نتیجه فراخوانی کند. درصورت موفقیت، موتور باید ttsEngine.updateVoices را نیز فراخوانی کند تا صداهای جدیداً دردسترس را ثبت کند.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

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

    • درخواست‌کننده

      TtsClient

    • lang

      رشته

onLanguageStatusRequest

Chrome نسخه ۱۳۲ و بالاتر 
chrome.ttsEngine.onLanguageStatusRequest.addListener(
  callback: function,
)

وقتی فعال می‌شود که مشتری TTS وضعیت نصب زبان را درخواست کند.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

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

    • درخواست‌کننده

      TtsClient

    • lang

      رشته

onPause

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

اختیاری: اگر موتور از رویداد توقف موقت پشتیبانی می‌کند، باید گفتار فعلی را که درحال بیان است (درصورت وجود) موقتاً متوقف کند تا زمانی که رویداد ازسرگیری یا رویداد توقف را دریافت کند. توجه داشته باشید که رویداد توقف باید وضعیت موقتاً متوقف‌شده را نیز پاک کند.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    () => void

onResume

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

اختیاری: اگر موتوری از رویداد توقف موقت پشتیبانی می‌کند، باید از رویداد ازسرگیری نیز پشتیبانی کند تا بتواند به خواندن گفته فعلی (درصورت وجود) ادامه دهد. توجه داشته باشید که رویداد توقف باید وضعیت موقتاً متوقف‌شده را نیز پاک کند.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    () => void

onSpeak

chrome.ttsEngine.onSpeak.addListener(
  callback: function,
)

زمانی فراخوانی می‌شود که کاربر با tts.speak() تماس می‌گیرد و یکی از صداهای مانیفست این افزونه اولین صدایی است که با شیء گزینه‌ها مطابقت دارد.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (utterance: string, options: SpeakOptions, sendTtsEvent: function) => void

    • گفته

      رشته

    • گزینه‌ها

      SpeakOptions

    • sendTtsEvent

      عملکرد

      پارامتر sendTtsEvent به‌صورت زیر است: 

      (event: tts.TtsEvent) => void

      • رویداد

        tts.TtsEvent

        رویداد از موتور نوشتار به گفتار که وضعیت این گفته را نشان می‌دهد.

onSpeakWithAudioStream

Chrome نسخه ۹۲ و بالاتر 
chrome.ttsEngine.onSpeakWithAudioStream.addListener(
  callback: function,
)

زمانی فراخوانی می‌شود که کاربر با tts.speak() تماس می‌گیرد و یکی از صداهای مانیفست این افزونه اولین صدایی است که با شیء گزینه‌ها مطابقت دارد. با ttsEngine.onSpeak تفاوت دارد زیرا Chrome سرویس‌های بازپخش صدا را ارائه می‌دهد و ارسال رویدادهای tts را مدیریت می‌کند.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

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

    • گفته

      رشته

    • گزینه‌ها

      SpeakOptions

    • audioStreamOptions

      AudioStreamOptions

    • sendTtsAudio

      عملکرد

      پارامتر sendTtsAudio به‌صورت زیر است: 

      (audioBufferParams: AudioBuffer) => void

      • audioBufferParams

        AudioBuffer

        پارامترهای حاوی میان‌گیر صوتی و داده‌های مرتبط.

    • sendError

      عملکرد

      Chrome نسخه ۹۴ و بالاتر

      پارامتر sendError به‌صورت زیر است: 

      (errorMessage?: string) => void

      • errorMessage

        رشته اختیاری

        رشته‌ای که خطا را توصیف می‌کند.

onStop

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

وقتی تماسی با tts.stop برقرار می‌شود و این افزونه ممکن است درحال صحبت کردن باشد، فعال می‌شود. اگر افزونه‌ای تماسی برای onStop دریافت کند و گفتار ازقبل متوقف شده باشد، نباید کاری انجام دهد (نباید خطا ایجاد کند). اگر گفتار در حالت موقتاً متوقف‌شده باشد، این کار باید حالت موقتاً متوقف‌شده را لغو کند.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    () => void

onUninstallLanguageRequest

Chrome نسخه ۱۳۲ و بالاتر 
chrome.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

وقتی فعال می‌شود که کلاینت «نوشتار به گفتار» نشان دهد که دیگر به زبان نیازی نیست.

پارامترها