chrome.tts

refresh date: 2026-09-25 robots: noindex

شرح

از chrome.tts API برای پخش نوشتار به گفتار (TTS) ترکیبی استفاده کنید. همچنین ttsEngine API مرتبط را ببینید که به افزونه اجازه می‌دهد موتور گفتار را پیاده‌سازی کند.

اجازه‌ها

tts

نمای کلی

‫Chrome بااستفاده از قابلیت‌های ترکیب گفتار ارائه‌شده توسط سیستم‌عامل، پشتیبانی بومی برای گفتار در Windows (بااستفاده از SAPI 5)،‏ Mac OS X، و ChromeOS ارائه می‌دهد. در همه پلاتفرم‌ها، کاربر می‌تواند افزونه‌هایی را نصب کند که خودشان را به‌عنوان موتورهای گفتار جایگزین ثبت می‌کنند.

درحال تولید گفتار

برای صحبت کردن، از افزونه‌تان با speak() تماس بگیرید. برای مثال:

chrome.tts.speak('Hello, world.');

برای توقف فوری صحبت کردن، کافی است stop() را صدا بزنید:

chrome.tts.stop();

می‌توانید گزینه‌هایی را ارائه دهید که ویژگی‌های مختلف گفتار را کنترل می‌کنند، مانند سرعت، زیروبمی، و غیره. برای مثال:

chrome.tts.speak('Hello, world.', {'rate': 2.0});

همچنین ایده خوبی است که زبان را مشخص کنید تا ترکیب‌کننده‌ای که از آن زبان (و گویش منطقه‌ای، درصورت وجود) پشتیبانی می‌کند انتخاب شود.

chrome.tts.speak('Hello, world.', {'lang': 'en-US', 'rate': 2.0});

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

chrome.tts.speak('Speak this first.');
chrome.tts.speak(
    'Speak this next, when the first sentence is done.', {'enqueue': true});

شرح کامل همه گزینه‌ها را می‌توانید در tts.speak زیر پیدا کنید. همه موتورهای گفتار از همه گزینه‌ها پشتیبانی نمی‌کنند.

برای گرفتن خطاها و اطمینان از اینکه speak() را به‌درستی فراخوانی می‌کنید، تابع بازخوانی‌ای را ارسال کنید که هیچ آرگومانی نداشته باشد. درون فراخوانی برگشتی، runtime.lastError را بررسی کنید تا ببینید آیا خطایی وجود داشته است یا نه.

chrome.tts.speak(
  utterance,
  options,
  function() {
    if (chrome.runtime.lastError) {
      console.log('Error: ' + chrome.runtime.lastError.message);
    }
  }
);

فراخوانی برگشتی بلافاصله، قبل‌از اینکه موتور شروع به تولید گفتار کند، برمی‌گردد. هدف از فراخوانی برگشتی، هشدار دادن به شما درباره خطاهای نحوی در استفاده از TTS API است، نه گرفتن همه خطاهای احتمالی که ممکن است در فرایند ترکیب و خروجی گفتار رخ دهد. برای گرفتن این خطاها نیز باید از شنونده رویداد استفاده کنید که در زیر شرح داده شده است.

درحال گوش دادن به رویدادها

برای دریافت اطلاعات هم‌زمان بیشتر درباره وضعیت گفتار ترکیبی، یک شنونده رویداد را در گزینه‌ها به speak() ارسال کنید، مانند این:

chrome.tts.speak(
  utterance,
  {
    onEvent: function(event) {
      console.log('Event ' + event.type + ' at position ' + event.charIndex);
      if (event.type == 'error') {
        console.log('Error: ' + event.errorMessage);
      }
    }
  },
  callback
);

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

  • 'start': موتور شروع به خواندن عبارت کرده است.
  • 'word': به مرز کلمه رسیدید. از event.charIndex برای تعیین موقعیت گفتار فعلی استفاده کنید.
  • 'sentence': به مرز جمله رسید. از event.charIndex برای تعیین موقعیت گفتار فعلی استفاده کنید.
  • 'marker': به نشانگر SSML رسید. از event.charIndex برای تعیین موقعیت گفتار فعلی استفاده کنید.
  • ‫'end': موتور خواندن عبارت را به‌پایان رسانده است.
  • ‫'interrupted': این گفته با تماس دیگری با speak() یا stop() قطع شد و تمام نشد.
  • 'cancelled': این گفته در صف قرار گرفت، اما سپس با تماس دیگری با speak() یا stop() لغو شد و اصلاً شروع به صحبت نکرد.
  • 'error': خطای خاص موتور روی داد و این گفته نمی‌تواند بیان شود. برای جزئیات، event.errorMessage را بررسی کنید.

چهار نوع رویداد—'end'،‏ 'interrupted'،‏ 'cancelled'، و 'error'—نهایی هستند. پس‌از دریافت یکی از این رویدادها، این گفته دیگر صحبت نخواهد کرد و هیچ رویداد جدیدی از این گفته دریافت نخواهد شد.

