Speechly Web Components

Quick installation from CDN

Include the resources in your <head> block: <head> <script type="text/javascript" src="https://speechly.github.io/browser-ui/latest/push-to-talk-button.js"></script> <script type="text/javascript" src="https://speechly.github.io/browser-ui/latest/big-transcript.js"></script> <script type="text/javascript" src="https://speechly.github.io/browser-ui/latest/error-panel.js"></script> </head> These scripts add Speechly's components to the page's custom element registry to be used in HTML markup as shown below.

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: <script type="text/javascript"> window.addEventListener("message", (e) => { if (e.data.type === "speechsegment") { const segment = e.data.segment; // Handle speech segment and make tentative changes to app state console.log("speechsegment message:", segment); if (segment.isFinal) { // Handle speech segment and make permanent changes to app state // Optionally show confirmation window.postMessage({ type: "speechhandled", success: true }, "*"); } } }); </script>

Element <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.
poweron - Optional string "true" | "false". Shows poweron state. If false, recording can immediately start but will first press will cause a system permission prompt. Default: "false"
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"
hide - Optional "false" | "true". Default: "false"
placement - Optional "bottom" turns on internal placement without PushToTalkContainer CSS class
voffset - Optional CSS string. Vertical distance from viewport edge. Only effective when using placement.
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.
fontsize - Optional CSS string for hint text. Default: "1.2rem"
showtime - Optional time in milliseconds. Visibility duration for intro and hint callouts. Default: "5000" (ms)
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)
textcolor - Optional string (CSS color) for hint text. Default: "#ffffff"
backgroundcolor - Optional string (CSS color) for hint text background. Default: "#202020"
gradientstop1 - Optional string (CSS color). Default: "#15e8b5"
gradientstop2 - Optional string (CSS color). Default: "#4fa1f9"
loginurl - Optional alternative url to use for Speechly login.
apiurl - Optional alternative url for Speechly API.

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.details property.
starting - CustomEvent triggered on initialization start
initialized - CustomEvent triggered on initialization end. details: {success: true | false, appId: string, status: "Ready" | "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: "initialized", success: true | false, appId: string, status: "Ready" | "Failed" | "NoBrowserSupport" | "NoAudioConsent"} - Broadcasted on initialization end.

Element <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 class
hoffset - 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"

Properties

speechsegment(segment: Segment) - Function. Call whenever a new segment update is available
speechstate(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: "speechsegment", segment: Segment} - Required. Updates transcript content in component. This message is automatically emitted by push-to-talk-button.
{type: "speechstate", state: ClientState} - Required. Needed to show/hide element. 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.

Element <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) or SpeechState (from react-client). SpeechState strings are: "Idle" | "Connecting" | "Ready" | "Recording" | "Loading" | "Failed" | "NoBrowserSupport" | "NoAudioConsent".
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"

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 start
holdend - 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: