Skip to content

AI

AiVoiceInput

Bit.BlazorUI.AIDictationSpeechToText

BitAiVoiceInput is a dictation button: a toggle that turns the microphone on and off and hands over what is said as text, through the speech recognition of the browser (the Web Speech API) - no server of yours, no audio for your app to handle. Each finished phrase is raised through OnTranscript and the provisional text through OnInterim while the user is still speaking. With a Transcriber (or an IBitAiSpeechToText service registered through UseSpeechToText) it records the microphone instead and hands the whole take to the app's own speech-to-text - which also works where the browser has no speech recognition (Firefox, Android WebView), with the time left of the recording shown beside the button. Where it cannot dictate either way, it renders nothing at all rather than a button that does nothing.

Notes

To use this component, you need to install the Bit.BlazorUI.AI(opens in a new tab) nuget package, as described in the Optional steps of the Getting started page.

BitAiVoiceInput renders nothing in a browser without speech recognition (Firefox, for one) - unless the app transcribes the speech itself (the Transcriber example below) - and it asks the browser once it is on the page, so it is never part of a prerendered page either. Where nothing shows in the examples below, try a Chromium browser or Safari. The browser asks for the microphone the first time it is pressed, and does the recognition itself - some (Chrome, for one) in their vendor's cloud service, so do not offer it for speech that must not leave the device. One dictation runs at a time on a page: starting one in a second voice input stops the first, which raises its OnListeningChanged as if it had stopped on its own.

The button says what a press does next (Dictate, then Stop dictation) - its name alone, with no pressed state on top of it to read ambiguously - and is filled in the listening color, with a ring pulsing around it (standing still under reduced motion), while the microphone is on, whichever way it dictates. A polite live region announces when the dictation starts, stops or fails (Listening, Dictation stopped, Dictation failed: microphone access was denied), and the reason of a failure is also shown above the button for a few seconds. These texts come from the strings in force (StartDictation, StopDictation, Listening, DictationStopped, DictationFailed), which a BitAiOptionsProvider localizes. A phrase still being spoken when the button stops the dictation is kept: it arrives through OnTranscript once the recognizer has committed to it. A BitAiPromptInput with AllowDictation already carries one; see the attachments scenario for it in a chat.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

Press the microphone and speak: OnTranscript receives each phrase once the recognizer has committed to it. Press it again to stop. Nothing shows here in a browser that cannot transcribe.


Heard: nothing yet

Interim & listening

OnInterim carries the provisional text as the user speaks - it changes with every syllable - and an empty one once that text is final or gone. OnListeningChanged is raised when the dictation starts or stops, however that happens (the button, a silence the browser ends it on, an error, or another voice input of the page starting its own dictation - one runs at a time, so try any other button of this page); IsListening says the same at any time.


Listening: False (IsListening: )
Provisional:
Final:

With a text field

The button only hands over text, so it goes beside any field: here each phrase is appended to a BitTextField, and the provisional text shows as its description until it is final.

Language

Language is the language listened for, as a BCP 47 tag - the browser's own language when null. Pick one and speak it.



Heard (en-US): nothing yet

OnError

OnError receives the name of the error the browser reported when the dictation fails - not-allowed for a microphone refused, no-speech for a silence, audio-capture for no microphone at all, network - and the dictation stops. Refuse the microphone to see it.


Heard: nothing yet
Last error: none

Cascading parameters

BitParams with a BitAiVoiceInputParams sets the Language and the look of every voice input inside it; a parameter of the voice input itself still wins.

British English:

Its own Language, German:

Heard: nothing yet

Disabled

A disabled voice input cannot be pressed. Disabling it while it listens stops the dictation, rather than leaving the microphone on with nothing able to turn it off.


Heard: nothing yet

Transcriber

