SpeechRecognitionErrorEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface SpeechRecognitionErrorEvent extends Event

Beschreibung

SpeechRecognitionErrorEvent ist das Ereignisobjekt, das an Handler des error-Events einer SpeechRecognition-Instanz übergeben wird. Es erbt von Event und hat zwei zusätzliche, schreibgeschützte Eigenschaften: error ist ein festgelegter Fehlercode, message ist eine optionale, vom Browser formulierte Beschreibung.

Die möglichen Werte von error sind:

"no-speech": Es wurde keine Sprache erkannt.
"aborted": Die Eingabe wurde abgebrochen, etwa durch abort().
"audio-capture": Die Audioaufnahme ist fehlgeschlagen, meist weil kein Mikrofon vorhanden ist.
"network": Die Netzwerkkommunikation mit dem Erkennungsdienst ist fehlgeschlagen.
"not-allowed": Der Nutzer oder der Browser hat den Zugriff auf das Mikrofon verweigert.
"service-not-allowed": Der Browser erlaubt den angeforderten Erkennungsdienst nicht.
"language-not-supported": Die in lang gesetzte Sprache wird nicht unterstützt.
"bad-grammar": Fehler in der Grammatik. Dieser Wert ist veraltet.

Das Interface braucht man immer dann, wenn man Spracheingabe robust machen will. So kann man Nutzern verständliche Hinweise anzeigen, z. B. „Mikrofonzugriff erlauben“, bei no-speech automatisch neu starten oder bei network auf Texteingabe umschalten. Selbst erzeugt man solche Objekte mit dem Konstruktor meist nur in Tests.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Konstruktor-Parameter: Name des Events, in der Praxis `"error"`.
$options Pflicht	{ error: string, message?: string, bubbles?: boolean, cancelable?: boolean, composed?: boolean }		Konstruktor-Parameter: `error` ist Pflicht und enthält einen der Fehlercodes. `message` ist optional und standardmäßig `""`. Dazu kommen die üblichen `EventInit`-Optionen.

Rückgabewert

Typ

SpeechRecognitionErrorEvent

Beschreibung

Das Ereignisobjekt mit den Eigenschaften error (Fehlercode als string) und message (string, oft leer).

Beispiele

Fehler per addEventListener auswerten

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

recognition.addEventListener('error', (event) => {
  // event ist ein SpeechRecognitionErrorEvent
  console.log(`Fehler: ${event.error}`, event.message);
});

recognition.start();

Fehler: not-allowed (wenn der Mikrofonzugriff verweigert wurde)

Verständliche Meldungen für Nutzer über onerror

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

const meldungen = {
  'no-speech': 'Es wurde nichts gesagt. Bitte erneut versuchen.',
  'audio-capture': 'Kein Mikrofon gefunden.',
  'not-allowed': 'Bitte erlauben Sie den Mikrofonzugriff.',
  'service-not-allowed': 'Spracherkennung ist in diesem Browser nicht erlaubt.',
  'network': 'Netzwerkfehler – bitte Verbindung prüfen.',
  'language-not-supported': 'Die gewählte Sprache wird nicht unterstützt.',
  'aborted': 'Die Erkennung wurde abgebrochen.'
};

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

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

Automatischer Neustart bei „no-speech“

const Recognition = window.SpeechRecognition ?? window.webkitSpeechRecognition;
const recognition = new Recognition();
let neustart = false;

recognition.onerror = (event) => {
  neustart = event.error === 'no-speech';
};

// start() erst im end-Event erneut aufrufen, sonst InvalidStateError
recognition.onend = () => {
  if (neustart) {
    neustart = false;
    recognition.start();
  }
};

recognition.start();

Event im Test selbst erzeugen

const event = new SpeechRecognitionErrorEvent('error', {
  error: 'network',
  message: 'Simulierter Ausfall'
});

console.log(event instanceof Event, event.error, event.message);

true network Simulierter Ausfall

// Wichtig · Fallstricke

Browser-Kompatibilität: Chrome und Edge bieten die API nur mit Präfix an (webkitSpeechRecognition, webkitSpeechRecognitionErrorEvent). Safari unterstützt sie ab 14.1, Firefox nicht. Deshalb vor der Nutzung immer prüfen, ob die API vorhanden ist. Auch der globale Konstruktor SpeechRecognitionErrorEvent ist ohne Präfix nicht überall verfügbar.
Sichere Umgebung: Der Mikrofonzugriff funktioniert nur über HTTPS bzw. localhost. Sonst erhält man "not-allowed". In iframes ist zusätzlich allow="microphone" nötig.
Datenschutz/Netzwerk: In Chrome wird das Audio zur Erkennung an Server von Google geschickt. Offline oder hinter restriktiven Firewalls kommt daher "network".
Nach einem error folgt immer ein end-Event. Ruft man start() direkt im Fehler-Handler auf, kann ein InvalidStateError auftreten. Deshalb besser im end-Handler neu starten.
message ist in vielen Browsern leer und nicht standardisiert formuliert. Für die Programmlogik nur error verwenden.
Bei "not-allowed" nicht in einer Schleife neu starten. Das nervt Nutzer und bringt nichts, solange die Berechtigung fehlt.

Siehe auch

Event SpeechRecognitionEvent SpeechRecognitionResult SpeechRecognitionPhrase SpeechRecognitionAlternative