Package com.smartgwt.client.util

Class VoiceAssist

java.lang.Object
com.smartgwt.client.util.VoiceAssist
public class VoiceAssist extends Object
The VoiceAssist class provides voice-interaction features by leveraging the browser?s speech recognition capabilities, typically through the SpeechRecognition or webkitSpeechRecognition interfaces. At the time of writing, full support is available in Chromium-based browsers like Chrome and Edge (on desktop). Safari provides partial support through the webkitSpeechRecognition API. Firefox does not support speech recognition due to privacy and security concerns, and some Chromium-based browsers like Brave also omit support due to their exclusion of Google?s proprietary services.

To enable VoiceAssist, call enable(), optionally passing the keyName you want to use for activation and recording - the default is Control. Once initialized, VoiceAssist can be activated or deactivated with three quick taps of the voiceKey.

When recognition is active, a user may double-tap the voiceKey to begin dictating a value for a focused input control. Text appears in the input control as the user speaks and the transcription is completed by a subsequent double-tap of the voiceKey, or by remaining silent for a number of seconds.

In addition to value-dictation, a user may dictate a command to be issued to the focused component, which may deal with the text itself or forward to an AI for action. If the focused component doesn't support voice-commands but one of its parents does, that parent will be the focus of your dictated command. To begin dictating a command, press and hold the voiceKey - while the key remains pressed, the recordingProgress() method is fired with interim text-results as the user speaks.

If the user speaks one of the cancelPhrases, the interim text is discarded and recording is canceled.

