chrome.tts

refresh date: 2026-09-25 robots: noindex

Opis

Użyj interfejsu chrome.tts API, aby odtwarzać zsyntetyzowany tekst zamieniony na mowę (TTS). Zobacz też powiązany interfejs ttsEngine API, który umożliwia rozszerzeniu wdrożenie silnika mowy.

Uprawnienia

tts

Przegląd

Chrome zapewnia natywną obsługę mowy w systemach Windows (za pomocą SAPI 5), macOS i ChromeOS, korzystając z funkcji syntezy mowy udostępnianych przez system operacyjny. Na wszystkich platformach użytkownik może instalować rozszerzenia, które rejestrują się jako alternatywne silniki mowy.

Generowanie mowy

Zadzwoń pod numer speak() z rozszerzenia, aby porozmawiać. Na przykład:

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

Aby natychmiast zatrzymać odczytywanie, zadzwoń pod numer stop():

chrome.tts.stop();

Możesz podać opcje, które kontrolują różne właściwości mowy, takie jak szybkość, wysokość i inne. Na przykład:

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

Warto też określić język, aby wybrać syntezator obsługujący ten język (i w razie potrzeby dialekt regionalny).

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

Domyślnie każde wywołanie funkcji speak() przerywa trwającą mowę i natychmiast ją zastępuje. Aby sprawdzić, czy połączenie nie będzie nikomu przeszkadzać, możesz zadzwonić pod numer isSpeaking(). Możesz też użyć opcji enqueue, aby dodać tę wypowiedź do kolejki wypowiedzi, które zostaną odczytane po zakończeniu bieżącej wypowiedzi.

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

Pełny opis wszystkich opcji znajdziesz w sekcji tts.speak poniżej. Nie wszystkie silniki mowy obsługują wszystkie opcje.

Aby wykrywać błędy i mieć pewność, że wywołujesz funkcję speak() prawidłowo, przekaż funkcję wywołania zwrotnego, która nie przyjmuje argumentów. W funkcji zwrotnej sprawdź, czy nie wystąpiły żadne błędy runtime.lastError.

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

Wywołanie zwrotne jest zwracane od razu, zanim silnik zacznie generować mowę. Funkcja zwrotna ma na celu powiadamianie o błędach składni w użyciu interfejsu TTS API, a nie wykrywanie wszystkich możliwych błędów, które mogą wystąpić w procesie syntezy i generowania mowy. Aby wykrywać również te błędy, musisz użyć detektora zdarzeń opisanego poniżej.

Nasłuchiwanie zdarzeń

Aby uzyskać więcej informacji w czasie rzeczywistym o stanie syntezowanej mowy, przekaż detektor zdarzeń w opcjach do speak(), tak jak w tym przykładzie:

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

Każde zdarzenie zawiera typ zdarzenia, indeks znaku bieżącej mowy względem wypowiedzi oraz w przypadku zdarzeń związanych z błędami opcjonalny komunikat o błędzie. Typy zdarzeń:

  • 'start': silnik zaczął odtwarzać wypowiedź.
  • 'word': osiągnięto granicę słowa. Użyj event.charIndex, aby określić bieżącą pozycję mowy.
  • 'sentence': osiągnięto koniec zdania. Użyj event.charIndex, aby określić bieżącą pozycję mowy.
  • 'marker': osiągnięto znacznik SSML. Użyj event.charIndex, aby określić bieżącą pozycję mowy.
  • 'end': silnik zakończył wypowiadanie komunikatu.
  • 'interrupted': ta wypowiedź została przerwana przez inne wywołanie speak() lub stop() i nie została dokończona.
  • 'cancelled': wypowiedź została umieszczona w kolejce, ale potem anulowana przez inne wywołanie funkcji speak() lub stop() i nigdy nie została odtworzona.
  • 'error': wystąpił błąd specyficzny dla silnika i nie można wypowiedzieć tego wyrażenia. Więcej informacji znajdziesz na stronie event.errorMessage.

4 typy zdarzeń – 'end', 'interrupted', 'cancelled' i 'error' – są ostateczne. Po otrzymaniu jednego z tych zdarzeń wypowiedź nie będzie już odtwarzana i nie będą odbierane żadne nowe zdarzenia z tej wypowiedzi.

Niektóre głosy mogą nie obsługiwać wszystkich typów zdarzeń, a niektóre mogą nie wysyłać żadnych zdarzeń. Jeśli nie chcesz używać głosu, chyba że wysyła on określone zdarzenia, przekaż wymagane zdarzenia w elemencie requiredEventTypes obiektu opcji lub użyj getVoices(), aby wybrać głos spełniający Twoje wymagania. Oba te przypadki opisujemy poniżej.

Znaczniki SSML

Wypowiedzi używane w tym interfejsie API mogą zawierać znaczniki w języku znaczników syntezy mowy (SSML). Jeśli używasz SSML, pierwszym argumentem funkcji speak() powinien być kompletny dokument SSML z nagłówkiem XML i tagiem najwyższego poziomu <speak>, a nie fragment dokumentu.

