@seams/voice-capture 0.0.0-stage → 0.67.0

package/dist/types/card/surface.d.ts

@@ -0,0 +1,28 @@
+import { type VoiceRecordingOptions } from '../microphone';
+import type { PhraseSurface } from './types';
+/** What the host page adds around the card. Every field is optional. */
+export type PhraseCardFrame = Readonly<{
+    /** The element that gets the card. Default: the document body. */
+    parent?: HTMLElement;
+    /** More class names for the surface element, such as the host's theme class. */
+    className?: string;
+    /** Shows the Back control of the prompt. */
+    back?: boolean;
+    /** The host sizes its frame to the surface, so the card follows the frame. */
+    hugged?: boolean;
+    /** Runs when the surface is in the document. Its return value runs when the surface closes. */
+    mounted?(element: HTMLElement): (() => void) | void;
+}>;
+export type PhraseCardInput = Readonly<{
+    sentence: string;
+    signal: AbortSignal;
+    frame?: PhraseCardFrame;
+    /** The speech detector of the recordings. Default: `model`. */
+    detector?: VoiceRecordingOptions['detector'];
+}>;
+/**
+ * Shows the given sentence in the prompt. The surface records clips with the quality check, and
+ * stays open so the caller can show its check and the result in the same card. A too quiet or
+ * interrupted recording stays on the surface for another try.
+ */
+export declare function openPhraseCard(input: PhraseCardInput): PhraseSurface;

package/dist/types/card/types.d.ts

@@ -0,0 +1,65 @@
+/** One clip of a shown sentence: 16 kHz mono samples that passed the quality check. */
+export type PhraseRecording = Readonly<{
+    kind: 'recorded';
+    samples: Float32Array;
+    /**
+     * `performance.now()` of the last voiced frame: the person stopped speaking then, before
+     * the pause that ends the recording.
+     */
+    endOfSpeechAt: number;
+}> | Readonly<{
+    kind: 'cancelled';
+}>;
+/** One segment of the line that shows a check: waiting, working, passed, failed or held. */
+export type PhraseSegmentState = 'idle' | 'run' | 'done' | 'fail' | 'wait' | 'skip';
+/** Text in which some words are marked, such as words that a verifier heard differently. */
+export type PhraseText = string | readonly (string | Readonly<{
+    mark: string;
+}>)[];
+/**
+ * A check after the recording: the sentence stays and dims, the action row goes, and the line
+ * becomes segments. Segments that change from `run` to `done` fill one after another.
+ */
+export type PhraseCheckView = Readonly<{
+    kind: 'check';
+    label: string;
+    caption: string;
+    /** The second line. Several lines change every 1.3 s and stay on the last one. */
+    details: readonly string[];
+    segments: readonly PhraseSegmentState[];
+}>;
+/** A result or a question: a headline takes the sentence's place, with one action. */
+export type PhraseResultView = Readonly<{
+    kind: 'result';
+    label: string;
+    headline: string;
+    caption: PhraseText;
+    detail: string;
+    /** A link after the detail, such as a transaction in a block explorer. */
+    link?: Readonly<{
+        text: string;
+        href: string;
+    }>;
+    /** `busy` shows the action dimmed while something outside the surface finishes. */
+    action: Readonly<{
+        label: string;
+        icon?: 'passkey';
+        busy?: boolean;
+    }>;
+    /** `seal`: the line closes into the success seal. */
+    line: 'seal' | readonly PhraseSegmentState[];
+}>;
+export type PhraseView = PhraseCheckView | PhraseResultView;
+/** `replaced`: another view or a recording took the surface first. */
+export type PhraseChoice = 'action' | 'closed' | 'replaced';
+/**
+ * The phrase surface stays open after a recording, so the caller can show its check and the
+ * result in the same card. The caller closes it.
+ */
+export interface PhraseSurface {
+    /** Shows the sentence with Record and records one clip. A later call records again. */
+    record(): Promise<PhraseRecording>;
+    /** A check view settles only when it is replaced; a result settles on its action or close. */
+    show(view: PhraseView): Promise<PhraseChoice>;
+    close(): void;
+}

package/dist/types/card/visual.d.ts