Transcriber hands the speech to the app's own speech-to-text (Whisper, Azure Speech, ...): the microphone is recorded in the browser - which works in Firefox and Android WebView too - and the whole take is handed to it, with its media type, once the user stops; what it returns arrives through OnTranscript. An app that transcribes the same way everywhere registers an IBitAiSpeechToText instead (AddBitBlazorUIAIServices(ai => ai.UseSpeechToText<T>())), which every voice input, and every composer's dictation, then uses. The recording stops on its own at MaxRecordingDuration - the time left counts down beside the button, and is announced once ten seconds before - and, with SilenceTimeout, once the user has said something and then been quiet that long. Mode decides which way a press dictates: Auto (the transcriber when there is one), Browser (the speech recognition of the browser, with the transcriber only where there is none) or Recording (the transcriber only). The transcriber here only describes what it was handed.



Listening: False
Heard: nothing yet
Last error: none

Style & Class

Style and Class reach the root, Styles and Classes its button (BitToggleButtonClassStyles) and its visually hidden live region (and the countdown of a recording). The button is restyled through the public --bit-ToggleButton-* variables, from :root, an ancestor or Style; of its own the voice input has --bit-AiVoiceInput-countdown-color, the color of the time left of a recording.


Heard: nothing yet

RTL

Use BitAiVoiceInput in right-to-left (RTL). The direction only lays it out: its Language is what decides the language listened for - Persian here.

شنیده شد: هنوز چیزی شنیده نشده

CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle it - and any instance nested inside it, which inherits the value too; a parameter changes one alone, as does the real CSS property on the instance's Style / Styles when that property does not inherit (opacity: 1 keeps one disabled instance undimmed without undimming a disabled one inside it), while an inherited one such as color or font-family also reaches the nested instances that do not set it themselves. Leave a variable unset and the component falls back to the theme token beside it.

BitAiVoiceInput CSS variables

Name Default value Description
--bit-AiVoiceInput-listening-color var(--bit-clr-err-text) Color of the microphone while the voice input listens, through the speech recognition of the browser or by recording alike.
--bit-AiVoiceInput-listening-background var(--bit-clr-err) Background of the button while the voice input listens.
--bit-AiVoiceInput-listening-hover-background var(--bit-clr-err-hover) Background of the button while the voice input listens and the pointer is over it.
--bit-AiVoiceInput-listening-active-background var(--bit-clr-err-active) Background of the button while the voice input listens and it is pressed.
--bit-AiVoiceInput-pulse-color the listening background Color of the ring pulsing around the button while the voice input listens (a steady ring under reduced motion).
--bit-AiVoiceInput-countdown-color var(--bit-clr-fg-sec) Color of the time left of a recording for the app's transcriber, shown beside the button while it records.
--bit-AiVoiceInput-error-color var(--bit-clr-err-fg) Color of the reason a dictation failed, shown above the button for a few seconds after the failure.

API

Every parameter, public member, sub-class and enum this component exposes.

BitAiVoiceInput parameters

Name Type Default value Description
Classes BitAiVoiceInputClassStyles? null Custom CSS classes for different parts of the voice input.
Language string? null The recognition language, as a BCP 47 language tag such as en-US. When null, the language of the browser is used - or, with a transcriber, whatever the transcriber decides (an IBitAiSpeechToText is handed it). It is read when the dictation starts.
MaxRecordingDuration TimeSpan 1 minute The longest a recording for the transcriber may last; it is transcribed, not thrown away, when it reaches it. The time left is shown beside the button while it records, and announced once ten seconds before the end.
MaxRecordingSize long 10 MB The largest recording handed to the transcriber, in bytes; a larger one fails with too-large. It is streamed to .NET in chunks, on Blazor Server as on WebAssembly.
Mode BitAiDictationMode BitAiDictationMode.Auto How speech is turned into text: through the app's transcriber, through the speech recognition of the browser, or through the one with the other as the fallback.
OnError EventCallback<string> Raised when the transcription fails, with the name of the error the browser reported - not-allowed for a microphone the user refused, no-speech, audio-capture, network and the like - or, for a recording, not-allowed, audio-capture, recording-failed, too-large or transcription-failed (the transcriber threw). The dictation has stopped by then, the live region has announced the failure, and its reason is shown beside the button for a few seconds.
OnInterim EventCallback<string> Raised with the provisional text as the user speaks, which may still change, and with an empty one once that text is final or gone. Only the speech recognition of the browser has provisional text; a transcriber hears the whole recording at once.
OnListeningChanged EventCallback<bool> Raised when the dictation starts (true) or stops (false), however that happens: the button, a Disabled set while listening, a silence the browser ends it on, an error, or another voice input of the page starting its own dictation (one runs at a time). A recording stops listening as it ends, before it is transcribed (IsTranscribing).
OnTranscript EventCallback<string> Raised with each finalised phrase, trimmed, once the recognizer has committed to it - or, with a transcriber, with what it heard in the recording.
SilenceTimeout TimeSpan? null Ends a recording for the transcriber once the user has said something and then been quiet for this long. When null, a recording ends when the user stops it, or at MaxRecordingDuration.
Styles BitAiVoiceInputClassStyles? null Custom CSS styles for different parts of the voice input.
Transcriber Func<Stream, string, CancellationToken, Task<string?>>? null The app's speech-to-text, given a recording (read from its start, and disposed once the task completes), its media type (audio/webm in Chromium and Firefox, audio/mp4 in Safari) and a token cancelled when the voice input goes away; it returns what was said. With one, the microphone is recorded in the browser and the take transcribed by the app (see Mode). When null, an IBitAiSpeechToText registered through AddBitBlazorUIAIServices(ai => ai.UseSpeechToText<T>()) is used, if there is one.

