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 menyediakan opsi yang mengontrol berbagai properti ucapan, seperti kecepatan, tinggi nada, dan banyak lagi. Contoh:

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

Ide baik juga untuk menentukan bahasa sehingga {i>synthesizer<i} mendukung bahasa tersebut (dan regional, jika ada) akan dipilih.

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

Secara default, setiap panggilan ke speak() mengganggu semua ucapan yang sedang berlangsung dan langsung berbicara. Kepada menentukan apakah panggilan akan mengganggu apa pun, Anda dapat memanggil isSpeaking(). Selain itu, Anda dapat menggunakan opsi enqueue untuk menyebabkan ucapan ini ditambahkan ke antrean ucapan yang akan diucapkan setelah ucapan saat ini 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 tts.speak(). Tidak semua ucapan akan mendukung semua opsi.

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

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

Callback langsung kembali, sebelum mesin mulai menghasilkan ucapan. Tujuan dari adalah untuk memberi tahu Anda tentang error sintaksis dalam penggunaan TTS API, bukan untuk menangkap semua kemungkinan kesalahan yang mungkin terjadi dalam proses sintesis dan pembuatan {i>output<i} ucapan. Untuk menangkap error ini Anda juga perlu menggunakan pemroses peristiwa, yang dijelaskan di bagian berikutnya.

Memproses peristiwa

Untuk mendapatkan informasi real-time lebih lanjut tentang status ucapan yang disintesis, teruskan pemroses peristiwa di opsi untuk 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 mencakup jenis peristiwa, indeks karakter ucapan saat ini relatif dengan ucapan, dan untuk kejadian {i>error<i}, pesan {i>error<i} opsional. Jenis peristiwanya adalah:

  • 'start': Mesin mulai mengucapkan ucapan.
  • 'word': Batas kata tercapai. Gunakan event.charIndex untuk menentukan ucapan saat ini posisi Anda.
  • 'sentence': Batas kalimat tercapai. Gunakan event.charIndex untuk menentukan posisi ucapan.
  • 'marker': Penanda SSML tercapai. Gunakan event.charIndex untuk menentukan ucapan saat ini posisi Anda.
  • 'end': Mesin telah selesai mengucapkan ucapan tersebut.
  • 'interrupted': Ucapan ini diganggu oleh panggilan lain ke speak() atau stop() dan melakukan belum selesai.
  • 'cancelled': Ucapan ini dimasukkan ke dalam antrean, 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. Periksa event.errorMessage untuk mengetahui detailnya.

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

Beberapa suara mungkin tidak mendukung semua jenis peristiwa, dan beberapa suara mungkin tidak mengirimkan peristiwa apa pun. Jika Anda tidak ingin menggunakan suara kecuali suara mengirimkan peristiwa tertentu, teruskan peristiwa yang Anda perlukan dalam requiredEventTypes anggota objek opsi, atau gunakan getVoices() untuk memilih suara yang sesuai persyaratan Anda. Keduanya akan dijelaskan dalam penjelasan berikut.

Markup SSML

Ucapan yang digunakan dalam API ini dapat mencakup markup yang 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 teratas, 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 mendukung semua tag SSML, dan beberapa mungkin tidak mendukung SSML sama sekali, tetapi semua mesin diwajibkan untuk mengabaikan SSML apa pun yang tidak didukung dan 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 disediakan oleh sistem operasi harus dapat mengucapkan teks apa pun setidaknya dalam satu bahasa. Beberapa pengguna mungkin memiliki berbagai suara yang tersedia, dari sistem operasinya dan dari mesin ucapan yang diimplementasikan oleh ekstensi Chrome lainnya. Dalam kasus tersebut, Anda dapat menerapkan kode kustom untuk memilih suara, atau untuk menampilkan daftar pilihan kepada pengguna.

Untuk mendapatkan daftar semua suara, panggil getVoices() dan teruskan fungsi yang akan 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 dan yang lebih baru

Enum