@@ -0,0 +1,25 @@
+import type { VoiceActivityEvent } from '../microphone';
+import { type VoiceCheckingStyle } from './ribbon';
+/** Shared by enrollment, unlock and signing. The recorder remains the only audio owner. */
+export declare class VoiceVisual {
+    readonly element: SVGSVGElement;
+    readonly glow: HTMLDivElement;
+    private readonly ribbon;
+    private readonly prompt;
+    private readonly themeObserver;
+    private phase;
+    private disposed;
+    constructor(document: Document, prompt: HTMLElement, checking: VoiceCheckingStyle);
+    listen(): void;
+    add(event: VoiceActivityEvent): void;
+    checking(): void;
+    accept(): void;
+    /** The glow keeps working while the line rests flat, for a status line that takes its place. */
+    flatten(): void;
+    ready(): void;
+    /** The glow settles while the ribbon closes into the success seal; resolves when the check is drawn. */
+    succeed(begin: () => void): Promise<void>;
+    stop(): void;
+    private setPhase;
+    private readonly render;
+}

package/dist/types/config.d.ts

@@ -0,0 +1,47 @@
+/** The microphone that the person chose: the system default, or one exact device. */
+export type VoiceMicrophonePreference = {
+    readonly kind: 'system_default';
+    readonly deviceId?: never;
+} | {
+    readonly kind: 'device';
+    readonly deviceId: string;
+};
+/** Where the page keeps the chosen microphone. `read` returns what `save` got, or anything else. */
+export type VoiceMicrophonePreferenceStore = Readonly<{
+    read(): Promise<unknown>;
+    save(preference: VoiceMicrophonePreference): Promise<void>;
+}>;
+export type VoiceCaptureConfig = Readonly<{
+    /**
+     * The folder URL that serves the files of `@seams/voice-capture/hosting`: the speech detection
+     * model, the audio worklet and the model engine. A relative URL is read against the page.
+     */
+    assetBase: string | URL;
+    /** Keeps the chosen microphone between visits. Default: it lasts until the page reloads. */
+    microphonePreference?: VoiceMicrophonePreferenceStore;
+    /** The product name in messages for the person, such as "VoiceID". */
+    label?: string;
+    /** The place that the person must keep open, such as "the Wallet". */
+    place?: string;
+    /** The site that serves the asset files, such as "this Wallet". */
+    site?: string;
+    /** What the person can do when a file cannot load. It is one sentence. */
+    recoveryHint?: string;
+    /** The name of the browser cache that keeps the model files. */
+    cacheName?: string;
+    /** The nonce of the page's style policy, for the style elements of the phrase card. */
+    styleNonce?: string | (() => string | undefined);
+}>;
+type ResolvedConfig = Required<Omit<VoiceCaptureConfig, 'assetBase' | 'microphonePreference' | 'styleNonce'>> & Readonly<{
+    assetBase: URL | null;
+    microphonePreference: VoiceMicrophonePreferenceStore | null;
+    styleNonce: string | (() => string | undefined) | null;
+}>;
+/** Sets where the assets are and how the page names itself. Call it once, before a recording. */
+export declare function configureVoiceCapture(config: VoiceCaptureConfig): void;
+export declare function captureConfig(): ResolvedConfig;
+/** The nonce for a style element, or undefined when the page has none. */
+export declare function styleNonce(): string | undefined;
+/** The URL of one asset file. It throws before `configureVoiceCapture` set the folder. */
+export declare function assetUrl(fileName: string): URL;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export { configureVoiceCapture, type VoiceCaptureConfig, type VoiceMicrophonePreference, type VoiceMicrophonePreferenceStore, } from './config';
+export { recordVoice, requireVoiceForeground, requireVoiceUserAction, voiceQualityMessage, InsufficientVoiceAudioError, type VoiceActivityEvent, type VoiceCaptureEvent, type VoiceCaptureObserver, type VoiceCaptureQuality, type VoiceRecordingOptions, type VoiceRecordingResult, } from './microphone';
+export { openVoiceMicrophone, rememberVoiceMicrophone, useSystemVoiceMicrophone, VoiceMicrophoneInterruptedError, type VoiceMicrophone, } from './microphoneInput';
+export { endPauseMs, expectedSpeechMs } from './speechPause';
+export { createVoiceActivity, levelDetector, voiceActivityModel, type SpeechDetector, } from './voiceActivity';
+export { BrowserInferenceModel, VoiceAssetLoadError, voiceInferenceEngine, type ModelAsset, type VoiceAssetProgress, } from './inference';
+export { MAX_SAMPLES, pcm16Wav, SAMPLE_RATE } from './wav';

package/dist/types/inference.d.ts

