new SpeechRecognitionEvent() — Methode · JavaScript-Referenz

Signatur

new SpeechRecognitionEvent(type, options)

Beschreibung

Der Konstruktor SpeechRecognitionEvent() legt ein Ereignisobjekt der Web Speech API an. Im Normalfall erzeugt der Browser diese Objekte selbst: Er übergibt sie an die Handler für result und nomatch einer SpeechRecognition-Instanz, sobald die Spracherkennung (vorläufige oder endgültige) Ergebnisse liefert.

Selbst aufrufen muss man den Konstruktor nur in wenigen Fällen:

Man will erkannte Ergebnisse an ein eigenes EventTarget weiterleiten, etwa an eine eigene Komponente oder einen Event-Bus.
Man will ein bereits erhaltenes Ereignis erneut auslösen (ein Event-Objekt lässt sich nicht zweimal dispatchen).
Man will Ereignisse für Tests nachbauen.

Die Eigenschaft results muss eine echte SpeechRecognitionResultList sein. Diese Schnittstelle hat keinen öffentlichen Konstruktor. Deshalb bekommt man sie praktisch nur aus einem vorhandenen, vom Browser erzeugten Ereignis.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"result"` oder `"nomatch"`. Groß- und Kleinschreibung zählt.
$options Pflicht	SpeechRecognitionEventInit		Objekt zur Initialisierung. Es erbt alle Felder von `EventInit` (`bubbles`, `cancelable`, `composed`).
$options.results Pflicht	SpeechRecognitionResultList		Liste der Erkennungsergebnisse. Laut Spezifikation ein Pflichtfeld. Sie muss eine echte `SpeechRecognitionResultList` sein, ein normales Array reicht nicht.
$options.resultIndex	number	0	Index des ersten Ergebnisses in `results`, das sich seit dem letzten Ereignis geändert hat.

Rückgabewert

Typ

SpeechRecognitionEvent

Beschreibung

Ein neues, noch nicht ausgelöstes Ereignisobjekt mit den Eigenschaften results und resultIndex. Auslösen lässt es sich mit dispatchEvent().

Beispiele

Konstruktor mit Präfix-Fallback ermitteln

// Chrome und Edge kennen den Konstruktor nur mit webkit-Präfix
const RecognitionEvent =
  window.SpeechRecognitionEvent ?? window.webkitSpeechRecognitionEvent;

if (!RecognitionEvent) {
  console.log('SpeechRecognitionEvent wird nicht unterstützt');
} else {
  console.log('Konstruktor verfügbar:', RecognitionEvent.name);
}

Konstruktor verfügbar: webkitSpeechRecognitionEvent (in Chrome)

Erkannte Ergebnisse an einen eigenen Event-Bus weiterleiten

const Recognition = window.SpeechRecognition ?? window.webkitSpeechRecognition;
const RecognitionEvent =
  window.SpeechRecognitionEvent ?? window.webkitSpeechRecognitionEvent;

const bus = new EventTarget();
bus.addEventListener('transkript', (e) => {
  const text = e.results[e.resultIndex][0].transcript;
  console.log('Bus empfängt:', text);
});

const recognition = new Recognition();
recognition.lang = 'de-DE';

recognition.addEventListener('result', (event) => {
  // Ein neues Event-Objekt anlegen, denn das Original ist bereits ausgelöst
  const weiter = new RecognitionEvent('transkript', {
    results: event.results,
    resultIndex: event.resultIndex,
  });
  bus.dispatchEvent(weiter);
});

recognition.start(); // fragt die Mikrofon-Berechtigung ab

Bus empfängt: hallo welt

Ereignis für Unit-Tests nachbauen (ohne echte ResultList)

// Eine SpeechRecognitionResultList lässt sich nicht selbst erzeugen.
// Für Tests daher ein normales Event mit nachgebildeten Eigenschaften verwenden:
const fakeResultEvent = (transcript, confidence = 0.9) => {
  const event = new Event('result');
  const alternative = { transcript, confidence };
  const result = Object.assign([alternative], { isFinal: true });
  const results = [result];
  results.item = (i) => results[i];
  Object.defineProperties(event, {
    results: { value: results },
    resultIndex: { value: 0 },
  });
  return event;
};

const handleResult = (e) => e.results[e.resultIndex][0].transcript;
console.log(handleResult(fakeResultEvent('Licht an')));

Licht an

// Wichtig · Fallstricke

Browser-Unterstützung: Chrome und Edge kennen den Konstruktor nur als webkitSpeechRecognitionEvent. Safari unterstützt ihn ab Version 14.1. Firefox unterstützt die Spracherkennung standardmäßig nicht. Vor der Nutzung also immer prüfen, ob der Konstruktor existiert.
results ist nicht frei erzeugbar: SpeechRecognitionResultList und SpeechRecognitionResult haben keine öffentlichen Konstruktoren. Übergibt man ein normales Array, wirft der Konstruktor einen TypeError. Für Tests daher Attrappen auf Basis von Event verwenden.
Selbst ausgelöste Ereignisse haben isTrusted === false. Die Spracherkennung selbst reagiert nicht darauf: Ein eigenes Ereignis startet oder beendet also keine Erkennung.
Die früheren Eigenschaften interpretation und emma wurden aus der Spezifikation entfernt. Man sollte sich nicht mehr darauf verlassen.
In Chrome läuft die Spracherkennung über einen Server von Google. Die Audiodaten verlassen also das Gerät, was für den Datenschutz relevant ist. Außerdem braucht die Erkennung einen sicheren Kontext (HTTPS) und die Mikrofon-Berechtigung.

Siehe auch

new FontFaceSetLoadEvent() new SpeechRecognition() new SpeechRecognitionErrorEvent() new SpeechRecognitionPhrase() new CompositionEvent()