Dictum SDK Wiki

The complete client contract for Dictum.

Dictum is exposed to products as a widget and SDK contract. The internal endpoint remains transport: clients should integrate through SDK methods, widget attributes, and shared state/transcript events.

Headless SDK Widget UI

Install

Use the SDK for custom UI, or the widget for packaged UI

Package

npm install @dictum/sdk

Browser requirements

Secure context for microphone access.
User gesture before starting capture.
Permission handling for allow, deny, and dismissed prompts.
Fallback UI when audio capture is unavailable.

Architecture

Endpoint stays internal

The SDK is the product boundary. Workers still handle sessions, audio, STT, correction, usage, and provider routing, but apps should not build against those transport details.

Public contract	SDK methods, widget attributes, and SDK events.
Web UI	Use the packaged widget when Dictum should own the visible interface.
Headless web	Use the SDK client when your app owns controls, layout, and insertion.
Mobile/native	Use native audio capture while preserving the same event contract.
Internal transport	Workers manage sessions, audio forwarding, STT, usage, and optional correction.
Server profile	Provider keys, models, routing, correction prompts, and limits stay server-side.

Headless Web

Bring your own recorder UI

Use the headless client when your product already owns the button, form field, editor, waveform, or workflow state machine.

import { createDictumClient } from "@dictum/sdk";

const dictum = createDictumClient({
  projectKey: "pk_live_xxx",
  userRef: "user_123",
  language: "auto",
  correction: true
});

dictum.on("state", ({ value }) => setRecorderState(value));
dictum.on("partial", ({ text }) => renderDraft(text));
dictum.on("final", ({ transcript }) => insertTranscript(transcript));
dictum.on("done", ({ transcript }) => persistTranscript(transcript));
dictum.on("error", ({ code, message }) => showDictumError(code, message));

await dictum.prepare();
await dictum.listen();
await dictum.record();
await dictum.stop();

Widget UI

Use the packaged interface

Markup

<script src="https://cdn.bestwhisper.com/dictum-widget.js"></script>

<dictum-widget
  project-key="pk_live_xxx"
  user-ref="user_123"
  mode="compact"
  correction="true"
></dictum-widget>

DOM events

const widget = document.querySelector("dictum-widget");

widget.addEventListener("dictum:state", (event) => {
  console.log(event.detail.value);
});

widget.addEventListener("dictum:final", (event) => {
  console.log(event.detail.transcript);
});

Mobile

Native capture, same events

Mobile apps should use native audio capture instead of embedding the web widget by default. The app layer still receives the same state, partial, final, done, and error events.

const client = createNativeDictumClient({
  projectKey: "pk_live_xxx",
  userRef: "user_123",
  audio: nativeAudioAdapter
});

client.on("state", ({ value }) => setState(value));
client.on("partial", ({ text }) => setDraft(text));
client.on("final", ({ transcript }) => save(transcript));

Options

createDictumClient options

Option	Type	Default	Purpose
projectKey	string	required	Public project key used to identify the Dictum project.
userRef	string	recommended	Stable app-side user id. Do not send secrets or email if avoidable.
language	string	"auto"	Language hint for capture and transcript routing.
correction	boolean	project default	Enables the server-side correction profile when available.
mode	"push-to-talk" \| "toggle"	"toggle"	Client interaction mode for headless controls.
metadata	object	{}	Small JSON object for app context, audit, or workflow ids.
transport	object	default	Advanced override for platform-specific audio/session transport.

Methods

Lifecycle methods

prepare()	Ask for microphone permission and create local audio resources.
listen()	Open the microphone and wait for user speech intent.
record()	Capture audio and emit recording state.
pause()	Pause capture without destroying the session.
resume()	Resume capture on the same session.
stop()	Finalize capture and stream transcript events.
cancel()	Close capture and discard the current audio cycle.
destroy()	Remove listeners and release resources.

Events

Shared SDK event contract

Event	Payload	Use
state	{ value }	Lifecycle state changed.
partial	{ text, sequence }	Incremental transcript for live UI.
final	{ transcript, language, durationMs }	Final transcript for insertion.
done	{ transcript, usage }	Capture and post-processing completed.
error	{ code, message, retryable }	Failure that the app can render or log.

State	Meaning
idle	Client is ready and not using the microphone.
listening	Microphone is open and waiting for speech.
recording	Audio is being captured locally.
transcribing	Audio is being processed by Dictum workers.
editing	Optional correction is running.
done	The current cycle completed.
error	The current cycle failed or needs user action.

Errors

Error codes and app behavior

Code	Meaning	Expected handling
permission_denied	The browser or OS blocked microphone access.	Ask the user to grant microphone permission.
unsupported_audio	The platform cannot provide a supported audio stream.	Fall back to upload or text input.
session_conflict	Another active Dictum session exists for this user.	Close the old session or retry after completion.
network_error	The client cannot reach Dictum transport.	Retry with backoff and preserve local draft state.
quota_exceeded	Project or site usage limit was reached.	Show billing or limit messaging.
transcription_failed	STT or correction failed server-side.	Offer retry and keep the original audio when possible.

Security

Keys stay server-side

Client integrations identify a project and session. Provider credentials, model choices, correction prompts, and limits are resolved from the server profile.

Client payload rules

Do not send provider credentials from the browser or mobile app.
Do not expose internal transport routes as product documentation.
Use stable user references rather than sensitive identifiers.
Keep transcript storage and retention explicit in the host application.

Testing

Integration checklist

Microphone permission	Handle allow, deny, and prompt-later states.
State rendering	Render listening, recording, transcribing, editing, done, and error.
Transcript handling	Treat partial as draft and final/done as commit-ready output.
Session cleanup	Call cancel or destroy when leaving the screen.
Retry behavior	Retry only retryable errors and avoid duplicate transcript insertion.
Privacy	Do not send provider keys or unnecessary personal data from clients.

Versioning

Stable contract first

The SDK can add events, attributes, and options without breaking clients. Removing or changing event names, method semantics, transcript payload fields, or error codes should require a major SDK version and a migration note.

project-key	Required project key.
user-ref	Optional app-side user reference.
mode	compact, inline, or custom shell behavior.
correction	true or false; defaults to project profile.
language	auto or a language hint.
theme	light, dark, or project default.