SpeechRecognition: Statische Methode available()
Die statische Methode available() der Schnittstelle SpeechRecognition prüft, ob die angegebenen Sprachen für die Spracherkennung in der gewünschten Qualitätsstufe verfügbar sind.
Um die für die Spracherkennung auf dem Gerät erforderlichen Sprachpakete zu installieren, verwenden Sie die Methode SpeechRecognition.install(). Ein Sprachpaket enthält die Daten, die ein Browser benötigt, um Sprache in einer bestimmten Sprache zu erkennen.
Der Zugriff auf die Methode available() wird durch die on-device-speech-recognition-Direktive der Permissions-Policy gesteuert. Wenn eine Richtlinie den Zugriff blockiert, wird das von available() zurückgegebene Promise mit unavailable erfüllt.
Syntax
available(options)
Parameter
options-
Ein Objekt mit Optionen für die Verfügbarkeitsprüfung. Mögliche Eigenschaften sind:
langs-
Ein Array aus einer oder mehreren Zeichenfolgen mit BCP-47-Sprachtags, die jeweils eine Sprache angeben, deren Verfügbarkeit geprüft werden soll. Wenn
langsein leeres Array ist, wird das Promise mitunavailableerfüllt. Browserspezifische Unterschiede finden Sie unter Browser-Kompatibilität. qualityOptional-
Ein Aufzählungswert, der den ungefähren Anwendungsfall Ihrer Spracherkennungs-App und damit die erforderliche Komplexität des Sprachpakets und des Spracherkennungsdienstes angibt. Mögliche Werte sind:
command-
Stufe 1: Kurze, isolierte Äußerungen mit begrenztem Wortschatz und einer einzelnen sprechenden Person. Zu den Anwendungsfällen gehören Sprachbefehle für Apps. Dies ist der Standardwert.
dictation-
Stufe 2: Fortlaufende Sprache bei mäßigen Hintergrundgeräuschen und mit einer einzelnen hauptsächlich sprechenden Person. Zu den Anwendungsfällen gehört das Diktieren längerer Texteingaben wie SMS-Nachrichten, E-Mail-Texten oder Zeichenfolgen für die Übersetzung.
conversation-
Stufe 3: Fortlaufende Sprache mit komplexem Wortschatz, starken Hintergrundgeräuschen und mehreren hauptsächlich sprechenden Personen. Zu den Anwendungsfällen gehören die Transkription von Besprechungen und die fortlaufende Live-Untertitelung.
processLocallyOptional-
Ein boolescher Wert, der angibt, ob die Verfügbarkeit der Sprachen nur für die Spracherkennung auf dem Gerät (
true) oder für die Spracherkennung auf dem Gerät oder über einen entfernten Dienst (false) geprüft werden soll. Der Standardwert istfalse.Hinweis: Mit
available()lässt sich nicht sicherstellen, dass ein entfernter Dienst die angegebenen Sprachen unterstützt. Ein Wert vonfalsebedeutet, dass entweder ein Spracherkennungsdienst auf dem Gerät oder ein entfernter Dienst sie unterstützt.
Rückgabewert
Ein Promise, das mit einem Aufzählungswert erfüllt wird, der die Verfügbarkeit der angegebenen Sprachen für die Spracherkennung angibt.
Mögliche Werte sind:
available-
Gibt an, dass alle angegebenen Sprachen in der gewünschten
quality-Stufe unterstützt werden.- Wenn
processLocallyauftruegesetzt ist, bedeutetavailable, dass die Spracherkennung für diese Sprachen auf dem Gerät verfügbar ist. Die erforderlichen Sprachpakete wurden heruntergeladen und auf dem Gerät der nutzenden Person installiert. - Wenn
processLocallyauffalsegesetzt ist, bedeutetavailable, dass die Spracherkennung für diese Sprachen entweder auf dem Gerät oder über einen entfernten Dienst verfügbar ist.
- Wenn
downloading-
Gibt an, dass alle angegebenen Sprachen in der gewünschten
quality-Stufe für die Verarbeitung auf dem Gerät unterstützt werden und das entsprechende Sprachpaket für mindestens eine Sprache gerade heruntergeladen wird. Nur relevant, wennprocessLocallyden Werttruehat. downloadable-
Gibt an, dass die angegebenen Sprachen in der gewünschten
quality-Stufe auf dem Gerät unterstützt werden, das entsprechende Sprachpaket für mindestens eine Sprache aber noch nicht heruntergeladen wurde oder die Website dafür noch nichtinstall()aufgerufen hat (siehe folgenden Hinweis). Nur relevant, wennprocessLocallyden Werttruehat. -
Gibt an, dass mindestens eine der angegebenen Sprachen in der gewünschten
quality-Stufe nicht unterstützt wird.- Wenn
processLocallyauftruegesetzt ist, bedeutetunavailable, dass die Spracherkennung auf dem Gerät für mindestens eine der angegebenen Sprachen nicht verfügbar ist. - Wenn
processLocallyauffalsegesetzt ist, bedeutetunavailable, dass die Spracherkennung für mindestens eine der angegebenen Sprachen weder auf dem Gerät noch über einen entfernten Dienst verfügbar ist.
- Wenn
Hinweis:
Zum Schutz der Privatsphäre verbergen Browser, ob sich ein Sprachpaket bereits auf dem Gerät der nutzenden Person befindet, bis die Website für diese Sprache install() aufgerufen hat.
Bis dahin gibt available() statt available oder downloading den Wert downloadable zurück, selbst wenn das Sprachpaket bereits installiert ist oder heruntergeladen wird.
Wird install() für ein bereits installiertes Sprachpaket aufgerufen, wird es nicht erneut heruntergeladen. Spätere Aufrufe von available() geben dann den tatsächlichen Status zurück.
Endgültiger Rückgabewert bei mehreren Sprachen mit unterschiedlichem Status
Auch wenn im Array langs mehrere Sprachen angegeben sind, wird nur ein Statuswert zurückgegeben.
Wenn die angegebenen Sprachen unterschiedliche Verfügbarkeitsstatus haben, wird derjenige Status zurückgegeben, der am weitesten von available entfernt ist.
Die folgenden Listen zeigen, wie der endgültige Status bestimmt wird. Die Regeln werden jeweils der Reihe nach geprüft:
Wenn processLocally den Wert false hat:
- Wenn alle Sprachen
availablesind, wirdavailablezurückgegeben. - Andernfalls wird
unavailablezurückgegeben.
Wenn processLocally den Wert true hat:
- Wenn mindestens eine Sprache
unavailableist, wirdunavailablezurückgegeben. - Andernfalls wird
downloadablezurückgegeben, wenn mindestens eine Sprachedownloadableist. - Andernfalls wird
downloadingzurückgegeben, wenn mindestens eine Sprachedownloadingist. - Andernfalls wird
availablezurückgegeben.
Ausnahmen
InvalidStateErrorDOMException-
Das aktuelle Dokument ist nicht vollständig aktiv.
SyntaxErrorDOMException-
Mindestens eine der in
langsangegebenen Zeichenfolgen ist kein gültiger BCP-47-Sprachtag.
Beispiele
>Verfügbarkeit 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, aber das passende Sprachpaket nicht installiert ist, schlägt die Erkennung fehl. Dabei wird ein error-Ereignis mit dem Fehlercode service-not-allowed ausgelöst.
So installieren Sie das passende Sprachpaket:
- Prüfen Sie mit der Methode
available(), ob das Sprachpaket auf dem Gerät der nutzenden Person installiert ist. - Falls es nicht installiert ist, installieren Sie es mit der Methode
SpeechRecognition.install().
Diese Schritte werden mit dem folgenden Codeausschnitt ausgeführt:
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:
- Wenn der Wert
unavailableist, steht kein geeignetes Sprachpaket zum Herunterladen bereit. Außerdem geben wir eine entsprechende Meldung aus. - Wenn der Wert
availableist, ist das Sprachpaket lokal verfügbar und die Erkennung kann beginnen. In diesem Fall rufen wirstart()auf und protokollieren eine Meldung in der Konsole, sobald die App Spracheingaben empfangen kann. - Wenn der Wert weder
unavailablenochavailableist (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.
Die Methode install() beginnt mit dem Herunterladen des Sprachpakets für en-US und gibt ein Promise zurück. Dieses wird mit einem booleschen Wert erfüllt, der angibt, ob die angegebenen Sprachpakete erfolgreich heruntergeladen und installiert wurden (true) oder nicht (false).
Dieser Code stammt aus unserem Beispiel zur Farbänderung per Spracherkennung auf dem Gerät (Demo direkt ausprobieren). Eine vollständige Erläuterung finden Sie unter Die Web Speech API verwenden.
Fähigkeiten des Modells auf dem Gerät prüfen
Der folgende Codeausschnitt verändert das vorherige Beispiel.
Er ruft available() mit der Option quality auf, die auf dictation gesetzt ist, um zu prüfen, ob die Spracherkennung auf dem Gerät diese Qualitätsstufe unterstützt.
Wenn das Ergebnis unavailable ist, setzen wir die Eigenschaft processLocally des SpeechRecognition-Objekts auf false (unter der Annahme, dass sie zuvor true war). Dadurch kann der Browser einen entfernten Erkennungsdienst verwenden, sofern einer verfügbar ist. Anschließend rufen wir start() auf.
Wenn das Ergebnis available ist, rufen wir start() auf, um die Erkennung auf dem Gerät zu starten.
Bei jedem anderen Ergebnis rufen wir install() mit der auf dictation gesetzten Option quality auf, um die erforderlichen 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-available> |