chrome.ttsEngine

refresh date: 2026-09-25 robots: noindex

Opis

Użyj interfejsu API chrome.ttsEngine, aby zaimplementować silnik zamiany tekstu na mowę(TTS) za pomocą rozszerzenia. Jeśli rozszerzenie zarejestruje się za pomocą tego interfejsu API, będzie otrzymywać zdarzenia zawierające wypowiedź do odczytania i inne parametry, gdy dowolne rozszerzenie lub aplikacja Chrome użyje interfejsu API tts do generowania mowy. Rozszerzenie może następnie użyć dowolnej dostępnej technologii internetowej do syntezy i wygenerowania mowy oraz wysłania zdarzeń z powrotem do funkcji wywołującej w celu zgłoszenia stanu.

Uprawnienia

ttsEngine

Przegląd

Rozszerzenie może zarejestrować się jako silnik mowy. Dzięki temu może przechwytywać niektóre lub wszystkie wywołania funkcji takich jak tts.speak i tts.stop oraz udostępniać alternatywną implementację. Rozszerzenia mogą korzystać z dowolnej dostępnej technologii internetowej do odtwarzania mowy, w tym ze strumieniowego przesyłania dźwięku z serwera i dźwięku HTML5. Rozszerzenie może nawet wykonywać inne czynności związane z wypowiedziami, np. wyświetlać napisy w wyskakującym okienku lub wysyłać je jako komunikaty logu na serwer zdalny.

Plik manifestu

Aby wdrożyć mechanizm TTS, rozszerzenie musi zadeklarować uprawnienie „ttsEngine”, a następnie wszystkie głosy, które udostępnia w pliku manifestu rozszerzenia, w ten sposób:

{
  "name": "My TTS Engine",
  "version": "1.0",
  "permissions": ["ttsEngine"],
  "tts_engine": {
    "voices": [
      {
        "voice_name": "Alice",
        "lang": "en-US",
        "event_types": ["start", "marker", "end"]
      },
      {
        "voice_name": "Pat",
        "lang": "en-US",
        "event_types": ["end"]
      }
    ]
  },
  "background": {
    "page": "background.html",
    "persistent": false
  }
}

Rozszerzenie może określać dowolną liczbę głosów.

Parametr voice_name jest wymagany. Nazwa powinna być na tyle opisowa, aby można było zidentyfikować nazwę głosu i używanego silnika. W bardzo rzadkich przypadkach, gdy 2 rozszerzenia zarejestrują głosy o tej samej nazwie, klient może określić identyfikator rozszerzenia, które powinno wykonać syntezę.

Parametr lang jest opcjonalny, ale zdecydowanie zalecany. Prawie zawsze głos może syntetyzować mowę tylko w jednym języku. Jeśli silnik obsługuje więcej niż 1 język, może łatwo zarejestrować osobny głos dla każdego języka. W rzadkich przypadkach, gdy jeden głos może obsługiwać więcej niż jeden język, najłatwiej jest po prostu wymienić 2 osobne głosy i obsługiwać je wewnętrznie przy użyciu tej samej logiki. Jeśli jednak chcesz utworzyć głos, który będzie obsługiwał wypowiedzi w dowolnym języku, pomiń parametr lang w pliku manifestu rozszerzenia.

Parametr event_types jest wymagany, jeśli silnik może wysyłać zdarzenia, aby informować klienta o postępach syntezy mowy. Zdecydowanie zalecamy obsługę co najmniej typu zdarzenia 'end', aby wskazać, kiedy mowa się kończy. W przeciwnym razie Chrome nie będzie mógł zaplanować wypowiedzi w kolejce.

Po wczytaniu rozszerzenie może zastąpić listę zadeklarowanych głosów, wywołując funkcję chrome.ttsEngine.updateVoices. (Pamiętaj, że parametry używane w wywołaniu automatycznym do updateVoices są zapisywane w formacie camelCase, np. voiceName, w odróżnieniu od pliku manifestu, w którym używany jest format voice_name).

Typy zdarzeń, które możesz wysyłać, odpowiadają typom zdarzeń, które odbiera metoda speak():

  • '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.
  • 'error': wystąpił błąd związany z silnikiem i nie można odczytać tej wypowiedzi. Przekaż więcej informacji w parametrze event.errorMessage.

Zdarzenia 'interrupted' i 'cancelled' nie są wysyłane przez mechanizm mowy, ale są generowane automatycznie przez Chrome.

Klienty zamiany tekstu na mowę mogą uzyskać informacje o głosie z pliku manifestu rozszerzenia, wywołując funkcję tts.getVoices, pod warunkiem że zarejestrowano detektory zdarzeń mowy w sposób opisany poniżej.

Obsługa zdarzeń mowy

Aby generować mowę na żądanie klientów, rozszerzenie musi zarejestrować detektory dla onSpeak i onStop, na przykład w ten sposób:

const speakListener = (utterance, options, sendTtsEvent) => {
  sendTtsEvent({type: 'start', charIndex: 0})

  // (start speaking)

  sendTtsEvent({type: 'end', charIndex: utterance.length})
};

const stopListener = () => {
  // (stop all speech)
};

chrome.ttsEngine.onSpeak.addListener(speakListener);
chrome.ttsEngine.onStop.addListener(stopListener);

Decyzja o tym, czy wysłać dane żądanie mowy do rozszerzenia, zależy wyłącznie od tego, czy rozszerzenie obsługuje dane parametry głosu w swoim pliku manifestu i czy ma zarejestrowane detektory dla onSpeak i onStop. Innymi słowy, rozszerzenie nie może otrzymać żądania mowy i dynamicznie zdecydować, czy je obsłużyć.

Typy

AudioBuffer

Chrome 92 lub nowsza wersja

Parametry zawierające bufor audio i powiązane dane.

Właściwości

  • audioBuffer

    ArrayBuffer

    Bufor audio z mechanizmu zamiany tekstu na mowę. Powinien mieć długość dokładnie audioStreamOptions.bufferSize i być zakodowany jako mono, przy audioStreamOptions.sampleRate, oraz jako liniowy pcm, 32-bitowy podpisany float, czyli typ Float32Array w javascript.

  • charIndex

    number optional

    Indeks znaków powiązany z tym buforem audio.

  • isLastBuffer

    boolean opcjonalne

    Prawda, jeśli ten bufor audio jest ostatnim dla wypowiadanego tekstu.

AudioStreamOptions

Chrome 92 lub nowsza wersja

Zawiera format strumienia audio, który powinien zostać wygenerowany przez silnik.

Właściwości

  • bufferSize

    liczba

    Liczba próbek w buforze audio.

  • sampleRate

    liczba

    Częstotliwość próbkowania oczekiwana w buforze audio.

LanguageInstallStatus

Chrome 132 lub nowsza wersja

Stan instalacji głosu.

Typ wyliczeniowy

"notInstalled"

"installing"

"installed"

"failed"

LanguageStatus

Chrome 132 lub nowsza wersja

Stan instalacji języka.

Właściwości

  • błąd

    ciąg znaków opcjonalny

    Szczegółowe informacje o błędach instalacji. Opcjonalnie wypełniane, jeśli nie udało się zainstalować języka.

  • installStatus

    LanguageInstallStatus

    Stan instalacji.

  • lang

    tekst

    Ciąg znaków języka w formie kod języka-kod regionu, przy czym region można pominąć. Przykłady: en, en-AU, zh-CH.

LanguageUninstallOptions

Chrome 132 lub nowsza wersja

Opcje odinstalowywania danego języka.

Właściwości

  • uninstallImmediately

    wartość logiczna

    Prawda, jeśli klient TTS chce natychmiast odinstalować język. Silnik może zdecydować, czy i kiedy odinstalować język, na podstawie tego parametru i informacji o żądającym. Jeśli ma wartość Fałsz, może używać innych kryteriów, takich jak ostatnie użycie, aby określić, kiedy odinstalować aplikację.

SpeakOptions

Chrome 92 lub nowsza wersja

Opcje określone dla metody tts.speak().

Właściwości

  • płeć

    VoiceGender opcjonalny

    Wycofane w Chrome 92

    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. Ta wartość musi zawierać się w przedziale od 0,1 do 10,0 (włącznie). Jeśli głos nie obsługuje pełnego zakresu szybkości, nie zwracaj błędu. Zamiast tego ogranicz tempo do zakresu obsługiwanego przez głos.

  • voiceName

    ciąg znaków opcjonalny

    Nazwa głosu używanego na potrzeby syntezy.

  • 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.

TtsClient

Chrome 131 lub nowsza wersja

Identyfikator klienta, który prosi o stan.

Właściwości

  • id

    tekst

    Klient wysyłający żądanie zarządzania językiem. W przypadku rozszerzenia jest to unikalny identyfikator rozszerzenia. W przypadku funkcji Chrome jest to zrozumiała dla człowieka nazwa funkcji.

  • źródło

    TtsClientSource

    Typ osoby zgłaszającej prośbę.

TtsClientSource

Chrome 131 lub nowsza wersja

Typ osoby zgłaszającej prośbę.

Typ wyliczeniowy

"chromefeature"

"extension"

VoiceGender

Chrome 54 lub nowsza wersja Wycofane od wersji Chrome 70

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

Typ wyliczeniowy

"male"

"female"

Metody

updateLanguage()

Chrome 132 lub nowsza wersja 
chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
): void

Wywoływane przez silnik, gdy następuje próba zainstalowania języka i gdy język jest odinstalowywany. Jest też wywoływana w odpowiedzi na żądanie stanu od klienta. Gdy głos jest instalowany lub odinstalowywany, silnik powinien też wywołać funkcję ttsEngine.updateVoices, aby zarejestrować głos.

