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 a triple-tap 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.

Note: On `handset` and `tablet` devices, the keyboard gestures described above (triple-tap, double-tap, press-and-hold) are not available because virtual keyboards do not fire physical key events for modifier keys. Call `setActive()` from a button or other UI element, and use `startDictatingValue()` or `startDictatingCommand()` to initiate recording programmatically.

- ## 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 boolean`
  `getActive()`
  Returns whether VoiceAssist is currently `active` for end-user interaction.
  `static int`
  `getAutoStopDelay()`
  VoiceAssist will stop recording automatically if the user stops speaking for this length of time.
  `static String[]`
  `getCancelPhrases()`
  Returns the current list of `cancel phrases`.
  `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 boolean`
  `getEnabled()`
  Returns whether VoiceAssist has been `enabled` by the application developer.
  `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 Img`
  `getVoiceAssistButton(Img properties)`
  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`
  `setActive(boolean active, String callback)`
  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`
  `setCancelPhrases(String[] cancelPhrases)`
  Sets the list of `cancel phrases` that will abort an ongoing recording when spoken.
  `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:
      - `setActive(boolean)`

  - ### 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:
      - `setActive(boolean)`
      - `Browser.checkSpeechRecognition()`

  - ### 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:
      - `setActive(boolean)`
      - `Browser.checkSpeechRecognition()`

  - ### getActive

    public static boolean getActive()
    Returns whether VoiceAssist is currently `active` for end-user interaction.
    Returns:
      true if VoiceAssist is active
    See Also:
      - `setActive(boolean)`

  - ### getCancelPhrases

    public static String[] getCancelPhrases()
    Returns the current list of `cancel phrases`.
    Returns:
      current cancel phrases
    See Also:
      - `com.smartgwt.client.util.VoiceAssist#cancelPhrases`

  - ### getEnabled

    public static boolean getEnabled()
    Returns whether VoiceAssist has been `enabled` by the application developer.
    Returns:
      true if VoiceAssist is enabled
    See Also:
      - `enable()`
      - `disable()`

  - ### 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 is not yet `active` when clicked, the button calls `setActive()` automatically. Note that `enable()` must have been called first, otherwise setActive() will log a warning and return without activating.

    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

  - ### getVoiceAssistButton

    public static Img getVoiceAssistButton(Img properties)
    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 is not yet `active` when clicked, the button calls `setActive()` automatically. Note that `enable()` must have been called first, otherwise setActive() will log a warning and return without activating.

    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.

    Parameters:
      `properties` - optional properties to apply to the returned Img widget, for example a title or ID
    Returns:
      a live widget wired for VoiceAssist recording

  - ### getVoiceAssistIcon

    public static FormItemIcon getVoiceAssistIcon()
    Returns a `FormItemIcon` properties object configured for VoiceAssist value-dictation. The returned object merges `voiceAssistIcon` defaults, then `voiceAssistIconProperties`, then any supplied `properties` argument, so all three customization levels are reflected.

    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.

    Returns:
      icon properties for VoiceAssist
    See Also:
      - `com.smartgwt.client.util.VoiceAssist#voiceAssistIcon`

  - ### getVoiceAssistIcon

    public static FormItemIcon getVoiceAssistIcon(FormItemIcon properties)
    Returns a `FormItemIcon` properties object configured for VoiceAssist value-dictation. The returned object merges `voiceAssistIcon` defaults, then `voiceAssistIconProperties`, then any supplied `properties` argument, so all three customization levels are reflected.

    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.

    Parameters:
      `properties` - additional properties to apply to the icon, overriding both defaults and properties
    Returns:
      icon properties for VoiceAssist
    See Also:
      - `com.smartgwt.client.util.VoiceAssist#voiceAssistIcon`

  - ### 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.

    `enable()` must be called before this method can activate VoiceAssist. If `enable()` has not been called, this method logs a warning and returns without activating.

    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:
      - `enable()`

  - ### setActive

    public static void setActive(boolean active, String callback)
    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.

    `enable()` must be called before this method can activate VoiceAssist. If `enable()` has not been called, this method logs a warning and returns without activating.

    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
      `callback` - optional callback fired when the activation or deactivation is complete. Because the first activation involves an asynchronous speech-recognition probe, callers that need to know when VoiceAssist is actually ready should pass a callback rather than assuming synchronous completion. The callback receives a single boolean argument: true if VoiceAssist is now in the requested state, false if activation failed (mic denied, speech service blocked, etc.). See `Callback`
    See Also:
      - `enable()`

  - ### setCancelPhrases

    public static void setCancelPhrases(String[] cancelPhrases)
    Sets the list of `cancel phrases` that will abort an ongoing recording when spoken.
    Parameters:
      `cancelPhrases` - new cancel phrases
    See Also:
      - `com.smartgwt.client.util.VoiceAssist#cancelPhrases`

  - ### 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:
      - `stopDictatingCommand()`
      - `com.smartgwt.client.util.VoiceAssist#canDictateCommands`
      - `cancelRecording()`

  - ### 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:
      - `stopDictatingValue()`
      - `com.smartgwt.client.util.VoiceAssist#canDictateValues`
      - `cancelRecording()`

  - ### 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:
      - `startDictatingCommand()`
      - `cancelRecording()`

  - ### 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:
      - `startDictatingValue()`
      - `cancelRecording()`

  - ### 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