chrome.tts

Deskripsi

Gunakan chrome.tts API untuk memutar text-to-speech (TTS) yang disintesis. Lihat juga ttsEngine API terkait, yang memungkinkan ekstensi untuk mengimplementasikan mesin ucapan.

Chrome menyediakan kemampuan ini di Windows (menggunakan SAPI 5), Mac OS X, dan ChromeOS, menggunakan kemampuan sintesis ucapan yang disediakan oleh sistem operasi. Di semua platform, pengguna dapat menginstal ekstensi yang mendaftarkan dirinya sebagai mesin ucapan alternatif.

Izin

tts

Konsep dan penggunaan

Buat ucapan

Panggil speak() dari ekstensi Anda untuk berbicara. Contoh:

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

Untuk langsung berhenti berbicara, cukup panggil stop():

chrome.tts.stop();

Anda dapat memberikan opsi yang mengontrol berbagai properti ucapan, seperti kecepatan, nada, dan lainnya. Contoh:

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

Sebaiknya tentukan bahasa sehingga synthesizer yang mendukung bahasa tersebut (dan dialek regional, jika ada) akan dipilih.

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

Secara default, setiap panggilan ke speak() mengganggu ucapan yang sedang berlangsung dan langsung berbicara. Untuk menentukan apakah panggilan akan mengganggu apa pun, Anda dapat memanggil isSpeaking(). Selain itu, Anda dapat menggunakan opsi enqueue agar ucapan ini ditambahkan ke antrean ucapan yang akan diucapkan ketika ucapan saat ini telah selesai.

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

Deskripsi lengkap semua opsi dapat ditemukan di bagian tts.speak(). Tidak semua mesin ucapan mendukung semua opsi.

Untuk menemukan error dan memastikan Anda memanggil speak() dengan benar, teruskan fungsi callback yang tidak memerlukan argumen. Di dalam callback, periksa runtime.lastError untuk melihat apakah ada error.

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

Callback langsung ditampilkan, sebelum mesin mulai membuat ucapan. Tujuan callback adalah untuk memberi tahu Anda tentang error sintaksis dalam penggunaan TTS API, bukan untuk menangkap semua kemungkinan error yang mungkin terjadi dalam proses sintesis dan pembuatan output ucapan. Untuk menangkap error ini juga, Anda perlu menggunakan pemroses peristiwa, yang dijelaskan di bagian berikutnya.

Memproses peristiwa

Untuk mendapatkan informasi selengkapnya tentang status ucapan yang disintesis secara real-time, teruskan pemroses peristiwa dalam opsi ke speak(), seperti ini:

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
);

Setiap peristiwa menyertakan jenis peristiwa, indeks karakter ucapan saat ini yang relatif terhadap ucapan, dan untuk peristiwa error, pesan error opsional. Jenis peristiwa tersebut adalah:

  • 'start': Mesin telah mulai mengucapkan ucapan.
  • 'word': Batas kata tercapai. Gunakan event.charIndex untuk menentukan posisi ucapan saat ini.
  • 'sentence': Batas kalimat tercapai. Gunakan event.charIndex untuk menentukan posisi ucapan saat ini.
  • 'marker': Penanda SSML tercapai. Gunakan event.charIndex untuk menentukan posisi ucapan saat ini.
  • 'end': Mesin telah selesai mengucapkan ucapan.
  • 'interrupted': Ucapan ini diinterupsi oleh panggilan lain ke speak() atau stop() dan tidak selesai.
  • 'cancelled': Ucapan ini diantrekan, tetapi kemudian dibatalkan oleh panggilan lain ke speak() atau stop() dan tidak pernah mulai berbicara sama sekali.
  • 'error': Terjadi error khusus mesin dan ucapan ini tidak dapat diucapkan. Untuk detailnya, lihat event.errorMessage.

Empat jenis peristiwa—'end', 'interrupted', 'cancelled', dan 'error'—adalah final. Setelah salah satu peristiwa tersebut diterima, ucapan ini tidak akan diucapkan lagi dan tidak ada peristiwa baru dari ucapan ini yang akan diterima.

Beberapa suara mungkin tidak mendukung semua jenis peristiwa, dan sebagian suara mungkin tidak mengirimkan peristiwa sama sekali. Jika Anda tidak ingin menggunakan suara, kecuali mengirimkan peristiwa tertentu, teruskan peristiwa yang diperlukan dalam anggota requiredEventTypes objek opsi, atau gunakan getVoices() untuk memilih suara yang memenuhi persyaratan Anda. Keduanya dijelaskan dalam berikut ini.

Markup SSML

