Push-To-Talk Button

Push-To-Talk Button is a holdable switch for controlling listening for speech. Pressing the button starts listening by calling startContext. Releasing it turns listening off by calling stopContext. Desktop users can control listening on/off with an optional keyboard hotkey, e.g. space.

You can toggle visibility and customise the appearance and the hint texts on the button.

Usage

<script type="text/javascript" src="https://unpkg.com/@speechly/browser-ui/core/push-to-talk-button.js"></script>

<push-to-talk-button
  appid="YOUR_APP_ID_FROM_SPEECHLY_DASHBOARD"
  placement="bottom"
  hide="false"
  capturekey=" "
  intro="Push to talk"
  size="80px" >
</push-to-talk-button>

Attributes

  • appid - Speechly App id to connect to.
  • projectid - Optional Speechly Project id to connect to. Allows changing App id on the fly within the same project.
  • loginurl - Optional alternative url to use for Speechly login.
  • apiurl - Optional alternative url for Speechly API.
  • capturekey - Optional string (of length 1). Defines a keyboard hotkey that with control listening on/off. Default: undefined. Recommendation: Space (" “)
  • poweron - Optional string “auto”|“true”|“false”. If “true”, first button press sends a “poweron” message instead of initializing Speechly. This allows displaying a welcome screen using Intro Popup or a custom implementation. “auto” setting tries to detect presence of Intro Popup in DOM and use poweron if found. Default: “auto”
  • hide - Optional “false” | “true”. Default: “false”

Attributes for styling

  • placement - Optional “bottom” turns on internal placement without PushToTalkContainer CSS class
  • size - Optional string (CSS). Defines the button frame width and height. Default: “88px”
  • voffset - Optional CSS string. Vertical distance from viewport edge. Only effective when using placement.
  • backgroundcolor - Optional string (CSS color) for button background. Default: “#ffffff”.
  • iconcolor - Optional string (CSS color) for button icon. Default: “#000000”.
  • gradientstop1 - Optional string (CSS color) for border color. Default: “#15e8b5”.
  • gradientstop2 - Optional string (CSS color) for border color. Default: “#4fa1f9”
  • fxgradientstop1 - Optional string (CSS color). Default: gradientstop1
  • fxgradientstop2 - Optional string (CSS color). Default: gradientstop2
  • customtypography - Optional “true” | “false”. True inherits css typography settings. Default: “false”
  • customcssurl - Optional string (url to .css file). Allows for further customization of component’s shadow root.

Attributes for tap and hold behaviour

  • taptotalktime - Optional time in milliseconds to listen after tap. Set to 0 to disable tap-to-talk. Default: “8000” (ms)
  • silencetohanguptime - Optional milliseconds of silence to listen before hangup. Only used in tap-to-talk mode. Default: “1000” (ms)
  • holdscale - Optional scale for button size when held down. Relative to size. Default: “1.35”.
  • borderscale - Optional scale for button size when held down. Relative to button radius. Default: “0.06”.
  • iconsize - Optional string (CSS dimension) for icon size. Relative to size. Default: “60%”.
  • fxsize - Optional string (CSS dimension) for button hold fx size. Relative to size. Default: “250%”.

Attributes for usage hints

  • intro - Optional string containing a short usage introduction. Displayed when the component is first displayed. Default: “Push to talk”. Set to "” to disable.
  • hint - Optional string containing a short usage hint. Displayed on a short tap. Default: “Push to talk”. Set to "" to disable.
  • showtime - Optional time in milliseconds. Visibility duration for intro and hint callouts. Default: “5000” (ms)
  • fontsize - Optional CSS string for hint text. Default: “1.2rem”
  • textcolor - Optional string (CSS color) for hint text. Default: “#ffffff”
  • hintbackgroundcolor - Optional string (CSS color) for hint text background. Default: “#202020” (attribute name changed from backgroundcolor)
  • hintxalign - Optional string (CSS percentage). Default: “50%”
  • hintwidth - Optional string (CSS dimension). Default: “auto”

Events emitted

  • holdstart - CustomEvent triggered upon hold start
  • holdend - CustomEvent triggered upon hold end. event.detail.timeMs contains hold time in ms.
  • speechsegment - CustomEvent triggered when speech-to-text segment changes. Segment available as the event.detail property.
  • starting - CustomEvent triggered on initialization start
  • initialized - CustomEvent triggered on initialization end. event.detail: {success: true | false, appId: string, state: ClientState.Connected|Failed|NoBrowserSupport|NoAudioConsent}
  • startcontext - CustomEvent triggered on just before starting listening. Allows changing appid to redirect audio to an alternative voice configuration.
  • stopcontext - CustomEvent triggered on just after stopping listening.

Window messages sent (postMessage)

  • {type: "speechsegment", segment: Segment} - Broadcasts new segment when an update is available
  • {type: "speechstate", state: ClientState} - Broadcasts state changes. Refer to browser-client documentation for values.
  • {type: "holdstart"} - Broadcasted upon hold start
  • {type: "holdend"} - Broadcasted upon hold end
  • {type: "poweron"} - Broadcasted on button initial button press when poweron=“true”

Window messages listened

  • {type: "showhint", hint: string} - Shows a custom hint using the call-out on the button.

Place <PushToTalkButton> component inside your <SpeechProvider> block. Please see Basic usage for a full app example.

import { PushToTalkButton } from "@speechly/react-ui";

...
<SpeechProvider appId="YOUR_APP_ID_FROM_SPEECHLY_DASHBOARD">
  <PushToTalkButton
    placement="bottom"
    hide="false"
    captureKey=" "
    intro="Push to talk"
    size="80px" >
  </PushToTalkButton>
</<SpeechProvider>
...

Properties

NameTypeDescription
placement?stringOptional “bottom” string turns on internal placement without any CSS positioning.
captureKey?stringKeyboard key to use for controlling the button. Passing e.g. (a spacebar) will mean that holding down the spacebar key will key the button pressed.
size?stringThe size of the button, as CSS (e.g. 5rem).
gradientStops?string[]Colours of the gradient around the button. Valid input is an array of two hex colour codes, e.g. ['#fff', '#000'].
hide?booleanOptional boolean. Default: false
intro?stringOptional string containing a short usage introduction. Displayed when the component is first displayed. Default: “Push to talk”. Set to "" to disable.
hint?stringOptional string containing a short usage hint. Displayed on a short tap. Default: “Push to talk”. Set to "" to disable.
fontSize?stringOptional CSS string for hint text. Default: “1.2rem”
showTime?numberOptional number in ms. Visibility duration for intro and hint callouts. Default: “5000” (ms)
textColor?stringOptional string (CSS color) for hint text. Default: “#ffffff”
backgroundColor?stringOptional string (CSS color) for hint text background. Default: “#202020”
powerOn?boolean | "auto"Optional boolean. Shows poweron state. If false, recording can immediately start but will first press will cause a system permission prompt. Default: false
voffset?stringOptional CSS string. Vertical distance from viewport edge. Only effective when using placement.
tapToTalkTime?numberOptional time in milliseconds to listen after tap. Set to 0 to disable tap-to-talk. Default: “8000” (ms)
silenceToHangupTime?numberOptional milliseconds of silence to listen before hangup. Only used in tap-to-talk mode. Default: “1000” (ms)

Button placement options

  • Place the button close to the bottom-center of the viewport (fixed) to indicate app-wide speech control. Use placement="bottom" for this option.
  • Place the button close to a group of components if speech input only controls a few input fields.
  • Place the button close to an input field if speech input only controls that component (e.g. text in a search box)

Last updated by Mathias Lindholm on January 26, 2022 at 11:45 +0200

Found an error on our documentation? Please file an issue or make a pull request