برخی‌از صداها ممکن است از همه انواع رویداد پشتیبانی نکنند و برخی‌از صداها ممکن است اصلاً هیچ رویدادی ارسال نکنند. اگر نمی‌خواهید از صدایی استفاده کنید مگراینکه رویدادهای خاصی را ارسال کند، رویدادهای موردنیازتان را در عضو requiredEventTypes شیء گزینه‌ها ارسال کنید، یا از getVoices() برای انتخاب صدایی که الزامات شما را برآورده می‌کند استفاده کنید. هر دو در زیر مستند شده‌اند.

نشانه‌گذاری SSML

گفته‌های استفاده‌شده در این API ممکن است شامل نشانه‌گذاری بااستفاده از Speech Synthesis Markup Language (SSML) باشد. اگر از SSML استفاده می‌کنید، اولین آرگومان speak() باید سند SSML کامل با سرصفحه XML و برچسب <speak> سطح بالا باشد، نه قطعه‌ای از سند.

برای مثال:

chrome.tts.speak(
  '<?xml version="1.0"?>' +
  '<speak>' +
  '  The <emphasis>second</emphasis> ' +
  '  word of this sentence was emphasized.' +
  '</speak>'
);

همه موتورهای گفتار از همه برچسب‌های SSML پشتیبانی نمی‌کنند و برخی ممکن است اصلاً از SSML پشتیبانی نکنند، اما همه موتورها باید هر SSML را که پشتیبانی نمی‌کنند نادیده بگیرند و همچنان نوشتار اصلی را بخوانند.

انتخاب کردن صدا

به‌طور پیش‌فرض، Chrome مناسب‌ترین صدا را برای هر گفتاری که می‌خواهید بیان کنید، براساس زبان انتخاب می‌کند. در اکثر سیستم‌های Windows،‏ Mac OS X، و ChromeOS، ترکیب گفتار ارائه‌شده توسط سیستم‌عامل باید بتواند هر نوشتاری را حداقل به یک زبان بخواند. بااین‌حال، ممکن است برخی‌از کاربران صداهای متنوعی از سیستم‌عامل خود و از موتورهای گفتار پیاده‌سازی‌شده توسط سایر افزونه‌های Chrome دردسترس داشته باشند. در این موارد، می‌توانید کد سفارشی را برای انتخاب صدای مناسب پیاده‌سازی کنید، یا فهرستی از انتخاب‌ها را به کاربر ارائه دهید.

برای دریافت فهرست همه صداها، getVoices() را فراخوانی کنید و تابعی را به آن ارسال کنید که آرایه‌ای از اشیاء TtsVoice را به‌عنوان آرگومان خود دریافت می‌کند:

chrome.tts.getVoices(
  function(voices) {
    for (var i = 0; i < voices.length; i++) {
      console.log('Voice ' + i + ':');
      console.log('  name: ' + voices[i].voiceName);
      console.log('  lang: ' + voices[i].lang);
      console.log('  extension id: ' + voices[i].extensionId);
      console.log('  event types: ' + voices[i].eventTypes);
    }
  }
);

انواع

EventType

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

شمارشی

«start»

«پایان»

"word"

"sentence"

«نشانگر»

«interrupted»

«لغوشده»

"error"

«توقف موقت»

«ازسر گرفتن»

TtsEvent

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

مشخصات

  • charIndex

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

    نمایه نویسه فعلی در گفتار. برای رویدادهای کلمه‌ای، رویداد در پایان یک کلمه و قبل‌از شروع کلمه بعدی اجرا می‌شود. charIndex نشان‌دهنده نقطه‌ای در نوشتار در ابتدای کلمه بعدی است که باید گفته شود.

  • errorMessage

    رشته اختیاری

    شرح خطا، اگر نوع رویداد error باشد.

  • طول

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

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

    طول بخش بعدی گفتار. برای مثال، در رویداد word، این طول کلمه‌ای است که بعداز آن گفته خواهد شد. اگر توسط موتور گفتار تنظیم نشده باشد، روی ۱- تنظیم می‌شود.

  • نوع

    EventType

    نوع می‌تواند start به‌محض شروع گفتار، word هنگام رسیدن به مرز کلمه، sentence هنگام رسیدن به مرز جمله، marker هنگام رسیدن به عنصر علامت SSML، end هنگام رسیدن به پایان گفته، interrupted هنگام توقف یا قطع شدن گفته قبل‌از رسیدن به پایان، cancelled هنگام حذف شدن از صف قبل‌از ترکیب شدن، یا error هنگام رخ دادن هر خطای دیگری باشد. هنگام توقف موقت گفتار، اگر گفتار خاصی در وسط متوقف شود، رویداد pause فعال می‌شود و اگر گفتار ازسر گرفته شود، رویداد resume فعال می‌شود. توجه داشته باشید که اگر گفتار در بین گفته‌ها موقتاً متوقف شود، ممکن است رویدادهای توقف موقت و ازسرگیری اجرا نشوند.

