Voice input infrastructure for product interfaces.

import { checkCompatibility, createClient } from "dictum-sdk";

const compatibility = checkCompatibility();
if (!compatibility.supported) {
  showUnsupportedBrowser(compatibility.missing);
} else {
  const client = createClient({
    projectKey: "dpk_live_xxx",
    identityToken: await getDictumIdentityToken(),
    target: document.querySelector("#message")
  });

  client.on("state_changed", event => renderVoiceState(event.state));
  client.on("transcript_delta", event => renderFinalSegment(event.data.text));
  client.on("sdk_error", event => showVoiceError(event.data));

  startButton.onclick = () => client.start().catch(showVoiceError);
  pauseButton.onclick = () => client.pause().catch(showVoiceError);
  resumeButton.onclick = () => client.resume().catch(showVoiceError);
  stopButton.onclick = () => client.stop().catch(showVoiceError);
  retryButton.onclick = () => client.retry().catch(showVoiceError);

  const result = await client.waitForResult();
  renderFinalTranscript(result.text, result.transport);
  inspectLatency(result.timing); // Separate monotonic client and Worker timelines.
}

const report = checkCompatibility();

if (!report.supported) {
  voiceButton.disabled = true;
  showMessage("Please update your browser to use voice input.");
  console.debug({ capture: report.capture, missing: report.missing });
}

import { createHmac } from "node:crypto";

const MAX_IDENTITY_LIFETIME_SECONDS = 7 * 24 * 60 * 60;
const encodeJson = value => Buffer.from(JSON.stringify(value)).toString("base64url");

function createDictumIdentity({ keyId, signingSecret, projectKey, userId, userName }) {
  const iat = Math.floor(Date.now() / 1000);
  const header = { alg: "HS256", typ: "JWT", kid: keyId };
  const payload = {
    sub: String(userId),
    ...(userName ? { name: String(userName) } : {}),
    aud: projectKey,
    iat,
    exp: iat + MAX_IDENTITY_LIFETIME_SECONDS
  };
  const unsignedToken = [encodeJson(header), encodeJson(payload)].join(".");
  const signature = createHmac("sha256", signingSecret)
    .update(unsignedToken)
    .digest("base64url");

  return [unsignedToken, signature].join(".");
}

app.post("/api/dictum/identity", requireUser, (request, response) => {
  const identityToken = createDictumIdentity({
    keyId: process.env.DICTUM_SIGNING_KEY_ID,
    signingSecret: process.env.DICTUM_SIGNING_SECRET,
    projectKey: process.env.DICTUM_PROJECT_KEY,
    userId: request.user.id
  });

  response.json({ identityToken });
});

import { createHmac, timingSafeEqual } from "node:crypto";

app.post("/webhooks/dictum", rawJsonBody, (request, response) => {
  const timestamp = request.get("X-Dictum-Timestamp");
  const received = request.get("X-Dictum-Signature");
  const expected = "v1=" + createHmac("sha256", process.env.DICTUM_WEBHOOK_SECRET)
    .update(timestamp + "." + request.rawBody)
    .digest("hex");

  if (!received || !timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
    return response.sendStatus(401);
  }

  const event = JSON.parse(request.rawBody);
  // Deduplicate event.id before processing an at-least-once delivery.
  console.log(event.data.audio_duration_ms, event.data.word_count);
  response.sendStatus(204);
});

---
name: dictum-voice-ui-design
description: Design or review product-native Dictum speech-to-text interfaces using the public SDK states and events.
---

<!-- Generated from DICTUM_STT_EVENT_CONTRACT (fe3fb49b2593dbc7de4b6a7d8a0dfe5cd433447b370f782b5459b2dd19313473). Do not edit public/skill.md directly. -->

# Dictum Voice UI Design

Use this skill when building or reviewing Dictum voice interfaces for websites
and apps. Dictum should feel native inside the host product rather than looking
like a generic recorder.

## Workflow

1. Inspect the host product first: input shape, density, brand colors,
   interaction style, mobile constraints, and where speech should appear.
