API reference
@speechineer/js
Speechineer for JavaScript — framework-free. Create the client once
(createClient), then create a session for what you want to do:
client.speechToForm(options) to fill a form by voice, client.textToForm(options)
to fill it from text. Subscribe to the session's state and render from it; drive
it with start / stop / end (or extract). Nothing here depends on a UI
framework — the React hooks and the Angular functions are thin wrappers over exactly
these sessions.
Every session reports the same SessionState: the lifecycle, the id, the last
error, the latest values, the transcript, isListening, and one entry per
connection. The client, the form definition, the callbacks, and the state types are
shared by every package and documented once in the Core reference.
Setup
The client: where Speechineer is and who is calling. Create it once; every session starts from it.
SpeechineerClient
Your connection to Speechineer. Create one with createClient and keep it for the lifetime of your app; every session starts from it.
Methods
speechToForm()
ts
speechToForm(options): SpeechToFormSession;Fill a form by voice. Returns the session; call start() on it when the user is
ready to speak. In React and Angular use useSpeechToForm / injectSpeechToForm
instead — they take the same options and manage the session for you.
Parameters
| Parameter | Type |
|---|---|
options | SpeechToFormOptions |
Returns
textToForm()
ts
textToForm(options): TextToFormSession;Extract field values from text — no microphone involved. Returns the session;
call extract(text) as often as you like. In React and Angular use
useTextToForm / injectTextToForm.
Parameters
| Parameter | Type |
|---|---|
options | TextToFormOptions |
Returns
Properties
| Property | Type | Description |
|---|---|---|
baseUrl | string | The API root this client talks to (no trailing slash). |
uiLanguage? | "en" | "de" | The language people are shown messages in, as the app asked for it — undefined when it did not. Deliberately not defaulted here. It travels to Speechineer as the session's language, and sending nothing is meaningful: Speechineer then negotiates from the browser's Accept-Language, which is a better answer than any guess this SDK could make (the header can say de-CH,de;q=0.9 while navigator.language says en-US). A session overrides it with its own uiLanguage. The SDK's own handful of messages still need a concrete language even when this is undefined — see negotiateSdkLanguage, which is the fallback for those only. |
createClient()
ts
function createClient(options?): SpeechineerClient;Create the client once, at app startup, and create every session from it.
Parameters
| Parameter | Type |
|---|---|
options | ClientOptions |
Returns
Example
ts
import { createClient } from "@speechineer/js";
// Development — an unsigned workspace key + who the end user is:
const speechineer = createClient({ apiKey: "spnr_live_…", account: { key: user.id } });
// Production — your server signs a short-lived token per user:
const speechineer = createClient({ token: () => fetch("/api/speechineer-token").then((r) => r.text()) });Capability: Speech to form
Fill a form by voice: values stream into values (and onFieldValue) as the user
speaks; add transcript: true to also receive the spoken text.
SpeechToFormOptions
What you pass to start filling a form by voice. The same options work in every framework; only the function that takes them differs.
Extends
SessionCallbacks.FormValueCallbacks.TranscriptCallbacks
Properties
| Property | Type | Description |
|---|---|---|
onSessionStart? | (sessionId) => void | Fires once, as soon as the session exists and work can begin. Receives the session id — keep it if you want to correlate it with your own logs. |
onStateChange? | (state) => void | The session state changed — its lifecycle, its id, a value, the transcript, an error, or the status of one of its connections. Receives the whole new state; render from it. |
onEvent? | (event) => void | Everything Speechineer reports for this session, at every level, failures included. One stream for logging or a live status display. event.level tells you what you have: 'error' means the session is over, and the other three are advisory. If you only want one level, take the matching hook below instead. |
onError? | (error) => void | Something failed in a way you should handle: a rejected request, a denied microphone permission, a lost connection, or a failure Speechineer reported while the session ran. Branch on error.code for the exact cause, or on the error's class (SpeechineerQuotaError, SpeechineerRuntimeError, …) to handle a whole family at once. Fires once per failure, so one rejected request reporting several problems calls this several times — the same list you can read as errors in the session state. |
onWarning? | (notice) => void | Something did not go as asked, but the session carried on — a setting Speechineer could not honour, a connection it refused, a component that had to retry. Worth surfacing or logging; never fatal. |
onInfo? | (notice) => void | A step worth reporting — a phase of the work starting or finishing. |
onDebug? | (notice) => void | Trace-level detail, for diagnosing an integration. Only arrives if the session is running at debug; otherwise Speechineer never sends it, so this stays silent rather than being filtered here. |
onFieldValue? | (fieldId, value) => void | One recognized field value. Called repeatedly while the user speaks, and more than once for the same fieldId when a value is refined — always apply the latest. fieldId is the id you gave the field; value is passed through as received, so cast or validate it the way your form expects. |
onTranscript? | (text) => void | The transcript so far — the full accumulated text, not just the newest words, so you can render it directly without stitching updates together. |
form | FormDefinition | Which form to fill: the one configured in Speechineer, or one defined right here. |
spokenLanguage? | string | The language the user will speak (for example 'en', 'de'). Detected automatically when omitted; set it when you already know, for slightly faster and more reliable recognition. |
transcript? | boolean | Also stream the spoken text: transcript in the state (and onTranscript) fills while the user speaks. Fixed for the session — change it by creating a new one. |
initialValues? | Record<string, unknown> | Values you already captured, keyed by field id — for example when a user resumes a form that was partly filled in earlier. They appear in values immediately and Speechineer continues from them. |
account? | Account | The end user this session is for, when it differs from the client's default account. Ignored when the client authenticates with a signed token — the token carries the account. |
uiLanguage? | "en" | "de" | The language to show this session's messages in, when it differs from the client's uiLanguage. It travels with the session, so every userMessage arrives already translated. Setting it again later — on start() after a stop, which re-seeds the session — switches the language from that point on; leaving it unset leaves the session in whatever language it was already running in. |
SpeechToFormSession
A speech-to-form session: the controls plus the observable state. Field values
and the transcript live in the state (values, transcript) and also reach your
callbacks as they arrive.
Properties
| Property | Type | Description |
|---|---|---|
start | () => Promise<void> | Start listening. Asks for microphone permission the first time, prepares the session, and begins sending audio. Safe to call again after stop() to continue in the same session. Rejects when the session could not be started, with the same SpeechineerError that reaches onError and state.error. Handle the promise — await it, or attach a .catch() — so a click handler leaves no unhandled rejection behind. |
stop | () => void | Pause listening. Values already being recognized still arrive, so late updates after this call are expected — keep applying them. |
end | () => Promise<void> | Finish the session and release everything: the microphone, the connections, and the session itself. start() afterwards begins a new one. values return to initialValues. Rejects when Speechineer could not be told the session is over. Everything local has already been released by then, so a cleanup path — an unmount, a reset — may catch and ignore it; what it must not do is leave the rejection unhandled. |
dispose | () => void | Release the microphone and the connections without finishing the session (leaving the page). The React and Angular bindings call this for you when the component goes away. |
getState | () => SessionState | The current session state. |
subscribe | (listener) => () => void | Be told about every state change; returns the unsubscribe function. |
setOptions | (next) => void | Swap the options the session reads its callbacks from — the framework bindings use it to keep the latest closures. transcript and form.source stay with the session; the rest of form is read when the next session starts. |
Capability: Text to form
No recording at all — turn text the user typed or pasted into field values, as often as you like.
TextToFormOptions
What you pass to extract field values from text. The same options work in every framework; only the function that takes them differs.
Extends
SessionCallbacks.FormValueCallbacks
Properties
| Property | Type | Description |
|---|---|---|
onSessionStart? | (sessionId) => void | Fires once, as soon as the session exists and work can begin. Receives the session id — keep it if you want to correlate it with your own logs. |
onStateChange? | (state) => void | The session state changed — its lifecycle, its id, a value, the transcript, an error, or the status of one of its connections. Receives the whole new state; render from it. |
onEvent? | (event) => void | Everything Speechineer reports for this session, at every level, failures included. One stream for logging or a live status display. event.level tells you what you have: 'error' means the session is over, and the other three are advisory. If you only want one level, take the matching hook below instead. |
onError? | (error) => void | Something failed in a way you should handle: a rejected request, a denied microphone permission, a lost connection, or a failure Speechineer reported while the session ran. Branch on error.code for the exact cause, or on the error's class (SpeechineerQuotaError, SpeechineerRuntimeError, …) to handle a whole family at once. Fires once per failure, so one rejected request reporting several problems calls this several times — the same list you can read as errors in the session state. |
onWarning? | (notice) => void | Something did not go as asked, but the session carried on — a setting Speechineer could not honour, a connection it refused, a component that had to retry. Worth surfacing or logging; never fatal. |
onInfo? | (notice) => void | A step worth reporting — a phase of the work starting or finishing. |
onDebug? | (notice) => void | Trace-level detail, for diagnosing an integration. Only arrives if the session is running at debug; otherwise Speechineer never sends it, so this stays silent rather than being filtered here. |
onFieldValue? | (fieldId, value) => void | One recognized field value. Called repeatedly while the user speaks, and more than once for the same fieldId when a value is refined — always apply the latest. fieldId is the id you gave the field; value is passed through as received, so cast or validate it the way your form expects. |
form | FormDefinition | Which form to fill: the one configured in Speechineer, or one defined right here. |
initialValues? | Record<string, unknown> | Values you already captured, keyed by field id. They appear in values immediately and Speechineer treats them as the baseline for the next extraction. |
account? | Account | The end user this session is for, when it differs from the client's default account. Ignored when the client authenticates with a signed token. |
uiLanguage? | "en" | "de" | The language to show this session's messages in, when it differs from the client's uiLanguage. It travels with the session, so every userMessage arrives already translated. Setting it again later switches the language from that point on; leaving it unset leaves the session in whatever language it was already running in. |
TextToFormSession
A text-to-form session: call extract as often as you like; every result is
merged into values (and reaches onFieldValue).
Properties
| Property | Type | Description |
|---|---|---|
start | () => Promise<void> | Open the session ahead of time. Optional — extract opens it on first use; call start() yourself to pay the connection cost before the user's first text. Rejects when the session could not be started, with the same SpeechineerError that reaches onError and state.error. Handle the promise — await it, or attach a .catch() — so a click handler leaves no unhandled rejection behind. |
extract | (text) => Promise<Readonly<Record<string, unknown>>> | Extract field values from the given text. Resolves with the values recognized in this call, keyed by field id; the same values are merged into values. Rejects with a SpeechineerError when the extraction fails — the same error also reaches onError and state.error. |
end | () => Promise<void> | Finish the session and release everything. values return to initialValues. Rejects when Speechineer could not be told the session is over. Everything local has already been released by then, so a cleanup path — an unmount, a reset — may catch and ignore it; what it must not do is leave the rejection unhandled. |
dispose | () => void | Release the connection without finishing the session (leaving the page). The React and Angular bindings call this for you when the component goes away. |
getState | () => SessionState | The current session state. |
subscribe | (listener) => () => void | Be told about every state change; returns the unsubscribe function. |
setOptions | (next) => void | Swap the options the session reads its callbacks from — the framework bindings use it to keep the latest closures. form.source stays with the session; the rest of form is read when the next session starts. |