API-Referenz
@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()
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()
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). |
createClient()
function createClient(options?): SpeechineerClient;Create the client once, at app startup, and create every session from it.
Parameters
| Parameter | Type |
|---|---|
options | ClientOptions |
Returns
Example
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 | Every status event Speechineer emits for this session — progress, warnings, and failures alike. Use it for logging or a live status display. |
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. Read error.code to branch and error.recoverable to decide whether to offer a retry. |
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. |
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. |
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. |
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 | Every status event Speechineer emits for this session — progress, warnings, and failures alike. Use it for logging or a live status display. |
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. Read error.code to branch and error.recoverable to decide whether to offer a retry. |
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. |
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. |
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. |
end | () => Promise<void> | Finish the session and release everything. values return to initialValues. |
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. |