SpeechRecognition.install() — Methode · JavaScript-Referenz

Signatur

SpeechRecognition.install(options)

Beschreibung

SpeechRecognition.install() ist eine statische Methode der Web Speech API. Sie sorgt dafür, dass die Sprachmodelle für eine oder mehrere Sprachen lokal auf dem Gerät liegen. Danach kann die Spracherkennung laufen, ohne dass Audiodaten an einen Cloud-Dienst gehen. Das bringt mehr Datenschutz, geringere Latenz und Offline-Fähigkeit.

Normalerweise verwendest du die Methode zusammen mit SpeechRecognition.available(). Zuerst fragst du ab, ob die gewünschten Sprachen lokal schon "available" sind oder erst "downloadable". Nur im zweiten Fall rufst du install() auf. Danach setzt du auf der Instanz recognition.processLocally = true, damit die Erkennung wirklich auf dem Gerät läuft.

Die Methode gibt ein Promise zurück. Es wird mit true erfüllt, wenn alle angeforderten Sprachpakete installiert wurden. Es wird mit false erfüllt, wenn mindestens eine Sprache nicht unterstützt wird oder die Installation fehlschlägt. Der Download kann je nach Modell mehrere Dutzend bis Hunderte Megabyte groß sein. Starte ihn deshalb am besten bewusst nach einer Nutzeraktion und zeige dabei einen Fortschritts- oder Wartehinweis an.

Parameter

Name	Typ	Default	Beschreibung
$options Pflicht	Object		Konfigurationsobjekt für die Installation.
$options.langs Pflicht	string[]		Array aus BCP-47-Sprach-Tags, z. B. `["de-DE", "en-US"]`, deren Sprachpakete installiert werden sollen.
$options.processLocally	boolean	false	Gibt an, ob die Pakete für die lokale Verarbeitung gedacht sind. In aktuellen Entwürfen ist das der Standardfall für die Installation. In einigen Implementierungen wird dieser Wert ignoriert oder gar nicht unterstützt.

Rückgabewert

Typ

Promise<boolean>

Beschreibung

Wird mit true erfüllt, wenn alle angegebenen Sprachpakete erfolgreich installiert wurden. Wird mit false erfüllt, wenn eine Sprache nicht unterstützt wird oder die Installation fehlschlägt. Das Promise wird abgelehnt (z. B. mit InvalidStateError), wenn das Dokument nicht aktiv ist.

Beispiele

Sprachpaket bei Bedarf installieren

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

const ensureLocalModel = async (lang) => {
  if (!SR || typeof SR.install !== 'function') {
    console.log('On-Device-Erkennung nicht unterstützt');
    return false;
  }
  const status = await SR.available({ langs: [lang], processLocally: true });
  console.log('Status:', status);

  if (status === 'available') return true;
  if (status === 'unavailable') return false;

  // "downloadable" oder "downloading"
  return SR.install({ langs: [lang], processLocally: true });
};

ensureLocalModel('de-DE').then((ok) => console.log('Bereit:', ok));

Status: downloadable Bereit: true

Installation per Button starten und lokal erkennen

const SR = window.SpeechRecognition || window.webkitSpeechRecognition;
const button = document.querySelector('#offline-diktat');

button.addEventListener('click', async () => {
  button.disabled = true;
  button.textContent = 'Lade Sprachmodell …';

  const ok = await SR.install({ langs: ['de-DE'] });
  if (!ok) {
    button.textContent = 'Deutsch lokal nicht verfügbar';
    return;
  }

  const recognition = new SR();
  recognition.lang = 'de-DE';
  recognition.processLocally = true; // Audio verlässt das Gerät nicht
  recognition.onresult = (e) => console.log(e.results[0][0].transcript);
  recognition.start();
  button.textContent = 'Sprich jetzt …';
});

Hallo Welt

Mehrere Sprachen auf einmal installieren

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

const installAll = async () => {
  try {
    const ok = await SR.install({ langs: ['de-DE', 'en-US', 'fr-FR'] });
    console.log(ok ? 'Alle Pakete installiert' : 'Mindestens eine Sprache fehlgeschlagen');
  } catch (err) {
    console.error('Installation abgebrochen:', err.name);
  }
};

installAll();

Alle Pakete installiert

// Wichtig · Fallstricke

Experimentell: Die Methode wird derzeit nur von Chromium-basierten Browsern unterstützt (ab ca. Chrome 139). Firefox und Safari kennen sie nicht. Prüfe deshalb vorher mit typeof SpeechRecognition.install === 'function', ob sie vorhanden ist. In Chrome ist der Konstruktor teils nur als webkitSpeechRecognition verfügbar.
Spezifikation noch im Wandel: Frühere Entwürfe hießen installOnDevice(lang) und nahmen nur einen einzelnen String entgegen. Auch die Namen der Optionen haben sich geändert. Verlass dich deshalb nicht blind auf ein bestimmtes Options-Schema.
Ein Teilfehler zählt als Fehler: Das Ergebnis ist ein einziges boolean für alle Sprachen. Scheitert eine einzige Sprache, lautet das Ergebnis false. Wenn du wissen willst, welche Sprache fehlt, frag den Status danach mit available() einzeln pro Sprache ab.
Kein Fehler bei ungültigen Sprach-Tags: Nicht unterstützte oder ungültige Sprach-Tags lösen keine Ausnahme aus, sondern führen zu false.
Datenvolumen und Nutzererlebnis: Die Downloads können groß sein. Starte sie nicht ungefragt beim Laden der Seite, sondern nach einer ausdrücklichen Nutzeraktion. Auf getakteten Verbindungen (z. B. Mobilfunk) solltest du vorher nachfragen. Browser können eine Nutzeraktivierung verlangen oder Downloads drosseln.
Datenschutz: Websites könnten die installierten Sprachpakete auswerten, um Nutzer wiederzuerkennen (Fingerprinting). Browser können deshalb Ergebnisse verschleiern oder die Installation einschränken, z. B. im Inkognito-Modus.
Die Installation allein aktiviert noch keine lokale Erkennung. Dafür musst du zusätzlich recognition.processLocally = true setzen.

Siehe auch

SpeechRecognition.available() SpeechRecognition.start() SpeechRecognition.stop() SpeechRecognition.abort() SpeechRecognitionResult.item()