@speechineer/js

The configuration and data types every Speechineer package shares. Whichever package you install, these are the same: how you configure the client, how you describe the form to fill, the callbacks that deliver values and progress, the errors and events that report problems, and the state every session reports.

The package for your framework documents its own functions; everything those functions' options are built from is described here, once.

Setup

Create the client once, at app startup, with your credentials — every session starts from it. Without a baseUrl it talks to the production Speechineer API.

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

Returns

SpeechToFormSession

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

Returns

TextToFormSession

Properties

ClientOptions

How the SDK reaches Speechineer and on whose behalf. Pass it once to createClient (or to the React provider / Angular provideSpeechineer).

Fill in one of the two credential styles:

• apiKey (+ account) — for an Unsigned API key. The SDK builds the token for you. Convenient for development, but the key is readable in your frontend.
• token — for a Signed API key. Your server signs a short-lived token per user and you hand it over (a string, or a function that fetches one); the SDK forwards it untouched, because signing requires a private key that must never reach the browser. Use this in production.

Properties

DEFAULT_BASE_URL

const DEFAULT_BASE_URL: "https://ai.speechineer.com/api" = 'https://ai.speechineer.com/api';

Where the SDK sends its requests unless createClient({ baseUrl }) says otherwise — the production Speechineer API.

createClient()

function createClient(options?): SpeechineerClient;

Create the client once, at app startup, and create every session from it.

Parameters

Returns

SpeechineerClient

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()) });

Authentication

Who is calling: your workspace's API key plus an identifier for the end user, or a token your server signed (a string, or a function that fetches a fresh one).

Account

The end user a session is for. Usage and per-account limits are tracked against it, so avoid one shared value for everybody.

Properties

TokenProvider

type TokenProvider = () => string | Promise<string>;

Returns a token your server signed for the current user — called every time a session is created or resumed, so a fresh, short-lived token is always used.

Returns

string | Promise<string>

Forms

Which form to fill and where its definition lives: configured in Speechineer (a workspace form — your code names it) or defined in your code (an inline form — fields, prompts, and model configurations ship with the call).

FormIdentity

The identity every form carries, whichever side defines it.

Extended by

• InlineForm
• WorkspaceForm

Properties

WorkspaceForm

A form configured in Speechineer. Your code names it, and the fields, prompts and models come from your workspace — change them there without shipping a release. Individual fields can be marked in your workspace as set by code, and those arrive through fieldConfigs.

Extends

• FormIdentity

Properties

Prompts

The prompts an inline form supplies, one per slot: how to transcribe, and how to extract the field values. Each is plain-language instruction text. Omit a slot to use the default.

Properties

Models

The model configurations an inline form pins, one per slot, by the keys you gave them in your workspace. Omit a slot to use the workspace default.

Properties

InlineForm

A form defined in your code: you declare the fields to extract (build them with FormField) and, optionally, the prompts and model configurations to use. Speechineer records it under key / version in your workspace.

Extends

• FormIdentity

Properties

FormDefinition

type FormDefinition = WorkspaceForm | InlineForm;

Where the form comes from: the one configured in Speechineer (source: 'workspace') or the one your code defines (source: 'inline'). Every capability that fills a form takes one of these as form.

Fields

What to extract and how to describe it. Build each field of an inline form with FormField; the prompt is the instruction Speechineer follows for that field.

OptionsFieldConfig

The allowed options of a choice field (select / multiselect).

Properties

RangeFieldConfig

The [min, max] range of a slider field.

Properties

FieldSpec

One field to extract. Build these with FormField rather than by hand — the factory picks the right type and validates the options for you.

Properties

FieldFactory

The field factory surface. Every helper returns a ready FieldSpec.

Methods

text()

text(id, prompt): FieldSpec;

Free-form text.

Parameters

Returns

FieldSpec

textarea()

textarea(id, prompt): FieldSpec;

Multi-line free-form text; same value semantics as text.

Parameters

Returns

FieldSpec

email()

email(id, prompt): FieldSpec;

An email address.

Parameters

Returns

FieldSpec

phone()

phone(id, prompt): FieldSpec;

A phone number.

Parameters

Returns

FieldSpec

url()

url(id, prompt): FieldSpec;

A URL.

Parameters

Returns

FieldSpec

integer()

integer(id, prompt): FieldSpec;

A whole number.

Parameters

Returns

FieldSpec

float()

float(id, prompt): FieldSpec;

A decimal number.

Parameters

Returns

FieldSpec

checkbox()

checkbox(id, prompt): FieldSpec;

A yes/no value.

Parameters

Returns

FieldSpec

date()

date(id, prompt): FieldSpec;

A calendar date.

Parameters

Returns

FieldSpec

time()