TtsOptions

Chrome نسخه ۷۷ به بالا

گزینه‌های گفتار برای موتور «نوشتار به گفتار».

مشخصات

  • desiredEventTypes

    رشته[] اختیاری

    انواع رویدادهای TTS که می‌خواهید به آن‌ها گوش دهید. اگر وجود نداشته باشد، ممکن است همه انواع رویداد ارسال شود.

  • در صف قرار دادن

    بولی اختیاری

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

  • extensionId

    رشته اختیاری

    شناسه افزونه موتور گفتار برای استفاده، درصورت مشخص بودن.

  • جنسیت

    VoiceGender اختیاری

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

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

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

  • lang

    رشته اختیاری

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

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

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

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

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

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

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

  • requiredEventTypes

    رشته[] اختیاری

    انواع رویدادهای نوشتار به گفتار که صدا باید از آن‌ها پشتیبانی کند.

  • voiceName

    رشته اختیاری

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

  • میزان صدا

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

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

  • onEvent

    void اختیاری

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

    تابع onEvent به‌صورت زیر است: 

    (event: TtsEvent) => {...}

    • رویداد

      TtsEvent

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

TtsVoice

شرحی از صدای دردسترس برای ترکیب گفتار.

مشخصات

  • eventTypes

    EventType[] اختیاری

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

  • extensionId

    رشته اختیاری

    شناسه افزونه‌ای که این صدا را ارائه می‌دهد.

  • جنسیت

    VoiceGender اختیاری

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

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

    جنسیت این صدا.

  • lang

    رشته اختیاری

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

  • دورکاری

    بولی اختیاری

    اگر درست باشد، موتور ترکیب منبع شبکه از راه دور است. ممکن است تأخیر بیشتر باشد و هزینه پهنای باند اعمال شود.

  • voiceName

    رشته اختیاری

    نام صدا.

VoiceGender

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

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

شمارشی

"male"

"female"

روش‌ها

getVoices()

قول 
chrome.tts.getVoices(
  callback?: function,
): Promise<TtsVoice[]>

آرایه‌ای از همه صداهای دردسترس را دریافت می‌کند.

پارامترها

  • تماس برگشتی

    تابع اختیاری

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

    (voices: TtsVoice[]) => void

    • صداها

      TtsVoice[]

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

بازگشتی‌ها

  • Promise<TtsVoice[]>

    Chrome نسخه ۱۰۱ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

isSpeaking()

قول 
chrome.tts.isSpeaking(
  callback?: function,
): Promise<boolean>

بررسی می‌کند که آیا موتور درحال‌حاضر درحال صحبت کردن است یا نه. در Mac OS X، هرگاه موتور گفتار سیستم درحال صحبت کردن باشد، نتیجه درست است، حتی اگر گفتار توسط Chrome آغاز نشده باشد.

پارامترها

  • تماس برگشتی

    تابع اختیاری

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

    (speaking: boolean) => void

    • صحبت کردن

      بولی

      اگر درحال صحبت کردن باشد، درست است و درغیراین‌صورت نادرست است.

بازگشتی‌ها

  • Promise<boolean>

    Chrome نسخه ۱۰۱ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

pause()

chrome.tts.pause(): void

ترکیب گفتار را موقتاً متوقف می‌کند، احتمالاً در وسط یک گفته. درخواست ازسرگیری یا توقف، گفتار را از حالت مکث خارج می‌کند.

resume()

chrome.tts.resume(): void

اگر گفتار موقتاً متوقف شده باشد، صحبت کردن را از جایی که متوقف شده بود ازسر می‌گیرد.

speak()

قول 
chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
): Promise<void>

نوشتار را بااستفاده از موتور نوشتار به گفتار می‌خواند.

پارامترها

  • گفته

    رشته

    نوشتاری که باید خوانده شود، نوشتار ساده یا سند SSML کامل و خوش‌ساخت. موتورهای گفتاری که از SSML پشتیبانی نمی‌کنند برچسب‌ها را حذف می‌کنند و نوشتار را می‌خوانند. حداکثر طول نوشتار ۳۲٬۷۶۸ نویسه است.

  • گزینه‌ها

    TtsOptions اختیاری

    گزینه‌های گفتار.

  • تماس برگشتی

    تابع اختیاری

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

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۰۱ به بالا

    بلافاصله، قبل‌از پایان گفتار، حل می‌شود. اگر خطایی رخ دهد، promise رد خواهد شد. برای دریافت بازخورد دقیق‌تر، از options.onEvent استفاده کنید.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

stop()

chrome.tts.stop(): void

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

رویدادها

onVoicesChanged

Chrome نسخه ۱۲۴ و بالاتر 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

وقتی فهرست tts.TtsVoice که توسط getVoices برگردانده می‌شود تغییر کرده باشد، فراخوانی می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

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

    () => void