chrome.tts

refresh date: 2026-09-25 robots: noindex

Opis

Użyj interfejsu API chrome.tts, aby odtwarzać syntetyzowaną zamianę tekstu na mowę (TTS). Zobacz też powiązany interfejs API ttsEngine, który umożliwia rozszerzeniu implementację silnika mowy.

Uprawnienia

tts

Przegląd

Chrome zapewnia natywną obsługę mowy w systemach Windows (przy użyciu SAPI 5), Mac OS X 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

Aby rozmawiać, zadzwoń pod numer speak() z rozszerzenia. Na przykład:

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

Aby natychmiast przestać mówić, po prostu powiedz 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 został wybrany syntezator obsługujący dany język (i dialekt regionalny, jeśli dotyczy).

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

Domyślnie każde wywołanie funkcji speak() przerywa bieżącą mowę i natychmiast odczytuje tekst. Aby sprawdzić, czy połączenie nie będzie przeszkadzać, możesz zadzwonić do: 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 tts.speak poniżej. Nie wszystkie silniki mowy obsługują wszystkie opcje.

Aby wychwytywać błędy i upewnić się, że wywołujesz speak() prawidłowo, przekaż wywołanie zwrotne, które nie przyjmuje żadnych argumentów. W wywołaniu zwrotnym sprawdź runtime.lastError, aby zobaczyć, czy wystąpiły błędy.

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ę. Wywołanie zwrotne ma na celu powiadomienie o błędach składniowych w korzystaniu z interfejsu TTS API, a nie wychwycenie 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ń, który opisujemy poniżej.

Nasłuchiwanie zdarzeń

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

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 znaków bieżącej mowy względem wypowiedzi, a w przypadku zdarzeń błędów – opcjonalny komunikat o błędzie. Typy zdarzeń:

• 'start': silnik zaczął odczytywać wypowiedź.
• 'word': osiągnięto granicę słowa. Użyj event.charIndex, aby określić bieżącą pozycję mowy.
• 'sentence': osiągnięto granicę 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ł odczytywanie wypowiedzi.
• 'interrupted': ta wypowiedź została przerwana przez inne wywołanie speak() lub stop() i nie została ukończona.
• 'cancelled': ta wypowiedź została umieszczona w kolejce, ale następnie anulowana przez inne wywołanie funkcji speak() lub stop() i nigdy nie została odczytana.
• 'error': wystąpił błąd związany z silnikiem i nie można odczytać tej wypowiedzi. Więcej informacji znajdziesz na stronie event.errorMessage.

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

Niektóre głosy mogą nie obsługiwać wszystkich typów zdarzeń, a inne mogą w ogóle nie wysyłać 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, który spełnia Twoje wymagania. Obie metody są opisane poniżej.

Znaczniki SSML

Wypowiedzi używane w tym interfejsie API mogą zawierać znaczniki używające języka 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 <speak> najwyższego poziomu, 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, ale wszystkie silniki muszą ignorować nieobsługiwane tagi SSML i nadal odczytywać tekst.

Wybór głosu

Domyślnie Chrome wybiera najbardziej odpowiedni głos dla każdej wypowiedzi, którą chcesz odczytać, na podstawie języka. W większości systemów Windows, Mac OS X i ChromeOS synteza mowy zapewniana przez system operacyjny powinna umożliwiać odczytywanie dowolnego tekstu 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 do Chrome. W takich przypadkach możesz zaimplementować niestandardowy kod, aby wybrać odpowiedni głos lub wyświetlić użytkownikowi listę opcji.

Aby uzyskać listę wszystkich głosów, wywołaj getVoices() i przekaż funkcję, która otrzymuje tablicę obiektów TtsVoice jako argument:

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 wersja

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 optional

  Indeks bieżącego znaku w wypowiedzi. W przypadku zdarzeń słownych zdarzenie jest wywoływane na końcu jednego słowa i przed rozpoczęciem następnego. charIndex reprezentuje 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 optional

  Chrome 74 lub nowsza wersja

  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 ustawiona przez mechanizm mowy, będzie miała wartość -1.

• typ

  EventType

  Typ może być start, gdy tylko mowa się rozpocznie, word, gdy zostanie osiągnięta granica słowa, sentence, gdy zostanie osiągnięta granica zdania, marker, gdy zostanie osiągnięty element znacznika SSML, end, gdy zostanie osiągnięty koniec wypowiedzi, interrupted, gdy wypowiedź zostanie zatrzymana lub przerwana przed osiągnięciem końca, cancelled, gdy zostanie usunięta z kolejki przed syntezą, lub error, gdy wystąpi jakikolwiek inny błąd. Podczas wstrzymywania mowy wywoływane jest zdarzenie pause, jeśli konkretna wypowiedź zostanie wstrzymana w połowie, oraz resume, jeśli wypowiedź zostanie wznowiona. Pamiętaj, że zdarzenia wstrzymania i wznowienia mogą nie zostać wywołane, jeśli mowa zostanie wstrzymana między wypowiedziami.

TtsOptions

Chrome 77 lub nowsza wersja

Opcje mowy dla mechanizmu TTS.

Właściwości

• desiredEventTypes

  string[] opcjonalne

  Typy zdarzeń TTS, które chcesz odsłuchiwać. Jeśli go nie ma, mogą być wysyłane wszystkie typy zdarzeń.

• enqueue

  boolean opcjonalne

  Jeśli ma wartość Prawda, dodaje tę wypowiedź do kolejki, jeśli TTS jest już w toku. Jeśli ma wartość false (domyślnie), przerywa bieżącą mowę i czyści kolejkę mowy przed wypowiedzeniem nowej wypowiedzi.

• extensionId

  ciąg znaków opcjonalny

  Identyfikator rozszerzenia silnika mowy, który ma być używany, jeśli jest znany.

• płeć

  VoiceGender opcjonalny

  Wycofane od Chrome 77

  Płeć została wycofana i będzie ignorowana.

  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 optional

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

• szybkość reakcji

  number optional

  Tempo mówienia względem domyślnego tempa dla tego głosu. Domyślna szybkość to 1,0, czyli zwykle około 180–220 słów na minutę. 2,0 oznacza 2 razy szybciej, a 0,5 – 2 razy wolniej. Wartości poniżej 0,1 lub powyżej 10,0 są niedozwolone, ale wiele głosów 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[] opcjonalne

  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 pole jest puste, używany jest dowolny dostępny głos.

• głośność

  number optional

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

• onEvent

  void optional

  Ta funkcja jest wywoływana ze zdarzeniami, które występują podczas wypowiadania tekstu.

  Funkcja onEvent wygląda tak:

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

  • zdarzenie

    TtsEvent

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

TtsVoice

Opis głosu dostępnego do 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 od wersji Chrome 70

  Płeć została wycofana i będzie ignorowana.

  Płeć 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

  boolean opcjonalne

  Jeśli ma wartość Prawda, silnik syntezy jest zasobem sieci zdalnej. Może to spowodować większe opóźnienia i koszty przepustowości.

• voiceName

  ciąg znaków opcjonalny

  Nazwa głosu.

VoiceGender

Chrome 54 lub nowsza wersja Wycofane od wersji Chrome 70

Płeć została wycofana i jest ignorowana.

Typ wyliczeniowy

"male"

"female"

Metody

getVoices()

Obietnica

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

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

Parametry

• callback

  function opcjonalne

  Parametr callback wygląda tak:

  (voices: TtsVoice[]) => void

  • Głosy

    TtsVoice[]

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

Zwroty

• Promise<TtsVoice[]>

  Chrome 101 lub nowsza wersja

  Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy 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 mówi, nawet jeśli mowa nie została zainicjowana przez Chrome.

Parametry

• callback

  function opcjonalne

  Parametr callback wygląda tak:

  (speaking: boolean) => void

  • mówienie,

    wartość logiczna

    Wartość true, jeśli mówi, w przeciwnym razie wartość false.

Zwroty

• Promise<boolean>

  Chrome 101 lub nowsza wersja

  Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

pause()

chrome.tts.pause(): void

Wstrzymuje syntezę mowy, potencjalnie w trakcie wypowiedzi. Wywołanie funkcji wznowienia lub zatrzymania spowoduje wyłączenie wstrzymania mowy.

resume()

chrome.tts.resume(): void

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

speak()

Obietnica

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

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

Parametry

• wypowiedź

  tekst

  Tekst do odczytania, zwykły tekst lub kompletny, prawidłowo sformatowany dokument 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

  function opcjonalne

  Parametr callback wygląda tak:

  () => void

Zwroty

• thought Promise<void>

  Chrome 101 lub nowsza wersja

  Rozpoznawanie następuje natychmiast, zanim mowa się zakończy. Jeśli wystąpi błąd, obietnica zostanie odrzucona. Aby uzyskać bardziej szczegółowe informacje, użyj options.onEvent.

  Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

stop()

chrome.tts.stop(): void

Zatrzymuje bieżącą mowę i czyści kolejkę oczekujących wypowiedzi. Dodatkowo, jeśli mowa została wstrzymana, zostanie wznowiona przy następnym wywołaniu funkcji mowy.

Wydarzenia

onVoicesChanged

Chrome 124 lub nowsza wersja

chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

Wywoływana, gdy lista tts.TtsVoice, która zostałaby zwrócona przez getVoices, uległa zmianie.

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  () => void