SpeechGrammarList — Schnittstelle · JavaScript-Referenz

Signatur

interface SpeechGrammarList

Beschreibung

SpeechGrammarList gehört zur Web Speech API und bündelt eine oder mehrere Grammatiken (SpeechGrammar). Eine Grammatik beschreibt, welche Wörter oder Satzmuster der Spracherkennungsdienst erwarten soll, zum Beispiel eine feste Liste von Farben, Befehlen oder Menüpunkten. Die Grammatiken werden üblicherweise im Format JSGF (JSpeech Grammar Format) formuliert.

Eine Liste legt man mit new SpeechGrammarList() an (in Chromium-Browsern: new webkitSpeechGrammarList()). Danach fügt man Grammatiken hinzu, entweder mit addFromString() als Zeichenkette oder mit addFromURI() aus einer externen Datei. Zum Schluss weist man die Liste der Eigenschaft SpeechRecognition.grammars zu.

Das Interface stellt folgende Mitglieder bereit:

length: Anzahl der enthaltenen Grammatiken (nur lesbar).
item(index): gibt die SpeechGrammar an der Position index zurück. Alternativ geht auch der Zugriff per Index wie bei einem Array: list[0].
addFromString(string, weight): fügt eine Grammatik hinzu, die als Zeichenkette vorliegt.
addFromURI(src, weight): fügt eine Grammatik hinzu, die unter einer URL liegt.

Grammatiken eignen sich vor allem für Sprachsteuerung mit einem kleinen, festen Wortschatz. In der Praxis ignorieren die meisten Erkennungsdienste (vor allem die Cloud-Erkennung in Chrome) die Grammatik weitgehend. Sie ist also eher ein Hinweis an den Dienst als eine feste Einschränkung. Die Ergebnisse sollte man deshalb immer selbst prüfen.

Parameter

Name	Typ	Default	Beschreibung
$string Pflicht	string		Nur bei `addFromString()`: der Grammatik-Text, meist im JSGF-Format, z. B. `#JSGF V1.0; grammar farben; public <farbe> = rot \| grün \| blau;`
$src Pflicht	string		Nur bei `addFromURI()`: URL einer Grammatik-Datei (z. B. `.jsgf` oder `.grxml`).
$weight	number	1.0	Gewichtung der Grammatik im Vergleich zu anderen Grammatiken der Liste, Wertebereich `0.0` bis `1.0`.
$index Pflicht	number		Nur bei `item()`: nullbasierter Index der gewünschten Grammatik.

Rückgabewert

Typ

SpeechGrammarList

Beschreibung

Der Konstruktor new SpeechGrammarList() gibt eine leere Liste zurück. item() gibt eine SpeechGrammar zurück, addFromString() und addFromURI() geben undefined zurück.

Beispiele

Liste anlegen und Grammatik aus einem String hinzufügen

// Präfix-Variante für Chrome/Edge berücksichtigen
const GrammarList = window.SpeechGrammarList ?? window.webkitSpeechGrammarList;

if (!GrammarList) {
  console.warn('SpeechGrammarList wird nicht unterstützt');
} else {
  const farben = ['rot', 'grün', 'blau', 'gelb', 'schwarz'];
  const jsgf = `#JSGF V1.0; grammar farben; public <farbe> = ${farben.join(' | ')};`;

  const grammars = new GrammarList();
  grammars.addFromString(jsgf, 1);

  console.log(grammars.length);
  console.log(grammars.item(0).weight);
}

1 1

Grammatik an SpeechRecognition übergeben (Sprachsteuerung)

const Recognition = window.SpeechRecognition ?? window.webkitSpeechRecognition;
const GrammarList = window.SpeechGrammarList ?? window.webkitSpeechGrammarList;

const befehle = ['start', 'stopp', 'weiter', 'zurück'];
const grammatik = `#JSGF V1.0; grammar befehle; public <befehl> = ${befehle.join(' | ')};`;

const recognition = new Recognition();
if (GrammarList) {
  const liste = new GrammarList();
  liste.addFromString(grammatik, 1);
  recognition.grammars = liste;
}
recognition.lang = 'de-DE';
recognition.interimResults = false;
recognition.maxAlternatives = 1;

recognition.addEventListener('result', (event) => {
  const text = event.results[0][0].transcript.trim().toLowerCase();
  // Grammatik ist nur ein Hinweis – Ergebnis selbst prüfen!
  if (befehle.includes(text)) {
    console.log(`Befehl erkannt: ${text}`);
  } else {
    console.log(`Unbekannte Eingabe: ${text}`);
  }
});

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

Befehl erkannt: weiter

Mehrere Grammatiken mit Gewichtung und Durchlaufen der Liste

const GrammarList = window.SpeechGrammarList ?? window.webkitSpeechGrammarList;
const liste = new GrammarList();

liste.addFromString('#JSGF V1.0; grammar ja_nein; public <antwort> = ja | nein;', 1.0);
liste.addFromURI('/grammatiken/zahlen.jsgf', 0.5);

for (let i = 0; i < liste.length; i++) {
  const g = liste[i]; // entspricht liste.item(i)
  console.log(i, g.weight);
}

0 1 1 0.5

// Wichtig · Fallstricke

Browser-Unterstützung: Chrome und Edge unterstützen das Interface nur mit Präfix als webkitSpeechGrammarList. Firefox hat die Spracherkennung standardmäßig abgeschaltet, und Safari stellt je nach Version nur webkitSpeechRecognition bereit, aber keine Grammatikliste. Deshalb immer mit Feature-Erkennung arbeiten (window.SpeechGrammarList ?? window.webkitSpeechGrammarList).
Wird oft ignoriert: Die Cloud-Spracherkennung in Chrome wertet Grammatiken in der Praxis kaum oder gar nicht aus. Man kann sich also nicht darauf verlassen, dass nur Wörter aus der Grammatik erkannt werden. Ergebnisse sollte man selbst gegen eine Wortliste prüfen.
Veraltet in der Spezifikation: In neueren Entwürfen der Web Speech API gelten Grammatiken als veraltet und werden durch andere Mechanismen zur Kontextanpassung ersetzt. In neuem Code sollte man die Grammatik deshalb höchstens als optionale Verbesserung einsetzen.
addFromURI() unterliegt den üblichen Regeln für Netzwerkzugriffe (gleicher Ursprung oder CORS). Außerdem wird die URL nicht unbedingt sofort geladen, Fehler zeigen sich also eventuell erst beim Start der Erkennung.
Die Spracherkennung braucht einen sicheren Kontext (HTTPS) und die Erlaubnis für das Mikrofon. In Chrome werden die Audiodaten zur Verarbeitung an einen Server geschickt, was für den Datenschutz wichtig ist.

Siehe auch

SpeechGrammar SVGNumberList SpeechSynthesis SourceBufferList SpeechRecognition