SpeechRecognition: error — Ereignis · JavaScript-Referenz

Signatur

recognition.addEventListener("error", handler)

Beschreibung

Das error-Ereignis gehört zur Web Speech API und wird an einer SpeechRecognition-Instanz ausgelöst, sobald die Erkennung nicht erfolgreich weiterlaufen kann. Der Handler bekommt ein SpeechRecognitionErrorEvent. Dessen Eigenschaft error enthält einen Fehlercode als Zeichenkette, message liefert optional eine genauere Beschreibung.

Registrieren kannst du den Handler mit recognition.addEventListener("error", handler) oder über die Eigenschaft recognition.onerror = handler. Mögliche Werte von event.error sind:

no-speech: Es wurde keine Sprache erkannt.
aborted: Die Erkennung wurde abgebrochen, etwa durch abort().
audio-capture: Die Audioaufnahme ist fehlgeschlagen, z. B. weil kein Mikrofon da ist.
network: Die Netzwerkkommunikation zum Erkennungsdienst ist fehlgeschlagen.
not-allowed: Der Nutzer oder der Browser hat den Mikrofonzugriff verweigert.
service-not-allowed: Der angeforderte Erkennungsdienst ist nicht erlaubt.
language-not-supported: Die in lang gesetzte Sprache wird nicht unterstützt.
bad-grammar: Die Grammatik ist fehlerhaft oder wird nicht unterstützt.

Mit dem Ereignis kannst du Nutzern verständliche Rückmeldungen geben, zum Beispiel „Bitte Mikrofon freigeben“. Außerdem lassen sich damit vorübergehende Fehler wie no-speech oder network gezielt wiederholen. Nach einem Fehler folgt in der Regel das end-Ereignis.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"error"`.
$handler Pflicht	(event: SpeechRecognitionErrorEvent) => void		Callback, der ein `SpeechRecognitionErrorEvent` mit den Eigenschaften `error` (Fehlercode) und `message` (Beschreibung) erhält.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Ereignisobjekt ist ein SpeechRecognitionErrorEvent.

Beispiele

Fehler mit addEventListener auswerten

const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition;
const recognition = new SpeechRecognition();
recognition.lang = 'de-DE';

recognition.addEventListener('error', (event) => {
  console.error(`Spracherkennungsfehler: ${event.error}`, event.message);
});

recognition.start();

Spracherkennungsfehler: no-speech

Verständliche Fehlermeldungen über onerror

const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition;
const recognition = new SpeechRecognition();
const status = document.querySelector('#status');

const meldungen = {
  'no-speech': 'Es wurde nichts gesagt. Bitte erneut versuchen.',
  'audio-capture': 'Kein Mikrofon gefunden.',
  'not-allowed': 'Bitte erlaube den Mikrofonzugriff.',
  'network': 'Netzwerkfehler – bitte Verbindung prüfen.',
  'language-not-supported': 'Diese Sprache wird nicht unterstützt.'
};

recognition.onerror = (event) => {
  status.textContent = meldungen[event.error] ?? `Unbekannter Fehler: ${event.error}`;
};

document.querySelector('#mic').addEventListener('click', () => recognition.start());

Automatischer Neustart bei vorübergehenden Fehlern und Entfernen des Listeners

const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition;
const recognition = new SpeechRecognition();
let versuche = 0;
let neuStarten = false;

const onError = (event) => {
  neuStarten = ['no-speech', 'network'].includes(event.error) && versuche < 3;
  if (!neuStarten) {
    console.warn('Abbruch:', event.error);
    recognition.removeEventListener('error', onError);
  }
};

recognition.addEventListener('error', onError);
recognition.addEventListener('end', () => {
  if (neuStarten) {
    versuche++;
    neuStarten = false;
    recognition.start(); // erst nach 'end' neu starten
  }
});

recognition.start();

Abbruch: not-allowed

// Wichtig · Fallstricke

Browser-Unterstützung: In Chrome und Edge heißt der Konstruktor webkitSpeechRecognition (mit Präfix), in Safari gibt es Unterstützung ab 14.1. Firefox unterstützt die Erkennung standardmäßig nicht. Prüfe deshalb vorher mit 'SpeechRecognition' in window || 'webkitSpeechRecognition' in window, ob die API verfügbar ist.
Kein Neustart im Fehler-Handler: Wenn du start() direkt in onerror aufrufst, kann eine InvalidStateError-Ausnahme auftreten, weil die Sitzung noch läuft. Starte die Erkennung erst im end-Ereignis neu.
not-allowed: Dieser Fehler tritt auch auf, wenn die Seite nicht in einem sicheren Kontext (HTTPS) läuft oder eine Berechtigungsrichtlinie das Mikrofon sperrt. Wiederholte Versuche helfen hier nicht. Beende die Schleife und informiere den Nutzer.
network: In Chrome wird das Audio an einen Server geschickt. Offline oder hinter restriktiven Firewalls kommt es deshalb häufig zu diesem Fehler. Das ist auch für den Datenschutz relevant.
Endlose Neustart-Schleifen solltest du mit einem Zähler oder einem Backoff begrenzen.

Siehe auch

SpeechRecognition SpeechRecognitionErrorEvent SpeechRecognition.prototype.start() GPUDevice: uncapturederror SpeechRecognition: end