SpeechSynthesisUtterance: error — Ereignis · JavaScript-Referenz

Signatur

utterance.addEventListener("error", handler) / utterance.onerror = handler

Beschreibung

Das error-Ereignis gehört zur Sprachausgabe der Web Speech API. Es wird an einer SpeechSynthesisUtterance ausgelöst, wenn die Äußerung nicht oder nicht vollständig gesprochen werden kann. Gründe sind zum Beispiel eine nicht verfügbare Stimme, eine fehlende Sprachsynthese-Engine, ein belegtes Audiogerät oder ein Abbruch durch speechSynthesis.cancel().

Der Handler erhält ein SpeechSynthesisErrorEvent. Dessen Eigenschaft error enthält einen Fehlercode als Zeichenkette, zum Beispiel "interrupted", "canceled", "synthesis-failed" oder "not-allowed". Zusätzlich stehen die von SpeechSynthesisEvent geerbten Eigenschaften utterance, charIndex, charLength, elapsedTime und name zur Verfügung. Damit lässt sich feststellen, an welcher Stelle im Text der Fehler aufgetreten ist.

Sie registrieren den Handler entweder mit addEventListener("error", …) oder über die Eigenschaft onerror. Nutzen Sie das Ereignis, um Nutzern eine Rückmeldung zu geben, auf eine andere Stimme umzuschalten oder ein Promise abzulehnen, das die Sprachausgabe kapselt. Nach einem error-Ereignis wird für dieselbe Äußerung in der Regel kein end-Ereignis mehr ausgelöst.

Parameter

Name	Typ	Beschreibung
$type Pflicht	string	Der Ereignisname `"error"` (nur bei `addEventListener`).
$handler Pflicht	(event: SpeechSynthesisErrorEvent) => void	Callback, der das `SpeechSynthesisErrorEvent` erhält. Wichtigste Eigenschaft ist `event.error` mit dem Fehlercode.
$event.error	string	Fehlercode: `"canceled"`, `"interrupted"`, `"audio-busy"`, `"audio-hardware"`, `"network"`, `"synthesis-unavailable"`, `"synthesis-failed"`, `"language-unavailable"`, `"voice-unavailable"`, `"text-too-long"`, `"invalid-argument"` oder `"not-allowed"`.
$event.charIndex	number	Position im Text, an der gerade gesprochen wurde, als der Fehler auftrat.
$event.elapsedTime	number	Zeit in Millisekunden seit Beginn der Äußerung (in älteren Implementierungen in Sekunden).
$event.utterance	SpeechSynthesisUtterance	Die betroffene Äußerung.

Rückgabewert

Typ

void

Beschreibung

Event-Handler geben nichts zurück. addEventListener liefert undefined.

Beispiele

Fehler per addEventListener protokollieren

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

utterance.addEventListener('error', (event) => {
  console.error(`Sprachausgabe fehlgeschlagen: ${event.error} (bei Zeichen ${event.charIndex})`);
});

speechSynthesis.speak(utterance);
// Abbruch provoziert den Fehler
setTimeout(() => speechSynthesis.cancel(), 300);

Sprachausgabe fehlgeschlagen: interrupted (bei Zeichen 0)

onerror-Eigenschaft mit Rückmeldung an den Nutzer

const button = document.querySelector('#vorlesen');
const status = document.querySelector('#status');

button.addEventListener('click', () => {
  const utterance = new SpeechSynthesisUtterance(document.querySelector('article').textContent);

  utterance.onerror = (event) => {
    // Absichtliche Abbrüche nicht als Fehler anzeigen
    if (event.error === 'interrupted' || event.error === 'canceled') return;
    status.textContent = `Vorlesen nicht möglich (${event.error}).`;
  };
  utterance.onend = () => { status.textContent = 'Fertig.'; };

  speechSynthesis.speak(utterance);
});

Sprachausgabe als Promise kapseln und Listener entfernen

const speak = (text, lang = 'de-DE') => new Promise((resolve, reject) => {
  const utterance = new SpeechSynthesisUtterance(text);
  utterance.lang = lang;

  const cleanup = () => {
    utterance.removeEventListener('end', onEnd);
    utterance.removeEventListener('error', onError);
  };
  const onEnd = () => { cleanup(); resolve(); };
  const onError = (event) => {
    cleanup();
    reject(new Error(`Speech error: ${event.error}`));
  };

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

try {
  await speak('Hallo Welt');
  console.log('Erfolgreich gesprochen');
} catch (err) {
  console.warn(err.message);
}

Erfolgreich gesprochen

// Wichtig · Fallstricke

Abbruch ist auch ein Fehler: speechSynthesis.cancel() oder ein neues speak() mit Unterbrechung lösen in vielen Browsern error mit "interrupted" oder "canceled" aus. Filtern Sie diese Codes heraus, wenn Sie nur echte Fehler melden möchten.
Nutzeraktion erforderlich: Chrome blockiert die Sprachausgabe ohne vorherige Nutzerinteraktion (Autoplay-Regeln). In diesem Fall kommt "not-allowed". Starten Sie speak() deshalb in einem Klick-Handler.
Unterschiedliches Verhalten der Browser: Welche Fehlercodes tatsächlich vorkommen, hängt von Browser und Betriebssystem ab. Manche Engines lösen bei einem Abbruch nur end aus. Werten Sie deshalb immer beide Ereignisse aus.
Stimmen: "voice-unavailable" oder "language-unavailable" können auftreten, wenn utterance.voice gesetzt wurde, bevor speechSynthesis.getVoices() geladen war (siehe voiceschanged).
Die Eigenschaft onerror nimmt nur einen einzigen Handler auf. Wenn Sie mehrere Listener brauchen, verwenden Sie addEventListener.

Siehe auch

SpeechSynthesisUtterance: end SpeechSynthesisUtterance: mark SpeechSynthesisUtterance: pause SpeechSynthesisUtterance: resume SpeechSynthesisUtterance: start