2. Design against the SDK's exact closed public contract:
   - States (7): `idle`, `requesting_mic`, `listening`, `paused`, `retrying`, `transcribing`, `failed`.
   - Events (17): `state_changed`, `volume_changed`, `transcript_delta`, `text_inserted`, `mic_denied`, `no_transcript`, `network_error`, `audio_invalid`, `compat_failed`, `limit_reached`, `fallback_started`, `quota_exceeded`, `auth_required`, `identity_expired`, `auth_invalid`, `retry_started`, `sdk_error`.
   - `text_inserted` is an event after successful insertion, never a lifecycle
     state.
3. Keep the control visible but compact. Use a microphone, waveform, spinner,
   check, stop, pause, retry, or warning icon only when the state requires it.
4. Show progress where users need confidence:
   - `listening`: show live audio signal or an active capture affordance.
   - `transcribing`: show a spinner with concise status text.
   - `text_inserted`: place the transcript in the target or preview, not in a
     detached debug surface.
   - `failed`: provide short recovery copy and one clear next action based on
     the typed public error.
5. Preserve keyboard, touch, and pointer ergonomics. The voice control must be
   tappable on mobile and must not interfere with normal typing.
6. Match the host design tokens. Use Tailwind tokens or declared theme
   variables and isolate provider-specific colors inside provider-inspired
   mockups.

## Design rules

- Do not add SDK-owned overlays, floating panels, hidden debug cards, or generic
  audio-upload UI.
- Do not expose raw SDK internals, transport frames, provider names, or
  implementation details to end users.
- Do not invent, rename, title-case, or space-separate SDK state or event names.
- Do not make state labels look clickable unless they are controls.
- Do not rely on color alone for state. Pair color with an icon, motion, text,
  or shape.
- Keep animations short and consistent with the host motion system. Animate
  transform and opacity when possible.
- For provider-inspired examples, reproduce the interaction pattern rather than
  presenting a misleading fake product integration.
- For marketing demos, show the transcript landing in the real target surface
  users understand.

## Output checklist

- Every public SDK state listed above has a deliberate UI path.
- Event handlers use the exact public names listed above.
- Successful insertion is handled through `text_inserted`, not an `inserted`
  state.
- The UI can recover from permission denied, no speech, empty audio, network
  error, authentication error, quota exceeded, and audio too long.
- Mobile and desktop layouts keep the control aligned with the input.
- The design avoids competitor claims and focuses on voice input integrated
  into sites or apps.
- The implementation uses no private Worker assumptions.

{
  "product": "Dictum",
  "capability": "headless voice-to-text for desktop and mobile web browsers",
  "browserOnly": true,
  "nonBrowserIntegration": "Use the Dictum API directly",
  "package": "dictum-sdk",
  "packagePublished": false,
  "browserSecrets": [
    "project public key",
    "signed customer identity under the global non-configurable seven-day maximum"
  ],
  "serverOnlySecrets": [
    "Dictum signing key",
    "speech provider API keys"
  ],
  "states": [
    "idle",
    "requesting_mic",
    "listening",
    "paused",
    "retrying",
    "transcribing",
    "failed"
  ],
  "events": [
    "state_changed",
    "volume_changed",
    "transcript_delta",
    "text_inserted",
    "mic_denied",
    "no_transcript",
    "network_error",
    "audio_invalid",
    "compat_failed",
    "limit_reached",
    "fallback_started",
    "quota_exceeded",
    "auth_required",
    "identity_expired",
    "auth_invalid",
    "retry_started",
    "sdk_error"
  ],
  "transport": "WebSocket first; explicit bounded recovery to POST",
  "transcriptRule": "Every transcript_delta segment is provider-confirmed, final, immutable, and append-only.",
  "usageRule": "Usage is measured by the Worker, never submitted by the browser SDK.",
  "privacyRule": "Never log raw audio, transcript text, signed identity, or provider secrets. Transcript text leaves Dictum only through a project-owner-configured signed webhook."
}