BitAiVoiceInput public members

Name Type Default value Description
IsListening bool false Whether the dictation is running - what OnListeningChanged reported last. False while the browser cannot transcribe.
IsTranscribing bool false Whether a recording is being transcribed by the app's transcriber - between the end of the recording and its transcript. The button waits, unavailable, meanwhile.

BitComponentBase parameters

Name Type Default value Description
AriaLabel string? null Gets or sets the accessible label for the component, used by assistive technologies.
Class string? null Gets or sets the CSS class name(s) to apply to the rendered element.
Dir BitDir? null Gets or sets the text directionality for the component's content.
Disabled bool false Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction.
ForceAnimation bool false Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested.
HtmlAttributes Dictionary<string, object> new Dictionary<string, object>() Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name.
Id string? null Gets or sets the unique identifier for the component's root element.
Style string? null Gets or sets the CSS style string to apply to the rendered element.
TabIndex string? null Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility BitVisibility BitVisibility.Visible Gets or sets the visibility state (visible, hidden, or collapsed) of the component.

BitComponentBase public members

Name Type Default value Description
UniqueId Guid Guid.NewGuid() Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement ElementReference Gets the reference to the root HTML element associated with this component.

BitAiVoiceInputClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitAiVoiceInput.
Listening string? null Custom CSS classes/styles for the root element of the BitAiVoiceInput while it listens - through the speech recognition of the browser or by recording for the app's transcriber alike - beside the bit-aivci-lsn class it carries then (and bit-aivci-rec, only while it records for the transcriber).
Button BitToggleButtonClassStyles? null Custom CSS classes/styles for the BitToggleButton of the BitAiVoiceInput that starts and stops the dictation (its Checked member is the state while the microphone is on).
Countdown string? null Custom CSS classes/styles for the time left of a recording for the app's transcriber, shown beside the button while it records.
Error string? null Custom CSS classes/styles for the reason a dictation failed, shown above the button for a few seconds after the failure.
LiveRegion string? null Custom CSS classes/styles for the visually hidden live region of the BitAiVoiceInput that announces whether the microphone is on.

BitAiDictationMode enum

Name Value Description
Auto 0 Through the app's transcriber when it supplies one (Transcriber, or an IBitAiSpeechToText service), recording the microphone in the browser; through the speech recognition of the browser otherwise.
Browser 1 Through the speech recognition of the browser where it has one, and through the app's transcriber, when it supplies one, only where it has none (Firefox, Android WebView).
Recording 2 Through the app's transcriber only, recording the microphone in the browser. With no transcriber the button is not shown.

BitVisibility enum

Name Value Description
Visible 0 The content of the component is visible.
Hidden 1 The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed 2 The component is hidden (display:none).

BitDir enum

Name Value Description
Ltr 0 Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl 1 Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto 2 Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.