@@ -0,0 +1,47 @@
+import type { InferenceSession } from 'onnxruntime-web';
+/** One file under the asset folder, with the exact bytes that the page accepts. */
+export type ModelAsset = Readonly<{
+    fileName: string;
+    sha256: string;
+    bytes: number;
+    /** The name in messages for the person. A function reads the settings when it is needed. */
+    label: string | (() => string);
+}>;
+export type VoiceAssetProgress = {
+    kind: 'checking_cache';
+} | {
+    kind: 'downloading';
+    received: number;
+} | {
+    kind: 'ready';
+};
+export declare class VoiceAssetLoadError extends Error {
+    readonly kind: 'connection' | 'unavailable' | 'integrity' | 'initialization';
+    constructor(kind: 'connection' | 'unavailable' | 'integrity' | 'initialization', message: string, options?: ErrorOptions);
+}
+declare class BrowserInferenceAsset {
+    private readonly asset;
+    private pending;
+    private progress;
+    private readonly listeners;
+    constructor(asset: ModelAsset);
+    get size(): number;
+    download(onProgress?: (progress: VoiceAssetProgress) => void): Promise<ArrayBuffer>;
+    private readonly failed;
+    private publish;
+    private valid;
+    private bytes;
+    private fetchBytes;
+}
+export declare const voiceInferenceEngine: BrowserInferenceAsset;
+export declare class BrowserInferenceModel {
+    readonly asset: BrowserInferenceAsset;
+    private session;
+    constructor(asset: ModelAsset);
+    prepare(): Promise<InferenceSession>;
+    /** Runs the model on one row of samples, as its `samples` input. Dispose the outputs. */
+    run(samples: Float32Array): Promise<InferenceSession.ReturnType>;
+    private readonly failed;
+    private load;
+}
+export {};

package/dist/types/microphone.d.ts

@@ -0,0 +1,81 @@
+import { type VoiceMicrophone } from './microphoneInput';
+/** One 32 ms frame as the recorder judged it. No capture event carries the stream. */
+export type VoiceActivityEvent = Readonly<{
+    kind: 'activity';
+    rms: number;
+    /** The speech detector and the level check both found speech. */
+    speech: boolean;
+    stream?: never;
+}>;
+export type VoiceCaptureEvent = {
+    readonly kind: 'opening';
+    readonly stream?: never;
+} | {
+    readonly kind: 'listening';
+    readonly stream?: never;
+} | VoiceActivityEvent | {
+    readonly kind: 'processing';
+    readonly stream?: never;
+} | {
+    readonly kind: 'measured';
+    readonly quality: VoiceCaptureQuality;
+    readonly stream?: never;
+};
+export type VoiceCaptureObserver = (event: VoiceCaptureEvent) => void;
+export type VoiceCaptureQuality = Readonly<{
+    attemptId: string;
+    capturedAtMs: number;
+    durationMs: number;
+    recordingMs: number;
+    endedBy: 'pause' | 'limit' | 'stream_ended';
+    voicedMs: number;
+    peakFrameRms: number;
+    levelThreshold: number;
+    requiredVoicedMs: number;
+    microphone: string;
+    microphoneSelection: VoiceMicrophone['selection'];
+    processing: VoiceMicrophone['processing'];
+    backgroundRms: number;
+    speechToBackgroundDb: number | null;
+    noise: 'high' | 'normal' | 'unknown';
+}>;
+export type VoiceRecordingResult = {
+    kind: 'captured';
+    samples: Float32Array;
+    quality: VoiceCaptureQuality;
+    /** `performance.now()` of the last voiced frame, or null when no speech was detected. */
+    lastSoundAtMs: number | null;
+} | {
+    kind: 'insufficient_audio';
+    quality: VoiceCaptureQuality;
+    samples?: never;
+};
+export declare function voiceQualityMessage(quality: VoiceCaptureQuality): string;
+/** Carries a typed capture rejection across the SDK's exception-based UI action boundary. */
+export declare class InsufficientVoiceAudioError extends Error {
+    readonly quality: VoiceCaptureQuality;
+    constructor(quality: VoiceCaptureQuality);
+}
+export type VoiceRecordingOptions = Readonly<{
+    /**
+     * The voiced time of the whole expected sentence, when the caller knows the sentence
+     * (`expectedSpeechMs`): after that much speech, a shorter pause ends the recording.
+     */
+    expectedSpeechMs?: number | null;
+    /**
+     * `model` (default): the speech detection model finds the speech. It needs the model and the
+     * model engine from the asset folder. `level`: only the sound level counts. It needs no model,
+     * and it cannot tell speech from other loud sound.
+     */
+    detector?: 'model' | 'level';
+}>;
+/** Throws unless the page is in front and the person just acted on it (a click or a key). */
+export declare function requireVoiceUserAction(): void;
+/** Throws unless the page is visible and has the focus. */
+export declare function requireVoiceForeground(): void;
+/**
+ * Records one utterance at 16 kHz. The recording ends after a pause, or after 8 s. A recording
+ * with less than 0.6 s of speech is `insufficient_audio`. The samples hold the speech with 0.2 s
+ * of margin on each side.
+ */
+export declare function recordVoice(signal: AbortSignal, onCapture: VoiceCaptureObserver, options?: VoiceRecordingOptions): Promise<VoiceRecordingResult>;