time(id, prompt): FieldSpec;

A time of day.

Parameters

Returns

FieldSpec

datetime()

datetime(id, prompt): FieldSpec;

A date with a time.

Parameters

Returns

FieldSpec

slider()

slider(
   id, 
   prompt, 
   range): FieldSpec;

Ranged numeric field; range is [min, max] with min < max.

Parameters

Returns

FieldSpec

select()

select(
   id, 
   prompt, 
   options, 
   appendOptionsToPrompt?): FieldSpec;

Single-choice; options must be non-empty.

Parameters

Returns

FieldSpec

multiselect()

multiselect(
   id, 
   prompt, 
   options, 
   appendOptionsToPrompt?): FieldSpec;

Multi-choice; options must be non-empty.

Parameters

Returns

FieldSpec

FieldConfigFactory

The factory surface for configuring a workspace form's code-defined fields. Only the three types that take a configuration appear here — the rest have nothing for code to supply.

Methods

slider()

slider(id, range): FieldSpec;

Ranged numeric field; range is [min, max] with min < max.

Parameters

Returns

FieldSpec

select()

select(
   id, 
   options, 
   appendOptionsToPrompt?): FieldSpec;

Single-choice; options must be non-empty.

Parameters

Returns

FieldSpec

multiselect()

multiselect(
   id, 
   options, 
   appendOptionsToPrompt?): FieldSpec;

Multi-choice; options must be non-empty.

Parameters

Returns

FieldSpec

FieldConfig

type FieldConfig = 
  | OptionsFieldConfig
  | RangeFieldConfig;

The extra configuration a field type may carry: the allowed options of a choice field, or the range of a slider.

FieldType

type FieldType = 
  | "text"
  | "textarea"
  | "email"
  | "phone"
  | "url"
  | "integer"
  | "float"
  | "slider"
  | "checkbox"
  | "select"
  | "multiselect"
  | "date"
  | "time"
  | "datetime"
  | "template";

FIELD_TYPES

const FIELD_TYPES: readonly ["text", "textarea", "email", "phone", "url", "integer", "float", "slider", "checkbox", "select", "multiselect", "date", "time", "datetime"];

The field types you can declare, in presentation order. Use it to build a type picker without redeclaring the list.

FormField

const FormField: FieldFactory;

Build the fields of an inline form. A factory object (no new, tree-shakeable) producing FieldSpecs, with light runtime validation for the config-bearing types.

Example

import { FormField } from "@speechineer/js"; // also exported by @speechineer/react and @speechineer/angular

const fields = [
  FormField.text("patientName", "Extract the patient full name"),
  FormField.integer("age", "Extract the age in years"),
  FormField.select("species", "Extract the species", ["Canine", "Feline", "Equine"]),
  FormField.slider("painLevel", "Extract the pain level", [0, 10]),
];

FormFieldConfig

const FormFieldConfig: FieldConfigFactory;

Configure the fields your workspace form marks as set by your code — a choice field whose options come from your own data, for example. Pass the results as the form's fields.

Same validation as FormField, without the prompt: what to extract is already written in your workspace, so only the field id and the configuration come from here.

Example

import { FormFieldConfig } from "@speechineer/js"; // also exported by @speechineer/react and @speechineer/angular

const form = {
  source: "workspace",
  key: "intake",
  version: "1",
  language: "en",
  fields: [FormFieldConfig.select("species", await loadSpeciesFromMyDatabase())],
} as const;

Callbacks

Optional hooks for imperative integrations. Everything they report — values, the transcript, events, errors — is also in the session state.

SessionCallbacks

The callbacks every session accepts. All of them are optional: a session runs without any, and you add the ones your integration reacts to. Everything they report is also visible in the session state, so a UI that renders from the state needs none of them.

Properties

FormValueCallbacks

Field-value callbacks, added by every capability that fills a form. Optional — the latest value of every field is always available as values in the session state; use the callback to push values into a form library imperatively.

Properties

TranscriptCallbacks

Transcript callbacks, added by every capability that returns the spoken text. Optional — the transcript so far is always available as transcript in the session state.

Properties

Events and errors

What you receive when something noteworthy or fatal happens during a session: a typed error with a stable code, and the stream of status events.

SpeechineerClientError

Your app's own mistake, caught before anything was sent — missing credentials, an action before start(), or a microphone the browser would not give up.

Extends

• SpeechineerError

Properties

SpeechineerAuthError

The credentials were missing, malformed, expired, or rejected.

Extends

• SpeechineerError

Properties

SpeechineerQuotaError

A usage allowance is spent. meta carries the ceiling that bound and how much of it was used — see QuotaMeta.

Extends

• SpeechineerError

Properties

SpeechineerAccessError

The credentials are valid but not allowed to do this.