Parametry

updateVoices()

Chrome 66 lub nowsza wersja 
chrome.ttsEngine.updateVoices(
  voices: TtsVoice[],
): void

Wywoływane przez silnik w celu zaktualizowania listy głosów. Ta lista zastępuje wszystkie głosy zadeklarowane w pliku manifestu tego rozszerzenia.

Parametry

  • Głosy

    TtsVoice[]

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

Wydarzenia

onInstallLanguageRequest

Chrome 131 lub nowsza wersja 
chrome.ttsEngine.onInstallLanguageRequest.addListener(
  callback: function,
)

Uruchamiane, gdy klient TTS prosi o zainstalowanie nowego języka. Silnik powinien spróbować pobrać i zainstalować język, a następnie wywołać funkcję ttsEngine.updateLanguage z wynikiem. W przypadku powodzenia silnik powinien też wywołać funkcję ttsEngine.updateVoices, aby zarejestrować nowo dostępne głosy.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (requestor: TtsClient, lang: string) => void

    • użytkownik zgłaszający prośbę

      TtsClient

    • lang

      tekst

onLanguageStatusRequest

Chrome 132 lub nowsza wersja 
chrome.ttsEngine.onLanguageStatusRequest.addListener(
  callback: function,
)

Uruchamiane, gdy klient TTS żąda stanu instalacji języka.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (requestor: TtsClient, lang: string) => void

    • użytkownik zgłaszający prośbę

      TtsClient

    • lang

      tekst

onPause

chrome.ttsEngine.onPause.addListener(
  callback: function,
)

Opcjonalnie: jeśli silnik obsługuje zdarzenie wstrzymania, powinien wstrzymać bieżącą wypowiedź, jeśli taka istnieje, dopóki nie otrzyma zdarzenia wznowienia lub zatrzymania. Pamiętaj, że zdarzenie zatrzymania powinno też wyczyścić stan wstrzymania.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onResume

chrome.ttsEngine.onResume.addListener(
  callback: function,
)

Opcjonalnie: jeśli silnik obsługuje zdarzenie wstrzymania, powinien też obsługiwać zdarzenie wznowienia, aby kontynuować odczytywanie bieżącej wypowiedzi (jeśli taka istnieje). Pamiętaj, że zdarzenie zatrzymania powinno też wyczyścić stan wstrzymania.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onSpeak

chrome.ttsEngine.onSpeak.addListener(
  callback: function,
)

Wywoływana, gdy użytkownik wywołuje funkcję tts.speak(), a jeden z głosów z manifestu tego rozszerzenia jest pierwszym, który pasuje do obiektu opcji.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (utterance: string, options: SpeakOptions, sendTtsEvent: function) => void

    • wypowiedź

      tekst

    • Opcje

      SpeakOptions

    • sendTtsEvent

      funkcja

      Parametr sendTtsEvent wygląda tak:

      (event: tts.TtsEvent) => void

      • zdarzenie

        tts.TtsEvent

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

onSpeakWithAudioStream

Chrome 92 lub nowsza wersja 
chrome.ttsEngine.onSpeakWithAudioStream.addListener(
  callback: function,
)

Wywoływana, gdy użytkownik wywołuje funkcję tts.speak(), a jeden z głosów z manifestu tego rozszerzenia jest pierwszym, który pasuje do obiektu opcji. Różni się od ttsEngine.onSpeak tym, że Chrome udostępnia usługi odtwarzania dźwięku i obsługuje wysyłanie zdarzeń TTS.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (utterance: string, options: SpeakOptions, audioStreamOptions: AudioStreamOptions, sendTtsAudio: function, sendError: function) => void

    • wypowiedź

      tekst

    • Opcje

      SpeakOptions

    • audioStreamOptions

      AudioStreamOptions

    • sendTtsAudio

      funkcja

      Parametr sendTtsAudio wygląda tak:

      (audioBufferParams: AudioBuffer) => void

      • audioBufferParams

        AudioBuffer

        Parametry zawierające bufor audio i powiązane dane.

    • sendError

      funkcja

      Chrome 94 lub nowsza wersja

      Parametr sendError wygląda tak:

      (errorMessage?: string) => void

      • Komunikat o błędzie

        ciąg znaków opcjonalny

        Ciąg tekstowy opisujący błąd.

onStop

chrome.ttsEngine.onStop.addListener(
  callback: function,
)

Uruchamiane, gdy wywoływana jest funkcja tts.stop, a rozszerzenie może być w trakcie odczytywania. Jeśli rozszerzenie otrzyma wywołanie onStop, a mowa została już zatrzymana, nie powinno nic robić (nie powinno zgłaszać błędu). Jeśli mowa jest w stanie wstrzymania, powinno to anulować ten stan.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onUninstallLanguageRequest

Chrome 132 lub nowsza wersja 
chrome.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

Uruchamiane, gdy klient TTS wskazuje, że język nie jest już potrzebny.

Parametry