Na przykład:

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

Nie wszystkie silniki mowy obsługują wszystkie tagi SSML, a niektóre mogą w ogóle nie obsługiwać SSML. Wszystkie silniki muszą jednak ignorować nieobsługiwane tagi SSML i nadal odczytywać tekst bazowy.

Wybór głosu

Domyślnie Chrome wybiera najbardziej odpowiedni głos dla każdego wypowiadanego tekstu na podstawie języka. W większości systemów Windows, Mac OS X i ChromeOS synteza mowy zapewniana przez system operacyjny powinna być w stanie odczytać dowolny tekst w co najmniej 1 języku. Niektórzy użytkownicy mogą mieć dostęp do różnych głosów z systemu operacyjnego i silników mowy zaimplementowanych przez inne rozszerzenia Chrome. W takich przypadkach możesz wdrożyć kod niestandardowy, aby wybrać odpowiedni głos lub wyświetlić użytkownikowi listę opcji.

Aby uzyskać listę wszystkich głosów, wywołaj funkcję getVoices() i przekaż jej funkcję, która jako argument otrzymuje tablicę obiektów 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);
    }
  }
);

Typy

EventType

Chrome 54 lub nowsza

Typ wyliczeniowy

„start”

"end"

„word”

„sentence”

„marker”

„interrupted”

„cancelled”

„error”

„pause”

„resume”

TtsEvent

Zdarzenie z silnika TTS, które informuje o stanie wypowiedzi.

Właściwości

  • charIndex

    number opcjonalny

    Indeks bieżącego znaku w wypowiedzi. W przypadku zdarzeń dotyczących słów zdarzenie jest wywoływane na końcu jednego słowa i przed rozpoczęciem następnego. Znak charIndex oznacza punkt w tekście na początku następnego słowa, które ma zostać wypowiedziane.

  • Komunikat o błędzie

    ciąg znaków opcjonalny

    Opis błędu, jeśli typ zdarzenia to error.

  • długość

    number opcjonalny

    Chrome 74 lub nowsza

    Długość następnej części wypowiedzi. Na przykład w przypadku zdarzenia word jest to długość słowa, które zostanie wypowiedziane jako następne. Jeśli nie zostanie ustawiony przez silnik mowy, będzie miał wartość -1.

  • typ

    EventType

    Typ może przyjmować wartości: start natychmiast po rozpoczęciu mowy, word po osiągnięciu granicy słowa, sentence po osiągnięciu granicy zdania, marker po osiągnięciu elementu znacznika SSML, end po osiągnięciu końca wypowiedzi, interrupted po zatrzymaniu lub przerwaniu wypowiedzi przed osiągnięciem końca, cancelled po usunięciu z kolejki przed syntezą lub error w przypadku wystąpienia innego błędu. Podczas wstrzymywania mowy wywoływane jest zdarzenie pause, jeśli dana wypowiedź zostanie wstrzymana w połowie, oraz zdarzenie resume, jeśli wypowiedź zostanie wznowiona. Pamiętaj, że zdarzenia wstrzymania i wznowienia mogą nie być wywoływane, jeśli mowa zostanie wstrzymana między wypowiedziami.

TtsOptions

Chrome 77 lub nowszy

Opcje mowy dla mechanizmu zamiany tekstu na mowę.

Właściwości

  • desiredEventTypes

    string[] opcjonalnie

    Typy zdarzeń TTS, których chcesz słuchać. Jeśli go brakuje, można wysyłać wszystkie typy zdarzeń.

  • dodawać do kolejki,

    wartość logiczna opcjonalna

    Jeśli wartość to „true”, wypowiedź zostanie dodana do kolejki, jeśli synteza mowy jest już w toku. Jeśli wartość to „false” (domyślnie), przerywa bieżącą mowę i czyści kolejkę mowy przed wypowiedzeniem nowego zdania.

  • extensionId

    ciąg znaków opcjonalny

    Identyfikator rozszerzenia silnika mowy do użycia, jeśli jest znany.

  • płeć

    VoiceGender opcjonalny

    Wycofane w Chrome 77

    Kryterium „Płeć” zostało wycofane i będzie ignorowane.

    Płeć głosu używanego do syntezy mowy.

  • lang

    ciąg znaków opcjonalny

    Język, który ma być używany do syntezy, w formacie język-region. Przykłady: „en”, „en-US”, „en-GB”, „zh-CN”.

  • rzut

    number opcjonalny

    Wysokość głosu w zakresie od 0 do 2 włącznie, gdzie 0 to najniższa, a 2 to najwyższa wysokość głosu. Wartość 1,0 odpowiada domyślnej wysokości głosu.

  • szybkość reakcji

    number opcjonalny

    Szybkość mówienia w stosunku do domyślnej szybkości dla tego głosu. Domyślna szybkość to 1,0, czyli zwykle około 180–220 słów na minutę. 2,0 oznacza dwukrotnie większą szybkość, a 0,5 – dwukrotnie mniejszą. Wartości poniżej 0,1 lub powyżej 10,0 są niedozwolone, ale wiele głosów będzie dodatkowo ograniczać minimalne i maksymalne tempo. Na przykład dany głos może nie mówić szybciej niż 3 razy szybciej niż normalnie, nawet jeśli podasz wartość większą niż 3,0.

  • requiredEventTypes

    string[] opcjonalnie

    Typy zdarzeń TTS, które musi obsługiwać głos.

  • voiceName

    ciąg znaków opcjonalny

    Nazwa głosu używanego na potrzeby syntezy. Jeśli to pole jest puste, używany jest dowolny dostępny głos.

  • głośność

    number opcjonalny

    Głośność mowy w zakresie od 0 do 1 włącznie, gdzie 0 oznacza najniższą głośność, a 1 – najwyższą.Wartość domyślna to 1,0.

  • onEvent

    void optional

    Ta funkcja jest wywoływana w przypadku zdarzeń, które występują podczas wypowiadania komunikatu.

    Funkcja onEvent wygląda tak:

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

    • zdarzenie

      TtsEvent

      Wydarzenie aktualizacji z silnika zamiany tekstu na mowę wskazujące stan tej wypowiedzi.

TtsVoice

Opis głosu dostępnego na potrzeby syntezy mowy.

Właściwości

  • eventTypes

    EventType[] opcjonalny

    Wszystkie typy zdarzeń wywołania zwrotnego, które ten głos może wysyłać.

  • extensionId

    ciąg znaków opcjonalny

    Identyfikator rozszerzenia, które udostępnia ten głos.

  • płeć

    VoiceGender opcjonalny

    Wycofane w Chrome 70

    Pole Gender zostało wycofane i będzie ignorowane.

    Płeć tego głosu.

  • lang

    ciąg znaków opcjonalny

    Język obsługiwany przez ten głos w formacie język-region. Przykłady: „en”, „en-US”, „en-GB”, „zh-CN”.

  • pilot

    wartość logiczna opcjonalna

    Jeśli ma wartość Prawda, silnik syntezy jest zdalnym zasobem sieciowym. Może to powodować większe opóźnienia i generować koszty związane z przepustowością.

  • voiceName

    ciąg znaków opcjonalny

    Nazwa głosu.

VoiceGender

Chrome 54 lub nowsza Wycofane w Chrome 70

Atrybut płeć został wycofany i jest ignorowany.

Typ wyliczeniowy

„male”

"female"

Metody

getVoices()

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

Pobiera tablicę wszystkich dostępnych głosów.

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (voices: TtsVoice[]) => void

    • Głosy

      TtsVoice[]

      Tablica obiektów tts.TtsVoice reprezentujących dostępne głosy do syntezy mowy.

Zwroty

  • Promise<TtsVoice[]>

    Chrome 101 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

isSpeaking()

Obietnica 
chrome.tts.isSpeaking(
  callback?: function,
): Promise<boolean>

Sprawdza, czy silnik aktualnie mówi. W systemie Mac OS X wynik jest prawdziwy, gdy silnik mowy systemu odtwarza dźwięk, nawet jeśli nie został on zainicjowany przez Chrome.

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (speaking: boolean) => void

    • mówienie,

      wartość logiczna

      Prawda, jeśli mówisz, w przeciwnym razie fałsz.

Zwroty

  • Promise<boolean>

    Chrome 101 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

pause()

chrome.tts.pause(): void

Wstrzymuje syntezę mowy, potencjalnie w trakcie wypowiedzi. Wywołanie wznowienia lub zatrzymania spowoduje wznowienie mowy.

resume()

chrome.tts.resume(): void

Jeśli mowa została wstrzymana, wznawia odtwarzanie od miejsca, w którym została przerwana.

speak()

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

Odtwarza tekst za pomocą mechanizmu zamiany tekstu na mowę.

Parametry

  • wypowiedź

    tekst

    Tekst do odczytania, w formacie zwykłego tekstu lub kompletnego, prawidłowo sformatowanego dokumentu SSML. Silniki mowy, które nie obsługują SSML, usuną tagi i odczytają tekst. Maksymalna długość tekstu to 32 768 znaków.

  • Opcje

    TtsOptions opcjonalny

    Opcje mowy.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 101 lub nowsza

    Rozwiązuje problem od razu, zanim skończy się mowa. Jeśli wystąpi błąd, obietnica zostanie odrzucona. Aby uzyskać bardziej szczegółowe informacje, użyj options.onEvent.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

stop()

chrome.tts.stop(): void

Zatrzymuje bieżącą mowę i czyści kolejkę oczekujących wypowiedzi. Jeśli mowa została wstrzymana, zostanie teraz wznowiona na potrzeby następnego wywołania funkcji mówienia.

Wydarzenia

onVoicesChanged

Chrome 124 lub nowsza 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

Wywoływana, gdy zmieni się lista obiektów tts.TtsVoice, które zostaną zwrócone przez metodę getVoices.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void