Extends

• SpeechineerError

Properties

SpeechineerNotFoundError

Something named in the request does not exist — a form, a version, or a session whose id answers to nothing because it was never created or has long since ended and been swept.

Extends

• SpeechineerError

Properties

SpeechineerConflictError

The request conflicts with the current state — for example an action whose prerequisite has not happened yet.

Extends

• SpeechineerError

Properties

SpeechineerValidationError

The request was not acceptable. When several things are wrong at once you get one error per cause in state.errors, so a rejected form tells you everything in one round trip.

Extends

• SpeechineerError

Properties

SpeechineerMethodError

The path is right but the HTTP method is not one it accepts. A mistake in how the request was built, not in what it asked for.

Extends

• SpeechineerError

Properties

SpeechineerNotAcceptableError

Nothing that can be returned matches the Accept header the request sent.

Extends

• SpeechineerError

Properties

SpeechineerTooLargeError

The request body is larger than the endpoint will read. Send less, or send it in parts.

Extends

• SpeechineerError

Properties

SpeechineerUnsupportedMediaError

The body's content type is not one the endpoint reads. The body itself may be perfectly well-formed — it is the type that is not supported.

Extends

• SpeechineerError

Properties

SpeechineerRateLimitError

Too many requests. Slow down and retry.

Extends

• SpeechineerError

Properties

SpeechineerRuntimeError

A running session stopped because something failed — transcription or field extraction could not be restarted. The session is over; offer the user a fresh start.

Extends

• SpeechineerError

Properties

SpeechineerServiceError

Speechineer could not handle the request, for a reason that is not your app's doing. Retrying the same request may work.

Extends

• SpeechineerError

Properties

SpeechineerUpstreamError

A service Speechineer depends on answered with something unusable. Retrying the same request the same way is unlikely to help.

Extends

• SpeechineerError

Properties

SpeechineerUnavailableError

Speechineer is temporarily unreachable. Nothing is wrong with your request — retry later.

Extends

• SpeechineerError

Properties

SpeechineerTimeoutError

The request took too long to complete. Retrying is reasonable.

Extends

• SpeechineerError

Properties

QuotaMeta

The meta a SpeechineerQuotaError carries: the allowance that bound, and how much of it was used.

The amounts are decimal strings, not numbers — usage is metered in fractional units and a JSON number would round them.

Properties

SpeechineerEvent

Anything Speechineer reports, at any level — a failure, a warning, a progress note.

This is what onEvent receives, so it is the one shape worth learning. level is the terminality: 'error' means the session is over and nothing else does, so you never have to inspect a code to find out whether you can keep going.

Extended by

• SessionNotice

Properties

SessionNotice

One thing that happened while the session kept running — delivered to onWarning, onInfo or onDebug, and to onEvent along with everything else.

Notices are advisory by definition: a connection re-establishing itself, a setting the service could not honour as asked, a stage of the work finishing. Anything that ends the session is not a notice — it arrives as a SpeechineerError through onError and state.errors.

Identical to SpeechineerEvent but for the narrower level; it adds no fields, because the event is the whole report.

Extends

• SpeechineerEvent

Properties

SpeechineerErrorCode

type SpeechineerErrorCode = 
  | keyof typeof SDK_ERRORS
  | string & {
};

A stable identifier for what went wrong.

The union lists what this version knows about but stays open on purpose: Speechineer can name a new failure without every app upgrading first, so the type must not claim the list is closed.

EventLevel

type EventLevel = LevelSdk;

How severe something is — and, for error, that the session is over.

There is no critical: nothing ever emitted one, and it named a severity no handler treated differently from error.

SDK_ERROR_CODES

const SDK_ERROR_CODES: readonly (
  | "NO_AUTH"
  | "NO_ACCOUNT"
  | "NO_CLIENT"
  | "NO_SESSION"
  | "MICROPHONE_DENIED"
  | "MICROPHONE_UNAVAILABLE"
  | "AUDIO_UNSUPPORTED"
  | "NETWORK"
  | "UNKNOWN"
  | "REQUEST_FAILED")[];

The codes the SDK names itself, as opposed to the ones Speechineer sends.

Useful for telling the two apart — "did this request even leave the browser?" is a different question from "what did Speechineer say?", and it changes what you do about it. A code in this list means nothing was sent: a missing credential, a denied microphone, a browser that cannot record. The one exception is REQUEST_FAILED, which means Speechineer was reached but answered in a shape that carried no code of its own.

Example

import { SDK_ERROR_CODES } from "@speechineer/js";

onError: (error) => {
  const isLocal = (SDK_ERROR_CODES as readonly string[]).includes(error.code);
  if (isLocal) showSetupHint(error);
  else reportToSupport(error.code, session.getState().requestId);
};