"start"

"akhir"

"kata"

"kalimat"

"penanda"

"terganggu"

"dibatalkan"

"error"

"jeda"

"lanjutkan"

TtsEvent

Kejadian dari mesin TTS untuk mengomunikasikan status ucapan.

Properti

  • charIndex

    angka opsional

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

  • errorMessage

    string opsional

    Deskripsi error, jika jenis peristiwanya adalah error.

  • panjang

    angka opsional

    Chrome 74 dan yang lebih baru

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

  • jenis

    EventType

    Jenisnya bisa start segera setelah ucapan dimulai, word saat batas kata tercapai, sentence saat batas kalimat tercapai, marker saat elemen tanda SSML tercapai, end saat akhir ucapan tercapai, interrupted saat ucapan dihentikan atau diinterupsi sebelum mencapai akhir, cancelled saat dihapus dari antrean sebelum disintesis, atau error saat error lain terjadi. Saat menjeda ucapan, peristiwa pause akan diaktifkan jika ucapan tertentu dijeda di tengahnya, dan resume jika ucapan melanjutkan ucapan. Perhatikan bahwa peristiwa jeda dan lanjutkan mungkin tidak 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 mungkin akan dikirim.

  • antrean

    boolean opsional

    Jika benar, mengantrekan ucapan ini jika TTS sudah berlangsung. Jika false (default), akan menginterupsi 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.

    Jenis kelamin suara untuk ucapan yang disintesis.

  • lang

    string opsional

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

  • pitch

    angka opsional

    Tinggi nada berbicara antara 0 dan 2 inklusif, dengan 0 adalah nilai terendah dan 2 adalah yang tertinggi. 1.0 sesuai dengan tinggi nada default suara.

  • laju

    angka opsional

    Kecepatan bicara relatif terhadap frekuensi 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 sangat dilarang, tetapi banyak suara akan membatasi tingkat minimum dan maksimum lebih lanjut—misalnya suara tertentu mungkin sebenarnya tidak 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 yang tersedia.

  • volume

    angka opsional

    Volume ucapan antara 0 dan 1 inklusif, dengan 0 adalah terendah dan 1 adalah tertinggi, dengan default 1,0.

  • onEvent

    batal opsional

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

    Fungsi onEvent akan terlihat seperti ini: 

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

    • peristiwa

      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 bahasa-wilayah. 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 mungkin menimbulkan biaya bandwidth.

  • voiceName

    string opsional

    Nama suara.

VoiceGender

Chrome 54 dan yang lebih baru Tidak digunakan lagi sejak Chrome 70

Gender tidak digunakan lagi dan diabaikan.

Enum

"laki-laki"

"perempuan"

Metode

getVoices()

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

Mendapatkan array dari semua suara yang tersedia.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (voices: TtsVoice[]) => void

    • suara

      TtsVoice[]

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

Hasil

  • Promise&lt;TtsVoice[]&gt;

    Chrome 101 dan yang lebih baru

    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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

isSpeaking()

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

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

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (speaking: boolean) => void

    • berbicara

      boolean

      Benar jika berbicara, salah jika tidak.

Hasil

  • Promise&lt;boolean&gt;

    Chrome 101 dan yang lebih baru

    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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

pause()

chrome.tts.pause()

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

resume()

chrome.tts.resume()

Jika ucapan dijeda, melanjutkan bicara dari bagian terakhir yang terakhir diucapkan.

speak()

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

Mengucapkan teks menggunakan mesin text-to-speech.

Parameter

  • ucapan

    string

    Teks yang akan diucapkan, baik teks biasa atau dokumen SSML lengkap yang dibentuk 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 ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 101 dan yang lebih baru

    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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

stop()

chrome.tts.stop()

Menghentikan ucapan saat ini dan menghapus antrean ucapan yang tertunda. Selain itu, jika ucapan dijeda, suara kini tidak akan dijeda untuk panggilan berikutnya.

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 ini: 

    () => void