SpeechSynthesisErrorEvent.error — Eigenschaft · JavaScript-Referenz

Signatur

SpeechSynthesisErrorEvent.error

Beschreibung

Die schreibgeschützte Eigenschaft error der Schnittstelle SpeechSynthesisErrorEvent enthält einen Fehlercode als String. Er beschreibt, warum eine SpeechSynthesisUtterance nicht oder nicht vollständig gesprochen wurde. Das Ereignis wird als error-Event auf der betroffenen Utterance ausgelöst. Man kann es mit utterance.addEventListener("error", …) oder über utterance.onerror abfangen.

Mögliche Werte laut Web-Speech-API-Spezifikation:

"canceled": Die Utterance wurde durch speechSynthesis.cancel() aus der Warteschlange entfernt, bevor sie gesprochen wurde.
"interrupted": Die laufende Ausgabe wurde durch speechSynthesis.cancel() unterbrochen.
"audio-busy": Das Audio-Ausgabegerät ist gerade nicht verfügbar.
"audio-hardware": Es wurde kein Audio-Ausgabegerät gefunden.
"network": Ein Netzwerkfehler ist aufgetreten, z. B. bei einer serverseitigen Stimme.
"synthesis-unavailable": Es steht keine Synthese-Engine zur Verfügung.
"synthesis-failed": Die Synthese-Engine hat einen Fehler gemeldet.
"language-unavailable": Für die angegebene Sprache (lang) gibt es keine passende Stimme.
"voice-unavailable": Die gewählte Stimme (voice) ist nicht verfügbar.
"text-too-long": Der Text ist zu lang für die Synthese.
"invalid-argument": Ein Wert für rate, pitch oder volume ist ungültig.
"not-allowed": Die Ausgabe ist nicht erlaubt, zum Beispiel weil noch keine Nutzerinteraktion stattgefunden hat (Autoplay-Richtlinie).

Die Eigenschaft ist nützlich, um echte Fehler von gewollten Abbrüchen zu unterscheiden. Hat der Nutzer die Ausgabe selbst abgebrochen, sollte die Anwendung keine Fehlermeldung zeigen. Bei "not-allowed" oder "voice-unavailable" ist dagegen eine Rückmeldung oder ein Ausweichverhalten sinnvoll.

Rückgabewert

Typ

string

Beschreibung

Einer der Fehlercodes "canceled", "interrupted", "audio-busy", "audio-hardware", "network", "synthesis-unavailable", "synthesis-failed", "language-unavailable", "voice-unavailable", "text-too-long", "invalid-argument" oder "not-allowed". Die Eigenschaft ist schreibgeschützt.

Beispiele

Fehlercode mit addEventListener auslesen

const utterance = new SpeechSynthesisUtterance('Hallo und willkommen!');
utterance.lang = 'de-DE';

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

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

Sprachausgabe fehlgeschlagen: not-allowed // nur wenn der Browser die Ausgabe blockiert

Gewollte Abbrüche von echten Fehlern unterscheiden (onerror)

const utterance = new SpeechSynthesisUtterance('Ein langer Artikeltext …');

utterance.onerror = (event) => {
  // Abbruch durch cancel() ist kein echter Fehler
  if (event.error === 'canceled' || event.error === 'interrupted') {
    console.log('Vorlesen wurde vom Nutzer gestoppt.');
    return;
  }
  console.error('Echter Fehler:', event.error);
};

speechSynthesis.speak(utterance);

// Nach einer Sekunde stoppen
setTimeout(() => speechSynthesis.cancel(), 1000);

Vorlesen wurde vom Nutzer gestoppt.

Benutzerfreundliche Meldungen je Fehlercode

const meldungen = {
  'not-allowed': 'Bitte klicke zuerst auf die Seite, um die Sprachausgabe zu erlauben.',
  'language-unavailable': 'Für diese Sprache ist keine Stimme installiert.',
  'voice-unavailable': 'Die gewählte Stimme ist nicht verfügbar.',
  'audio-hardware': 'Kein Audiogerät gefunden.',
  'network': 'Netzwerkfehler bei der Sprachausgabe.',
  'text-too-long': 'Der Text ist zu lang zum Vorlesen.'
};

const vorlesen = (text, lang = 'de-DE') => new Promise((resolve, reject) => {
  const u = new SpeechSynthesisUtterance(text);
  u.lang = lang;
  u.onend = resolve;
  u.onerror = (e) => reject(new Error(meldungen[e.error] ?? `Unbekannter Fehler: ${e.error}`));
  speechSynthesis.speak(u);
});

try {
  await vorlesen('Guten Tag!', 'xx-XX');
} catch (err) {
  console.warn(err.message);
}

Für diese Sprache ist keine Stimme installiert. // je nach Browser/Engine

// Wichtig · Fallstricke

Abbruch ist auch ein Fehler: Ein Aufruf von speechSynthesis.cancel() löst auf der laufenden bzw. wartenden Utterance ein error-Event mit "interrupted" bzw. "canceled" aus. Diese Fälle sollten vor der Fehlerbehandlung herausgefiltert werden.
Autoplay-Richtlinie: Chrome und Safari blockieren Sprachausgabe ohne vorherige Nutzerinteraktion und melden dann "not-allowed". speak() sollte deshalb in einem Klick-Handler aufgerufen werden.
Uneinheitliche Browser: Nicht jede Engine nutzt alle Codes. Firefox und Safari melden eine fehlende Sprache oft gar nicht und nehmen stillschweigend eine Standardstimme. In Chrome brechen lange Texte teils nach etwa 15 Sekunden ohne Event ab. Deshalb nie davon ausgehen, dass bei jedem Problem ein bestimmter Code kommt, und immer einen Rückfallwert vorsehen (z. B. mit ??).
Kompatibilität: SpeechSynthesisErrorEvent gibt es in allen aktuellen Desktop- und Mobilbrowsern. Ältere Browser liefern teils nur ein allgemeines Event ohne error-Eigenschaft. Vor der Nutzung sollte man mit 'speechSynthesis' in window prüfen, ob die API überhaupt vorhanden ist.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird stillschweigend ignoriert.

Siehe auch

SensorErrorEvent.error SpeechRecognitionErrorEvent.error SpeechSynthesisEvent.name SpeechSynthesisEvent.utterance GPUUncapturedErrorEvent.error