When the user releases the speech-key, recording is stopped and the final text of the recording is passed to the target component for action.

  • Constructor Summary

    Constructors
    Constructor
    Description
    VoiceAssist()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    cancelRecording()
    Cancels any ongoing recording session (value or command) and discards the transcription.
    static void
    disable()
    Disables VoiceAssist completely, removing keyboard listeners, deactivating if currently active, and canceling any in-progress recording.
    static void
    enable()
    Enables the VoiceAssist module by initializing the speech-recognition engine and, on non-mobile browsers, installing keyboard listeners for the speech-key.
    static void
    enable(String key)
    Enables the VoiceAssist module by initializing the speech-recognition engine and, on non-mobile browsers, installing keyboard listeners for the speech-key.
    static int
    getAutoStopDelay()
    VoiceAssist will stop recording automatically if the user stops speaking for this length of time.
    static boolean
    getCanDictateCommands()
    Whether VoiceAssist allows command-dictation, where the user's speech is transcribed and forwarded to a target component (or AI) for execution.
    static boolean
    getCanDictateValues()
    Whether VoiceAssist allows value-dictation, where the user's speech is transcribed into a focused text field.
    static String
    getLanguage()
    The BCP 47 language-tag for the language that VoiceAssist expects to interpret.
    static int
    getNoSpeechDelay()
    VoiceAssist will stop recording automatically if the user doesn't speak at all for this length of time.
    static Img
    getVoiceAssistButton()
    Returns an Img widget pre-configured to start and stop VoiceAssist recording.
    static FormItemIcon
    getVoiceAssistIcon()
    Returns a FormItemIcon properties object configured for VoiceAssist value-dictation.
    static FormItemIcon
    getVoiceAssistIcon(FormItemIcon properties)
    Returns a FormItemIcon properties object configured for VoiceAssist value-dictation.
    static String
    getVoiceKey()
    The key that activates and performs VoiceAssist features like value and command dictation.
    static void
    recordingProgress(String text)
    Event fired with interim text-results as the user speaks.
    static void
    setActive(boolean active)
    Sets whether VoiceAssist is active.
    static void
    setAutoStopDelay(int autoStopDelay)
    VoiceAssist will stop recording automatically if the user stops speaking for this length of time.
    static void
    setCanDictateCommands(boolean canDictateCommands)
    Whether VoiceAssist allows command-dictation, where the user's speech is transcribed and forwarded to a target component (or AI) for execution.
    static void
    setCanDictateValues(boolean canDictateValues)
    Whether VoiceAssist allows value-dictation, where the user's speech is transcribed into a focused text field.
    static void
    setLanguage(String language)
    The BCP 47 language-tag for the language that VoiceAssist expects to interpret.
    static void
    setNoSpeechDelay(int noSpeechDelay)
    VoiceAssist will stop recording automatically if the user doesn't speak at all for this length of time.
    static void
    setVoiceKey(String voiceKey)
    The key that activates and performs VoiceAssist features like value and command dictation.
    static void
    startDictatingCommand()
    Begins command-dictation.
    static void
    startDictatingValue()
    Begins value-dictation for the currently focused FormItem.
    static void
    stopDictatingCommand()
    Stops an ongoing command-dictation session normally, forwarding the transcribed text to the target component for execution.
    static void
    stopDictatingValue()
    Stops an ongoing value-dictation session normally, applying the transcribed text to the target FormItem.
    static boolean
    stopRecording()
    Stops any ongoing recording session (value or command) normally, applying the transcribed text.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • VoiceAssist

      public VoiceAssist()

  • Method Details

    • setAutoStopDelay

      public static void setAutoStopDelay(int autoStopDelay)
      VoiceAssist will stop recording automatically if the user stops speaking for this length of time. The default is 2 seconds.
      Parameters:
      autoStopDelay - new autoStopDelay. Default value is 2000.

    • getAutoStopDelay

      public static int getAutoStopDelay()
      VoiceAssist will stop recording automatically if the user stops speaking for this length of time. The default is 2 seconds.
      Returns:
      current value of autoStopDelay

    • setCanDictateCommands

      public static void setCanDictateCommands(boolean canDictateCommands)
      Whether VoiceAssist allows command-dictation, where the user's speech is transcribed and forwarded to a target component (or AI) for execution. When false, the long-press gesture is ignored and startDictatingCommand() is a no-op.
      Parameters:
      canDictateCommands - new canDictateCommands. Default value is true.

    • getCanDictateCommands

      public static boolean getCanDictateCommands()
      Whether VoiceAssist allows command-dictation, where the user's speech is transcribed and forwarded to a target component (or AI) for execution. When false, the long-press gesture is ignored and startDictatingCommand() is a no-op.
      Returns:
      current value of canDictateCommands

    • setCanDictateValues

      public static void setCanDictateValues(boolean canDictateValues)
      Whether VoiceAssist allows value-dictation, where the user's speech is transcribed into a focused text field. When false, the voice-assist inline icon is not shown on form items, the double-tap gesture is ignored, and startDictatingValue() is a no-op.
      Parameters:
      canDictateValues - new canDictateValues. Default value is true.

    • getCanDictateValues

      public static boolean getCanDictateValues()
      Whether VoiceAssist allows value-dictation, where the user's speech is transcribed into a focused text field. When false, the voice-assist inline icon is not shown on form items, the double-tap gesture is ignored, and startDictatingValue() is a no-op.
      Returns:
      current value of canDictateValues

    • setLanguage

      public static void setLanguage(String language)
      The BCP 47 language-tag for the language that VoiceAssist expects to interpret. These are in the format "language-REGION", like "en-US" or "fr-FR". If unset, VoiceAssist uses the language provided by your browser or OS.
      Parameters:
      language - new language. Default value is null.

    • getLanguage

      public static String getLanguage()
      The BCP 47 language-tag for the language that VoiceAssist expects to interpret. These are in the format "language-REGION", like "en-US" or "fr-FR". If unset, VoiceAssist uses the language provided by your browser or OS.
      Returns:
      current value of language

    • setNoSpeechDelay

      public static void setNoSpeechDelay(int noSpeechDelay)
      VoiceAssist will stop recording automatically if the user doesn't speak at all for this length of time. The default is 3 seconds.
      Parameters:
      noSpeechDelay - new noSpeechDelay. Default value is 3000.

    • getNoSpeechDelay

      public static int getNoSpeechDelay()
      VoiceAssist will stop recording automatically if the user doesn't speak at all for this length of time. The default is 3 seconds.
      Returns:
      current value of noSpeechDelay

    • setVoiceKey

      public static void setVoiceKey(String voiceKey)
      The key that activates and performs VoiceAssist features like value and command dictation.
      Parameters:
      voiceKey - new voiceKey. Default value is "Control".

    • getVoiceKey

      public static String getVoiceKey()
      The key that activates and performs VoiceAssist features like value and command dictation.
      Returns:
      current value of voiceKey

    • cancelRecording

      public static boolean cancelRecording()
      Cancels any ongoing recording session (value or command) and discards the transcription. If value-dictation was in progress, the target item's value is restored to its pre-recording state.
      Returns:
      true if a recording was canceled, false if no recording was in progress

    • disable

      public static void disable()
      Disables VoiceAssist completely, removing keyboard listeners, deactivating if currently active, and canceling any in-progress recording. After calling this method, enable() must be called again before VoiceAssist can be reactivated.
      See Also:

    • enable

      public static void enable()
      Enables the VoiceAssist module by initializing the speech-recognition engine and, on non-mobile browsers, installing keyboard listeners for the speech-key. Once enabled, a user may triple-tap the speech-key to activate VoiceAssist. On handset and tablet devices, keyboard listeners are skipped (virtual keyboards do not fire physical key events); call setActive() directly from a button or other UI element instead.

      No intrusive mic/speech probe is performed at enable time. The probe runs on the first call to setActive().

      See Also:

    • enable

      public static void enable(String key)
      Enables the VoiceAssist module by initializing the speech-recognition engine and, on non-mobile browsers, installing keyboard listeners for the speech-key. Once enabled, a user may triple-tap the speech-key to activate VoiceAssist. On handset and tablet devices, keyboard listeners are skipped (virtual keyboards do not fire physical key events); call setActive() directly from a button or other UI element instead.

      No intrusive mic/speech probe is performed at enable time. The probe runs on the first call to setActive().

      Parameters:
      key - optional different key to use for VoiceAssist - use with care
      See Also:

    • getVoiceAssistButton

      public static Img getVoiceAssistButton()
      Returns an Img widget pre-configured to start and stop VoiceAssist recording. The button can be placed anywhere in the UI (toolbars, tab-bar controls, etc.) to give users a clickable entry point for voice interaction.

      When clicked, the button determines the recording mode based on the currently focused component. If a FormItem that supports value-dictation is focused, value-dictation begins; otherwise, command-dictation begins. Recording stops on a second click, or automatically after a period of silence (see autoStopDelay).

      If VoiceAssist has not yet been active when clicked, the button calls setActive() automatically.

      The button is created with canFocus: false so that clicking it does not steal focus from the component whose value or commands are being dictated.

      Returns:
      a live widget wired for VoiceAssist recording

    • getVoiceAssistIcon

      public static FormItemIcon getVoiceAssistIcon()
      Returns a FormItemIcon properties object configured for VoiceAssist value-dictation. The icon appears inline on the right side of a text field when focused, and clicking it toggles voice recording on and off.

      This is the same icon configuration used internally when FormItem.showVoiceAssistIcon is enabled. Use this method to retrieve the config for manual inclusion in a custom item's FormItem.icons array.

      The returned object is a copy of voiceAssistIconDefaults, so customizations made to the defaults are reflected in all subsequently created icons.

      Returns:
      icon properties for VoiceAssist

    • getVoiceAssistIcon

      public static FormItemIcon getVoiceAssistIcon(FormItemIcon properties)
      Returns a FormItemIcon properties object configured for VoiceAssist value-dictation. The icon appears inline on the right side of a text field when focused, and clicking it toggles voice recording on and off.

      This is the same icon configuration used internally when FormItem.showVoiceAssistIcon is enabled. Use this method to retrieve the config for manual inclusion in a custom item's FormItem.icons array.

      The returned object is a copy of voiceAssistIconDefaults, so customizations made to the defaults are reflected in all subsequently created icons.

      Parameters:
      properties - additional properties to apply to the icon, overriding defaults
      Returns:
      icon properties for VoiceAssist

    • recordingProgress

      public static void recordingProgress(String text)
      Event fired with interim text-results as the user speaks.
      Parameters:
      text - the latest text-results for an on-going recording

    • setActive

      public static void setActive(boolean active)
      Sets whether VoiceAssist is active. When active, the dictation methods (startDictatingValue(), startDictatingCommand()) become operational, subject to canDictateValues and canDictateCommands. Voice-assist icons appear on applicable FormItems if canDictateValues is true. When set to false, any in-progress recording is stopped and icons are hidden.

      On the first call with true, Browser.checkSpeechRecognition() runs a brief probe to verify mic access and speech-service connectivity. If the probe fails, VoiceAssist shows an explanatory message and does not become active. Subsequent calls skip the probe and use the cached result.

      If enable() has not yet been called, this method calls it automatically.

      On non-mobile devices, this method is called internally when the user triple-taps the speech-key (toggling the active state). On handset and tablet devices, call it directly from a button or other UI element.

      Parameters:
      active - true to activate, false to deactivate
      See Also:

    • startDictatingCommand

      public static void startDictatingCommand()
      Begins command-dictation. VoiceAssist locates a target component by walking up the parent chain from the currently focused widget, looking for one that supports voice commands (see supportsVoiceCommands()). The user's speech is transcribed and forwarded to the target for execution.

      Recording stops automatically after a period of silence (see autoStopDelay), or can be stopped explicitly via stopDictatingCommand(). The user can also say a cancel phrase to discard the transcription.

      Has no effect if VoiceAssist is not active, if canDictateCommands is false, or if a recording is already in progress.

      See Also:

    • startDictatingValue

      public static void startDictatingValue()
      Begins value-dictation for the currently focused FormItem. VoiceAssist locates the focused item via EventHandler; if the focused item supports value-dictation (currently TextItem and TextAreaItem), the user's speech is transcribed and applied as the item's value.

      Recording stops automatically after a period of silence (see autoStopDelay), or can be stopped explicitly via stopDictatingValue(). The user can also say a cancel phrase to discard the transcription.

      Has no effect if VoiceAssist is not active, if canDictateValues is false, if no focused item supports value-dictation, or if a recording is already in progress.

      See Also:

    • stopDictatingCommand

      public static void stopDictatingCommand()
      Stops an ongoing command-dictation session normally, forwarding the transcribed text to the target component for execution. Has no effect if command-dictation is not currently in progress.
      See Also:

    • stopDictatingValue

      public static void stopDictatingValue()
      Stops an ongoing value-dictation session normally, applying the transcribed text to the target FormItem. Has no effect if value-dictation is not currently in progress.
      See Also:

    • stopRecording

      public static boolean stopRecording()
      Stops any ongoing recording session (value or command) normally, applying the transcribed text. For value-dictation, the text is set as the item's value; for command-dictation, the text is forwarded to the target component for execution.
      Returns:
      true if a recording was stopped, false if no recording was in progress