Ucapan yang digunakan dalam API ini dapat mencakup markup menggunakan Bahasa Markup Sintesis Ucapan (SSML). Jika Anda menggunakan SSML, argumen pertama untuk speak() harus berupa dokumen SSML lengkap dengan header XML dan tag <speak> level atas, bukan fragmen dokumen.

Contoh:

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

Tidak semua mesin ucapan akan mendukung semua tag SSML, dan sebagian mungkin tidak mendukung SSML sama sekali, tetapi semua mesin harus mengabaikan SSML yang tidak didukung dan agar tetap mengucapkan teks yang mendasarinya.

Pilih suara

Secara default, Chrome memilih suara yang paling sesuai untuk setiap ucapan yang ingin Anda ucapkan, berdasarkan bahasa. Pada sebagian besar sistem Windows, Mac OS X, dan ChromeOS, sintesis ucapan yang disediakan oleh sistem operasi harus dapat mengucapkan teks apa pun setidaknya dalam satu bahasa. Namun, beberapa pengguna mungkin memiliki berbagai suara yang tersedia, dari sistem operasi mereka dan mesin ucapan yang diimplementasikan oleh ekstensi Chrome lainnya. Dalam hal ini, Anda dapat menerapkan kode kustom untuk memilih suara yang sesuai, atau untuk memberi pengguna daftar pilihan.

Untuk mendapatkan daftar semua suara, panggil getVoices() dan teruskan fungsi yang menerima array objek TtsVoice sebagai argumennya:

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);
    }
  }
);

Jenis

EventType

Chrome 54+

Enum

"error"

TtsEvent

Peristiwa dari mesin TTS untuk mengomunikasikan status ucapan.

Properti

  • charIndex

    nomor opsional

    Indeks karakter saat ini dalam ucapan. Untuk peristiwa kata, peristiwa dipicu di akhir satu kata dan sebelum awal kata berikutnya. charIndex mewakili satu titik dalam teks di awal kata berikutnya yang akan diucapkan.

  • errorMessage

    string opsional

    Deskripsi error, jika jenis peristiwa adalah error.

  • length

    nomor opsional

    Chrome 74 dan yang lebih baru

    Panjang bagian berikutnya dari ucapan tersebut. Misalnya, dalam peristiwa word, ini adalah panjang kata yang akan diucapkan selanjutnya. Nilainya akan ditetapkan ke -1 jika tidak disetel oleh mesin ucapan.

  • tipe

    EventType

    Jenis ucapan dapat berupa start segera setelah ucapan dimulai, word saat batas kata tercapai, sentence saat batas kalimat tercapai, marker saat elemen tanda SSML tercapai, end saat ucapan berakhir atau selesai, interrupted saat ucapan dihentikan atau diinterupsi sebelum mencapai akhir, cancelled saat ucapan dihapus dari antrean sebelum disintesis, atau error saat terjadi error lain. Saat menjeda ucapan, peristiwa pause akan diaktifkan jika ucapan tertentu dijeda di tengah, dan resume jika ucapan melanjutkan ucapan. Perhatikan bahwa peristiwa jeda dan lanjutkan mungkin tidak akan diaktifkan jika ucapan dijeda di antara ucapan.

TtsOptions

Chrome 77 dan yang lebih baru

Opsi ucapan untuk mesin TTS.

