Speechly Web Components
Quick installation from CDN
Include the resources in your<head>
block:
Usage
Include the following lines in your <body>
to enable turning listening on/off and showing the transcript:
Handling Speech Input
Listen for the broadcasted speechsegment messages to perform actions:Push-to-talk Button
Autonomous customElement for connecting to Speechly and controlling listening on/off.
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 classsize
- 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: gradientstop1fxgradientstop2
- Optional string (CSS color). Default: gradientstop2customtypography
- 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 startholdend
- 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 startinitialized
- 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 changingappid
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: DecoderState}
- Broadcasts decoder state changes. Refer to browser-client API doc for values.{type: "audiosourcestate", state: AudioSourceState}
- Broadcasts mic state changes. Refer to browser-client API doc 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.
Big Transcript
<big-transcript/>
is an overlay-style component for displaying real-time speech-to-text transcript.
It is intended to be placed as an overlay near top-left corner of the screen using BigTranscriptContainer
CSS class. It is momentarily displayed and automatically hidden after the end of voice input.
Attributes
placement
- Optional "top" turns on internal placement without BigTranscriptContainer CSS classhoffset
- Optional CSS string. Horizontal distance from viewport edge. Only effective when using placement.voffset
- Optional CSS string. Vertical distance from viewport edge. Only effective when using placement.fontsize
- Optional CSS string for text size. Default: "1.5rem"color
- Optional string (CSS color) for text. Default: "#ffffff"highlightcolor
- Optional string (CSS color) for entity highlighting, vu meter and acknowledged icon. Default: "#15e8b5"backgroundcolor
- Optional string (CSS color) for hint text background. "none" for no background. Default: "#202020"marginbottom
- Optional string (CSS dimension). Dynamic margin added when element is visible. Default: "0rem"formattext
- Optional "true" | "false". If true, transcript is formatted with detected entities, e.g. numbers. Default: "true"demomode
- Optional "true" | "false". If true, transitions are slowed down for better readablility. Default: "false"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.
Properties
speechsegment(segment: Segment)
- Function. Call whenever a new segment update is availablespeechstate(state: ClientState)
- Function. Call whenever ClientState changes. Needed to show/hide element.speechhandled(success: boolean)
- Function. Optionally call on segment.isFinal to show confirmation that speech was processed. An indication will be shown with big-transcript.
Events emitted
visibilitychanged
- Called when visibility changes
Window messages listened
{type: "speechstate", state: ClientState}
- Required. Needed to show/hide element. This message is automatically emitted by push-to-talk-button.{type: "speechsegment", segment: Segment}
- Required. Updates transcript content in component. This message is automatically emitted by push-to-talk-button.{type: "speechhandled", success: boolean}
- Optional. Shows an indication to the user that the voice command was successfully understood by the app. Use window.postMessage to send it on segment.isFinal.
Holdable Button
Autonomous customElement that displays a stateless, holdable button with an icon and emits events on press.Installation
Attributes
icon
- Defines the appearance and behaviour of the button. Accepts serialized enums of ClientState (from browser-client).capturekey
- Optional string (of length 1). Defines a keyboard hotkey that with control listening on/off. Default: undefined. Recommendation: Space (" ")size
- Optional string (CSS). Defines the button frame width and height. Default: "6rem"gradientstop1
- Optional string (CSS color). Default: "#15e8b5"gradientstop2
- Optional string (CSS color). Default: "#4fa1f9"fxgradientstop1
- Optional string (CSS color). Default: gradientstop1fxgradientstop2
- Optional string (CSS color). Default: gradientstop2
Properties
onholdstart
- Callback function slot for hold start.onholdend
- Callback function slot for hold end. Params: timeMs (number) contains hold time in ms.isbuttonpressed()
- Returns true if button is currently held pressed.
Events emitted
holdstart
- CustomEvent triggered upon hold startholdend
- CustomEvent triggered upon hold end. event.detail.timeMs contains hold time in ms.
Browser-UI Playground Log
Try it out! Hold the button and talk. You can also try holding the hot key (SPACE) to activate listening.
The listening hot key is disabled if an element like input has focus: