@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.

SessionEvent

One status event from a running session, delivered to onEvent. Events are informational — progress, warnings, and failures alike — and are useful for logging or a live status display. Failures also reach you as a typed SpeechineerError through onError, so you rarely need to branch on events yourself.

Properties

ErrorPhase

type ErrorPhase = "start" | "recover" | "connection" | "action" | "end" | "runtime";

When an error happened.

• start — while creating the session, opening its connections, or starting the microphone.
• recover — while re-establishing a session the service had dropped.
• connection — a connection failed while the session was running.
• action — a request you made (for example extract) was rejected.
• end — while finishing the session.
• runtime — the service stopped the session; it cannot continue and recoverable is false.

EventLevel

type EventLevel = LogVerbosity;

How important an event is — from debug chatter to critical failures. Filter your logging on it.

SpeechineerError

Something the SDK could not do. Branch on code — it is stable — and read message for a human-readable explanation. recoverable tells you whether calling start() again is worth a try (for example after a denied microphone permission, or a network hiccup); when it is false the session has stopped for good and you should offer the user a fresh start.

Codes you can expect: AUTH_REQUIRED, ACCOUNT_REQUIRED (client configuration), NETWORK, REQUEST_FAILED or a specific code returned by Speechineer (the request was rejected), NOT_FOUND (the session no longer exists), MICROPHONE_DENIED, MICROPHONE_UNAVAILABLE, AUDIO_UNSUPPORTED, NO_SESSION (an action before start), NO_CLIENT (framework wiring missing), and the runtime failure codes Speechineer reports while a session runs.

Extends

• Error

Constructors

Constructor

new SpeechineerError(message, options): SpeechineerError;

Parameters

Returns

SpeechineerError

Overrides

Error.constructor

Properties

code

readonly code: string;

A stable identifier for what went wrong — branch on this, not on message.

phase

readonly phase: ErrorPhase;

When it happened — see ErrorPhase.

recoverable

readonly recoverable: boolean;

Whether a new start() may succeed. false means the session has stopped for good.

detail

readonly detail: string | null;

Additional detail from Speechineer, when there is any.

cause?

readonly optional cause?: unknown;

The underlying error, when there was one.

name

name: string;

Inherited from

Error.name

message

message: string;

Inherited from

Error.message

stack?

optional stack?: string;

Inherited from

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 — starting or recovering threw; see error. 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