package/dist/types/microphoneInput.d.ts

@@ -0,0 +1,19 @@
+import { type VoiceMicrophonePreference } from './config';
+export type VoiceMicrophone = Readonly<{
+    stream: MediaStream;
+    preference: VoiceMicrophonePreference;
+    selection: 'default' | 'preferred' | 'replacement';
+    label: string;
+    processing: Readonly<{
+        noiseSuppression: boolean | null;
+        echoCancellation: boolean | string | null;
+        autoGainControl: boolean | null;
+        sampleRate: number | null;
+    }>;
+}>;
+export declare function openVoiceMicrophone(signal: AbortSignal): Promise<VoiceMicrophone>;
+export declare function rememberVoiceMicrophone(microphone: VoiceMicrophone): Promise<void>;
+export declare function useSystemVoiceMicrophone(): Promise<void>;
+export declare class VoiceMicrophoneInterruptedError extends Error {
+    constructor();
+}

package/dist/types/speechPause.d.ts

@@ -0,0 +1,8 @@
+/** The silence that ends a recording after `voicedMs` of speech. */
+export declare function endPauseMs(voicedMs: number, expectedSpeechMs: number | null): number;
+/**
+ * The least voiced time of the whole `sentence` as people read it aloud. Digits, dots and dashes
+ * are words of their own: "Send 0.01 NEAR to seams-v1.testnet" is read as 13 words ("send zero
+ * point zero one near to seams dash v one dot testnet").
+ */
+export declare function expectedSpeechMs(sentence: string): number;

package/dist/types/voiceActivity.d.ts

@@ -0,0 +1,15 @@
+import { BrowserInferenceModel } from './inference';
+export declare const voiceActivityModel: BrowserInferenceModel;
+/** Judges 32 ms frames of 16 kHz audio. `clear` ends one stream of frames. */
+export type SpeechDetector = Readonly<{
+    /** The probability from 0 to 1 that the 512-sample frame holds speech. */
+    probability(frame: Float32Array): Promise<number>;
+    clear(): void;
+}>;
+/** The speech detection model. It downloads the model and the model engine on first use. */
+export declare function createVoiceActivity(): Promise<SpeechDetector>;
+/**
+ * A detector with no model and no download: every frame counts as speech, so only the level
+ * check of the recorder decides. It cannot tell speech from other loud sound.
+ */
+export declare const levelDetector: SpeechDetector;

package/dist/types/wav.d.ts

@@ -0,0 +1,9 @@
+export declare const SAMPLE_RATE = 16000;
+/** The Speak-to-Sign verifier refuses audio longer than 8 s. */
+export declare const MAX_SAMPLES: number;
+/**
+ * 16 kHz mono PCM16 with the plain 44-byte header that the Speak-to-Sign verifier writes for its
+ * canonical WAV, so the SHA-256 of these bytes is the audio digest of a verdict. Samples after
+ * 8 s are left out.
+ */
+export declare function pcm16Wav(samples: Float32Array): Uint8Array<ArrayBuffer>;

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@seams/voice-capture",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.67.0",
+  "type": "module",
+  "description": "Records one spoken sentence in the browser, with speech detection, a quality check and a phrase card",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seams-tech/speak-to-sign.git",
+    "directory": "packages/voice-capture"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./card": {
+      "types": "./dist/types/card/index.d.ts",
+      "import": "./dist/esm/card/index.js"
+    },
+    "./hosting": {
+      "types": "./dist/hosting.d.mts",
+      "import": "./dist/hosting.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE.md",
+    "!dist/**/*.map"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs && tsrs -p tsconfig.build.json",
+    "type-check": "tsrs --noEmit",
+    "test": "playwright test",
+    "example": "node scripts/serve-example.mjs"
+  },
+  "dependencies": {
+    "onnxruntime-web": "1.30.0",
+    "preact": "10.29.8"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.56.1",
+    "@types/node": "24.2.0",
+    "@types/react": "19.2.18",
+    "rolldown": "1.0.0-rc.9",
+    "tsrs": "0.18.0-ts7.1.0-dev.20260929",
+    "voice-glow": "0.2.1"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@11.11.0+sha512.4463f65fd80ed80d69bc1d4bf163ee94f605c7380fc318bb5b2ebe15f8cd12d49c51a4d59e951b401e764d3b6ca751cbf51bc50ed7001a6bcb4935e684c34882"
+}