SpeechRecognition: Statische Methode install()
Die statische Methode install() der Schnittstelle SpeechRecognition installiert die Sprachpakete, die für die Spracherkennung auf dem Gerät in den angegebenen Sprachen und auf der angegebenen Qualitätsstufe benötigt werden.
Ein Sprachpaket enthält die Daten, die ein Browser benötigt, um Sprache in einer bestimmten Sprache zu erkennen.
Nach der Installation kann die Erkennung in dieser Sprache auf dem Gerät der nutzenden Person ausgeführt werden. Audiodaten müssen dann nicht an einen entfernten Dienst gesendet werden.
Mit der Methode SpeechRecognition.available() können Sie prüfen, ob die Sprachpakete bereits installiert sind. Setzen Sie dazu processLocally auf true.
Der Zugriff auf die Methode install() wird durch die on-device-speech-recognition-Direktive von Permissions-Policy gesteuert.
Wenn eine Richtlinie den Zugriff blockiert, wird das von install() zurückgegebene Promise mit einer DOMException vom Typ NotAllowedError zurückgewiesen.
Syntax
install(options)
Parameter
options-
Ein Objekt mit Optionen für die Installation. Mögliche Eigenschaften sind:
langs-
Ein Array aus mindestens einem String mit einem BCP-47-Sprachtag. Jeder String steht für eine Sprache, deren Sprachpaket Sie installieren möchten.
qualityOptional-
Ein Aufzählungswert, der den ungefähren Anwendungsfall Ihrer Spracherkennungs-App angibt.
install()installiert Sprachpakete, die mindestens diese Qualitätsstufe unterstützen. Mögliche Werte sind:command-
Stufe 1: Kurze, einzeln gesprochene Äußerungen mit begrenztem Wortschatz und einer sprechenden Person. Ein Anwendungsfall sind Sprachbefehle für Apps. Dies ist der Standardwert.
dictation-
Stufe 2: Fortlaufende Sprache bei mäßigen Hintergrundgeräuschen und mit einer hauptsächlich sprechenden Person. Anwendungsfälle sind das Diktieren längerer Texteingaben wie SMS-Nachrichten, E-Mail-Texten oder zu übersetzenden Texten.
conversation-
Stufe 3: Fortlaufende Sprache mit komplexem Wortschatz, starken Hintergrundgeräuschen und mehreren hauptsächlich sprechenden Personen. Anwendungsfälle sind das Transkribieren von Besprechungen und die fortlaufende Live-Untertitelung.
processLocallyOptional-
Ein boolescher Wert.
install()installiert immer Sprachpakete für die Spracherkennung auf dem Gerät. Diese Option hat daher keine Wirkung. Sie könneninstall()also dasselbe Optionsobjekt übergeben wieavailable(). Browserspezifische Unterschiede finden Sie unter Browser-Kompatibilität.
Rückgabewert
Ein Promise, das mit einem booleschen Wert erfüllt wird. Dieser gibt an, ob die Sprachpakete erfolgreich installiert wurden.
Das Promise wird mit einem der folgenden Werte erfüllt:
true-
Alle Installationsversuche für die angeforderten Sprachen waren erfolgreich, oder die Sprachen waren bereits installiert.
false-
Eine oder mehrere der angeforderten Sprachen werden nicht unterstützt, die Installation des Sprachpakets für eine unterstützte Sprache ist fehlgeschlagen, der Browser hat den Download eines Sprachpakets abgelehnt (beispielsweise weil die nutzende Person eine Berechtigungsanfrage abgelehnt hat) oder das Array
langswar leer.
Ausnahmen
InvalidStateErrorDOMException-
Das aktuelle Dokument ist nicht vollständig aktiv.
NotAllowedErrorDOMException-
Einer der folgenden Fälle liegt vor:
- Der Aufruf würde den Download eines Sprachpakets starten, aber die Seite verfügt nicht über eine vorübergehende Aktivierung.
- Die Verwendung von
install()wird durch dieon-device-speech-recognition-Direktive vonPermissions-Policyblockiert.
SyntaxErrorDOMException-
Mindestens einer der in
langsangegebenen Strings ist kein gültiger BCP-47-Sprachtag.
Beispiele
>Verfügbarkeit der Spracherkennung auf dem Gerät prüfen und Sprachpakete installieren
Damit die Spracherkennung auf dem Gerät funktioniert, muss im Browser ein Sprachpaket für die Sprache installiert sein, die Sie erkennen möchten.
Wenn Sie start() aufrufen, nachdem Sie processLocally auf true gesetzt haben, das passende Sprachpaket aber nicht installiert ist, schlägt die Erkennung fehl. Dabei wird ein error-Ereignis mit dem Fehlercode service-not-allowed ausgelöst.
Gehen Sie in zwei Schritten vor, um das passende Sprachpaket zu installieren:
- Prüfen Sie mit der Methode
SpeechRecognition.available(), ob das Sprachpaket auf dem Gerät der nutzenden Person installiert ist. - Wenn es nicht installiert ist, installieren Sie es mit der Methode
install().
Der folgende Codeausschnitt führt diese Schritte aus:
startBtn.addEventListener("click", () => {
// Check availability of target language
SpeechRecognition.available({ langs: ["en-US"], processLocally: true }).then(
(result) => {
if (result === "unavailable") {
diagnostic.textContent = `en-US not available to download at this time. Sorry!`;
} else if (result === "available") {
recognition.start();
console.log("Ready to receive a color command.");
} else {
diagnostic.textContent = `en-US language pack downloading`;
SpeechRecognition.install({
langs: ["en-US"],
processLocally: true,
}).then((result) => {
if (result) {
diagnostic.textContent = `en-US language pack downloaded. Try again.`;
} else {
diagnostic.textContent = `en-US language pack failed to download. Try again later.`;
}
});
}
},
);
});
Zuerst rufen wir die Methode available() auf. Dabei geben wir mit langs: ["en-US"] eine Sprache an, deren Verfügbarkeit geprüft werden soll, und setzen processLocally: true. Wir prüfen drei mögliche Rückgabewerte:
- Ist der Wert
unavailable, steht kein geeignetes Sprachpaket zum Download bereit. Wir geben außerdem eine entsprechende Meldung aus. - Ist der Wert
available, ist das Sprachpaket lokal verfügbar und die Erkennung kann beginnen. In diesem Fall rufen wirstart()auf und geben eine Meldung in der Konsole aus, sobald die App Sprache empfangen kann. - Hat der Wert einen anderen Inhalt (
downloadableoderdownloading), geben wir eine Diagnosemeldung aus, um die nutzende Person darüber zu informieren, dass ein Sprachpaket heruntergeladen wird. Anschließend rufen wir die Methodeinstall()auf, um den Download durchzuführen.
Danach rufen wir die Methode install() mit denselben Optionen auf.
Sie beginnt mit dem Download des Sprachpakets für en-US und gibt ein Promise zurück. Dieses wird mit true erfüllt, wenn die Sprachpakete erfolgreich heruntergeladen und installiert wurden, andernfalls mit false.
Dieser Code stammt aus unserem Beispiel zum Ändern von Farben per Spracherkennung auf dem Gerät (Demo öffnen). Eine ausführliche Erklärung finden Sie unter Verwendung der Web Speech API.
Ein Sprachpaket für eine bestimmte Qualitätsstufe installieren
Der folgende Codeausschnitt verändert das vorherige Beispiel.
Er ruft available() mit der Option quality und dem Wert dictation auf, um zu prüfen, ob die Spracherkennung auf dem Gerät diese Qualitätsstufe unterstützt.
Ist das Ergebnis unavailable, setzen wir die Eigenschaft processLocally des SpeechRecognition-Objekts auf false (unter der Annahme, dass sie zuvor true war) und rufen dann start() auf. Dadurch kann der Browser einen entfernten Erkennungsdienst verwenden, falls einer verfügbar ist.
Ist das Ergebnis available, rufen wir start() auf, um die Spracherkennung auf dem Gerät zu starten.
Bei jedem anderen Ergebnis rufen wir install() mit der Option quality und dem Wert dictation auf, um die benötigten Sprachpakete zu installieren.
startBtn.addEventListener("click", () => {
// Check availability of on-device target language dictation quality
SpeechRecognition.available({
langs: ["en-US"],
processLocally: true,
quality: "dictation",
}).then((result) => {
if (result === "unavailable") {
diagnostic.textContent = `On-device recognition for dictation not available. Falling back to any available recognition service.`;
recognition.processLocally = false;
recognition.start();
} else if (result === "available") {
recognition.start();
console.log("Ready to receive a color command.");
} else {
diagnostic.textContent = `en-US language pack downloading`;
SpeechRecognition.install({
langs: ["en-US"],
processLocally: true,
quality: "dictation",
}).then((result) => {
if (result) {
diagnostic.textContent = `en-US language pack downloaded. Try again.`;
} else {
diagnostic.textContent = `en-US language pack failed to download. Try again later.`;
}
});
}
});
});
Spezifikationen
| Spezifikation |
|---|
| Web Speech API> # dom-speechrecognition-install> |