SpeechSynthesisErrorEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface SpeechSynthesisErrorEvent extends SpeechSynthesisEvent

Beschreibung

SpeechSynthesisErrorEvent ist das Ereignisobjekt, das der Browser an eine SpeechSynthesisUtterance sendet, wenn deren Sprachausgabe nicht gestartet oder nicht zu Ende geführt werden kann. Du erhältst es im error-Ereignis, also über utterance.addEventListener("error", handler) oder die Eigenschaft utterance.onerror.

Die Schnittstelle erbt von SpeechSynthesisEvent und stellt damit auch utterance, charIndex, charLength, elapsedTime und name bereit. Dazu kommt die schreibgeschützte Eigenschaft error. Sie enthält einen der folgenden Fehlercodes als Zeichenkette:

"canceled": Die Äußerung wurde aus der Warteschlange entfernt, bevor sie begonnen hat, z. B. durch speechSynthesis.cancel().
"interrupted": Eine laufende Ausgabe wurde abgebrochen, z. B. durch cancel().
"audio-busy": Das Audioausgabegerät ist gerade belegt.
"audio-hardware": Es wurde kein Audioausgabegerät gefunden.
"network": Ein Netzwerkfehler ist aufgetreten (bei serverbasierten Stimmen).
"synthesis-unavailable": Es steht keine Sprachsynthese-Engine zur Verfügung.
"synthesis-failed": Die Engine meldet einen Fehler bei der Synthese.
"language-unavailable": Für die gewünschte Sprache (lang) gibt es keine passende Stimme.
"voice-unavailable": Die gewählte Stimme (voice) ist nicht verfügbar.
"text-too-long": Der Text ist für den Sprachdienst zu lang.
"invalid-argument": rate, pitch oder volume haben ungültige Werte.
"not-allowed": Der Start wurde nicht erlaubt, z. B. weil keine Nutzerinteraktion vorausging.

In der Praxis nutzt du das Ereignis, um Nutzern verständliche Rückmeldungen zu geben, auf eine andere Stimme oder Sprache auszuweichen oder zu lange Texte in kleinere Stücke aufzuteilen. Den Konstruktor brauchst du nur selten, etwa für Tests oder um Fehler selbst auszulösen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, in der Regel `"error"` (nur beim Konstruktor `new SpeechSynthesisErrorEvent()`).
$options Pflicht	object		Initialisierungsobjekt. Pflichtfelder: `utterance` (`SpeechSynthesisUtterance`) und `error` (einer der Fehlercodes). Optional: `charIndex`, `charLength`, `elapsedTime`, `name` sowie `bubbles`, `cancelable`, `composed`.

Beispiele

Fehler über die onerror-Eigenschaft abfangen

const utterance = new SpeechSynthesisUtterance('Willkommen auf programmierung.net!');
utterance.lang = 'de-DE';

utterance.onerror = (event) => {
  // event ist ein SpeechSynthesisErrorEvent
  console.error(`Sprachausgabe fehlgeschlagen: ${event.error}`);
  console.log(`Abgebrochen bei Zeichen ${event.charIndex} nach ${event.elapsedTime} ms`);
};

document.querySelector('#vorlesen').addEventListener('click', () => {
  speechSynthesis.speak(utterance);
});

Sprachausgabe fehlgeschlagen: not-allowed Abgebrochen bei Zeichen 0 nach 0 ms

Fehlercodes auswerten und auf eine andere Stimme ausweichen

const speak = (text, voice) => {
  const utterance = new SpeechSynthesisUtterance(text);
  if (voice) utterance.voice = voice;

  const onError = (event) => {
    switch (event.error) {
      case 'canceled':
      case 'interrupted':
        // vom Nutzer oder Code abgebrochen, das ist kein echter Fehler
        break;
      case 'voice-unavailable':
      case 'language-unavailable': {
        const fallback = speechSynthesis.getVoices().find((v) => v.lang.startsWith('de'));
        if (fallback && fallback !== voice) speak(text, fallback);
        break;
      }
      case 'text-too-long':
        // Text satzweise aufteilen
        text.split(/(?<=[.!?])\s+/).forEach((satz) => speak(satz, voice));
        break;
      default:
        console.warn('Sprachausgabe nicht möglich:', event.error);
    }
    utterance.removeEventListener('error', onError);
  };

  utterance.addEventListener('error', onError);
  speechSynthesis.speak(utterance);
};

speak('Das ist ein Test der Sprachausgabe.');

Ereignis im Test selbst erzeugen und auslösen

const utterance = new SpeechSynthesisUtterance('Test');

utterance.addEventListener('error', (e) => {
  console.log(e instanceof SpeechSynthesisErrorEvent, e.error, e.utterance === utterance);
});

const fakeError = new SpeechSynthesisErrorEvent('error', {
  utterance,
  error: 'network',
  charIndex: 0,
  elapsedTime: 0
});

utterance.dispatchEvent(fakeError);

true network true

Promise-Wrapper mit Fehlerbehandlung

const say = (text) => new Promise((resolve, reject) => {
  const u = new SpeechSynthesisUtterance(text);
  u.onend = resolve;
  u.onerror = (e) => reject(new Error(`Speech: ${e.error}`));
  speechSynthesis.speak(u);
});

try {
  await say('Hallo Welt');
  console.log('Fertig gesprochen');
} catch (err) {
  console.error(err.message);
}

Fertig gesprochen

Siehe auch

SpeechSynthesisEvent SpeechSynthesisVoice SpeechSynthesisUtterance SpeechRecognitionErrorEvent SpeechSynthesis