Properti

  • desiredEventTypes

    string[] opsional

    Jenis peristiwa TTS yang ingin Anda dengarkan. Jika tidak ada, semua jenis peristiwa dapat dikirim.

  • antrean

    boolean opsional

    Jika true (benar), mengantrekan ucapan ini jika TTS sudah berlangsung. Jika false (default), akan menyela ucapan saat ini dan menghapus antrean ucapan sebelum mengucapkan ucapan baru ini.

  • extensionId

    string opsional

    ID ekstensi mesin ucapan yang akan digunakan, jika diketahui.

  • gender

    VoiceGender opsional

    Tidak digunakan lagi sejak Chrome 77

    Gender tidak digunakan lagi dan akan diabaikan.

    Gender suara untuk ucapan yang disintesis.

  • lang

    string opsional

    Bahasa yang akan digunakan untuk sintesis, dalam bentuk language-region. Contoh: 'en', 'en-US', 'en-GB', 'zh-CN'.

  • pitch

    nomor opsional

    Berbicara dengan nada antara 0 dan 2 inklusif, dengan 0 sebagai terendah dan 2 sebagai tertinggi. 1.0 sesuai dengan nada default suara.

  • laju

    nomor opsional

    Kecepatan bicara relatif terhadap kecepatan default untuk suara ini. 1.0 adalah tingkat default, biasanya sekitar 180 hingga 220 kata per menit. 2,0 dua kali lebih cepat, dan 0,5 adalah setengah lebih cepat. Nilai di bawah 0,1 atau di atas 10,0 tidak diizinkan, tetapi banyak suara akan membatasi tingkat minimum dan maksimum lebih jauh—misalnya suara tertentu mungkin tidak benar-benar berbicara lebih cepat dari 3 kali normal meskipun Anda menentukan nilai yang lebih besar dari 3,0.

  • requiredEventTypes

    string[] opsional

    Jenis peristiwa TTS yang harus didukung suara.

  • voiceName

    string opsional

    Nama suara yang akan digunakan untuk sintesis. Jika kosong, gunakan suara apa pun yang tersedia.

  • volume

    nomor opsional

    Volume berbicara antara 0 dan 1 inklusif, dengan 0 sebagai terendah dan 1 sebagai tertinggi, dengan default 1.0.

  • onEvent

    membatalkan opsional

    Fungsi ini dipanggil dengan peristiwa yang terjadi dalam proses pengucapan ucapan.

    Fungsi onEvent terlihat seperti: 

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

    • event

      TtsEvent

      Peristiwa pembaruan dari mesin text-to-speech yang menunjukkan status ucapan ini.

TtsVoice

Deskripsi suara yang tersedia untuk sintesis ucapan.

Properti

  • eventTypes

    EventType[] opsional

    Semua jenis peristiwa callback yang dapat dikirim suara ini.

  • extensionId

    string opsional

    ID ekstensi yang menyediakan suara ini.

  • gender

    VoiceGender opsional

    Tidak digunakan lagi sejak Chrome 70

    Gender tidak digunakan lagi dan akan diabaikan.

    Gender suara ini.

  • lang

    string opsional

    Bahasa yang didukung suara ini, dalam bentuk language-region. Contoh: 'en', 'en-US', 'en-GB', 'zh-CN'.

  • remote

    boolean opsional

    Jika true (benar), mesin sintesis adalah resource jaringan jarak jauh. Latensi mungkin lebih tinggi dan dapat dikenai biaya bandwidth.

  • voiceName

    string opsional

    Nama suara.

VoiceGender

Chrome 54+ Tidak digunakan lagi sejak Chrome 70

Gender tidak digunakan lagi dan diabaikan.

Enum

Metode

getVoices()

Promise 
chrome.tts.getVoices(
  callback?: function,
)

Mendapatkan array dari semua suara yang tersedia.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (voices: TtsVoice[])=>void

    • suara

      TtsVoice[]

      Array objek tts.TtsVoice yang mewakili suara yang tersedia untuk sintesis ucapan.

Hasil

  • Promise<TtsVoice[]>

    Chrome 101+

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

isSpeaking()

Promise 
chrome.tts.isSpeaking(
  callback?: function,
)

Memeriksa apakah mesin sedang berbicara. Di Mac OS X, hasilnya adalah benar setiap kali mesin ucapan sistem berbicara, meskipun ucapan tidak dimulai oleh Chrome.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (speaking: boolean)=>void

    • berbicara

      boolean

      Benar jika berbicara, salah jika sebaliknya.

Hasil

  • Promise<boolean>

    Chrome 101+

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

pause()

chrome.tts.pause()

Menjeda sintesis ucapan, kemungkinan di tengah ucapan. Panggilan untuk melanjutkan atau menghentikan akan membatalkan jeda ucapan.

resume()

chrome.tts.resume()

Jika ucapan dijeda, ucapan akan dilanjutkan dari posisi terakhir.

speak()

Promise 
chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
)

Mengucapkan teks menggunakan mesin text-to-speech.

Parameter

  • ucapan

    string

    Teks yang digunakan, bisa berupa teks biasa atau sebuah dokumen SSML yang lengkap dan tersusun dengan baik. Mesin ucapan yang tidak mendukung SSML akan menghapus tag dan mengucapkan teks. Panjang maksimum teks adalah 32.768 karakter.

  • opsi

    TtsOptions opsional

    Opsi ucapan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 101+

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

stop()

chrome.tts.stop()

Menghentikan semua ucapan saat ini dan menghapus antrean ucapan yang tertunda. Selain itu, jika ucapan dijeda, ucapan akan dilanjutkan untuk panggilan berikutnya yang akan diucapkan.

Acara

onVoicesChanged

Chrome 124 dan yang lebih baru 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

Dipanggil saat daftar tts.TtsVoice yang akan ditampilkan oleh getVoices telah berubah.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    ()=>void