SpeechRecognition.processLocally — Eigenschaft · JavaScript-Referenz

Signatur

SpeechRecognition.processLocally

Beschreibung

Mit processLocally legen Sie fest, ob eine SpeechRecognition-Instanz die Sprache ausschließlich auf dem Gerät verarbeiten darf. Standardmäßig ist der Wert false. Dann entscheidet der Browser selbst, wo die Erkennung läuft. In Chrome bedeutet das meist, dass Audiodaten an einen Server-Dienst gesendet werden.

Setzen Sie die Eigenschaft auf true, wenn Datenschutz, Offline-Betrieb oder geringe Latenz wichtig sind, zum Beispiel bei Diktierfunktionen für vertrauliche Inhalte oder in Anwendungen, die ohne Netzwerk funktionieren sollen. Ist für die gewählte Sprache (lang) kein lokales Sprachmodell vorhanden, bricht die Erkennung ab: Es wird ein error-Ereignis mit dem Fehlercode "language-not-supported" ausgelöst. Der Browser weicht in diesem Fall nicht stillschweigend auf die Cloud aus.

Deshalb sollten Sie processLocally zusammen mit den statischen Methoden SpeechRecognition.available() und SpeechRecognition.install() verwenden. Mit available() prüfen Sie, ob ein lokales Modell für eine Sprache vorhanden ist. Mit install() lassen Sie es bei Bedarf herunterladen. Die Eigenschaft muss vor dem Aufruf von start() gesetzt werden.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Erkennung lokal auf dem Gerät erfolgen muss. false (Standardwert), wenn der Browser auch entfernte Dienste nutzen darf. Die Eigenschaft ist les- und schreibbar.

Beispiele

Lokale Erkennung aktivieren

const SR = window.SpeechRecognition || window.webkitSpeechRecognition;
const recognition = new SR();

recognition.lang = 'de-DE';
recognition.processLocally = true; // Audio verlässt das Gerät nicht

recognition.addEventListener('result', (event) => {
  console.log('Erkannt:', event.results[0][0].transcript);
});

recognition.addEventListener('error', (event) => {
  if (event.error === 'language-not-supported') {
    console.warn('Kein lokales Sprachmodell für', recognition.lang);
  }
});

console.log(recognition.processLocally);
recognition.start();

true Erkannt: Hallo Welt

Verfügbarkeit prüfen und Modell bei Bedarf installieren

const SR = window.SpeechRecognition || window.webkitSpeechRecognition;

const startLocalDictation = async (lang = 'de-DE') => {
  if (typeof SR?.available !== 'function') {
    console.warn('Lokale Erkennung wird nicht unterstützt');
    return;
  }

  const options = { langs: [lang], processLocally: true };
  const status = await SR.available(options);
  console.log('Status:', status);

  if (status === 'unavailable') return;

  if (status === 'downloadable' || status === 'downloading') {
    // install() möglichst aus einer Nutzeraktion heraus aufrufen
    const ok = await SR.install(options);
    if (!ok) return console.warn('Installation fehlgeschlagen');
  }

  const recognition = new SR();
  recognition.lang = lang;
  recognition.processLocally = true;
  recognition.onresult = (e) => console.log(e.results[0][0].transcript);
  recognition.start();
};

document.querySelector('#diktat').addEventListener('click', () => startLocalDictation());

Status: downloadable

Datenschutz-Schalter mit Rückfall auf Cloud-Erkennung

const SR = window.SpeechRecognition || window.webkitSpeechRecognition;

const createRecognition = ({ privateMode }) => {
  const recognition = new SR();
  recognition.lang = 'de-DE';
  // Nur setzen, wenn der Browser die Eigenschaft kennt
  if ('processLocally' in recognition) {
    recognition.processLocally = privateMode;
  } else if (privateMode) {
    throw new Error('Lokale Verarbeitung nicht verfügbar');
  }
  return recognition;
};

const rec = createRecognition({ privateMode: false });
console.log(rec.processLocally);

false

// Wichtig · Fallstricke

Experimentell: Derzeit nur in Chromium-Browsern (Chrome/Edge ab etwa Version 139) umgesetzt. Firefox unterstützt die Web Speech Recognition API nicht. Safari kennt nur webkitSpeechRecognition ohne diese Eigenschaft. Prüfen Sie die Unterstützung vorab mit 'processLocally' in recognition.
Kein automatischer Rückfall auf die Cloud: Ist true gesetzt, aber für die Sprache kein lokales Modell vorhanden, meldet die Erkennung den Fehler "language-not-supported". Prüfen Sie die Verfügbarkeit vorher mit SpeechRecognition.available().
Die Eigenschaft muss vor start() gesetzt werden. Eine Änderung während einer laufenden Sitzung wirkt erst bei der nächsten Sitzung.
Die Namen der Methoden haben sich während der Entwicklung geändert: Frühe Chrome-Versionen hießen availableOnDevice() und installOnDevice().
Lokale Modelle können mehrere hundert MB groß sein. Starten Sie den Download über install() nur nach einer Nutzeraktion und mit Hinweis an den Nutzer.
Auch bei false ist Mikrofonzugriff nötig, und dafür ist ein sicherer Kontext (HTTPS) erforderlich.

Siehe auch

SpeechRecognition.unspokenPunctuation SpeechRecognition.phrases SpeechRecognition.continuous SpeechRecognition.grammars SpeechRecognition.lang