SpeechineerError

Something Speechineer could not do. The session is over.

Branch on code — it is stable — or catch a subclass to handle a whole category at once (SpeechineerQuotaError covers every way an allowance can run out).

Two messages, for two readers. userMessage is written for the person using your app and arrives already translated into the session's language — show that one. message is written for you: it says what to do about the failure, and belongs in your logs rather than on screen.

It is also a SpeechineerEvent with level: 'error', which is why onEvent can receive failures and notices alike.

Extends

• Error

Extended by

• SpeechineerAccessError
• SpeechineerAuthError
• SpeechineerClientError
• SpeechineerConflictError
• SpeechineerMethodError
• SpeechineerNotAcceptableError
• SpeechineerNotFoundError
• SpeechineerQuotaError
• SpeechineerRateLimitError
• SpeechineerRuntimeError
• SpeechineerServiceError
• SpeechineerTimeoutError
• SpeechineerTooLargeError
• SpeechineerUnavailableError
• SpeechineerUnsupportedMediaError
• SpeechineerUpstreamError
• SpeechineerValidationError

Implements

• SpeechineerEvent

Constructors

Constructor

new SpeechineerError(options): SpeechineerError;

Parameters

Returns

SpeechineerError

Overrides

Error.constructor

Properties

level

readonly level: "error";

Always 'error': a failure is the terminal level, by definition.

Implementation of

SpeechineerEvent.level

type

readonly type: string;

The category. Prefer catching the matching subclass over comparing this yourself.

Implementation of

SpeechineerEvent.type

code

readonly code: string;

A stable identifier for what went wrong. Branch on this, not on a message.

Implementation of

SpeechineerEvent.code

userMessage

readonly userMessage: string;

For the person using your app, in the session's language. Show this one.

Implementation of

SpeechineerEvent.userMessage

meta

readonly meta: Record<string, unknown> | null;

Data belonging to this failure — the shape depends on code.

Implementation of

SpeechineerEvent.meta

cause?

readonly optional cause?: unknown;

The underlying failure, when there was one.

name

readonly name: string;

The class name — "SpeechineerQuotaError" and so on. Prefer code or a catch by class.

Overrides

Error.name

message

readonly message: string;

For you, in English: what went wrong and what to do about it. Log this one.

Implementation of

SpeechineerEvent.message

Overrides

Error.message

stack?

readonly optional stack?: string;

Where the failure was raised, when the browser provides it.

Overrides

Error.stack

Session state

What a running session reports about itself — its lifecycle, its id, the last error, the latest values, the transcript, whether it is listening, and whether each of its connections is open. The same shape in every framework: read it, subscribe to it, render from it.

ConnectionState

The state of one connection.

Properties

SessionState

Everything a session reports about itself. Read it with getState(), receive it through subscribe / onStateChange, or — in React and Angular — take it from the hook / inject result. Render your UI from it. The object is immutable — every change produces a new one — so it is safe to compare by reference.

Properties

SessionStatus

type SessionStatus = "idle" | "starting" | "active" | "recovering" | "ending" | "failed";

Where the session is in its life.

• idle — nothing started yet (or the session was ended).
• starting — the session is being created and its connection opened.
• active — the session exists; isListening and connections tell you what it is doing.
• recovering — the session vanished on the server and is being resumed.
• ending — end() is discarding the session.
• failed — the session is not usable: starting or recovering did not succeed, or a running session ended because something failed (a crash, a spent allowance). See errors; errors[0].code says which. start() may be called again.

ConnectionStatus

type ConnectionStatus = "closed" | "connecting" | "open" | "closing";

Whether one connection of the session is open. closing is reported by the microphone connection between stop() and the moment capture has fully wound down.

ConnectionKey

type ConnectionKey = "session" | "audio" | "results" | "transcript";

The connections a session may have. session is the main connection every session has — when it is lost, every other connection is closed as well. audio carries the microphone, results the recognized values, transcript the spoken text. A session only lists the connections its capability uses.

SessionConnections

type SessionConnections = {
  session: ConnectionState;
} & Readonly<Partial<Record<Exclude<ConnectionKey, "session">, ConnectionState>>>;

The connections of a session: session always, the others only when the capability uses them.

Type Declaration

Type Aliases

SdkLanguage

type SdkLanguage = typeof SDK_LANGUAGES[number];

A language the SDK can speak.

Variables

SDK_LANGUAGES

const SDK_LANGUAGES: readonly ["en", "de"];

The languages the SDK can render its own sentences in. The service translates its own.

DEFAULT_SDK_LANGUAGE

const DEFAULT_SDK_LANGUAGE: SdkLanguage = 'en';

The language used when nothing else answers — the same fallback the service ends on.