@happyvertical/smrt-ui 0.51.39 → 0.53.0

package/dist/components/forms/dictation.svelte.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Dictation: speak into a text field.
+ *
+ * The state machine behind the microphone button and "long-press a field to
+ * speak". It does not recognise speech itself: the host hands it a speech
+ * source, normally smrt-svelte's browser speech-to-text adapter
+ * (`createSttDictationSource` in `@happyvertical/smrt-svelte/browser-ai`),
+ * whose adapters already satisfy `DictationSpeechSource`. That keeps smrt-ui
+ * free of the Provider and the speech engines, and gives one speech engine
+ * for forms, chat, and anything else.
+ *
+ * States: `idle` → `starting` → `listening` → `stopping` → `idle`, and
+ * `error` (with `errorKind`) from any of them. A "ready" beep plays when the
+ * microphone is actually listening. Final phrases go to `onText` (put them
+ * in the field with `insertTextAtCursor`); the phrase in progress is
+ * `interim`.
+ *
+ * How listening stops: tap the microphone again (`toggle`/`stop`), send the
+ * form, press Escape, or pause talking (the browser ends it). A long press
+ * starts listening and it keeps listening after the finger comes up, so the
+ * person can press, hear the beep, let go, and talk.
+ *
+ * On first use it asks for the microphone (`getUserMedia`) and waits for the
+ * answer before it starts recognising, so the permission prompt cannot cut
+ * the recogniser off and a "no" shows as "the microphone is blocked".
+ *
+ * It never stops silently. Every recogniser error becomes an `error` state
+ * with a plain `errorKind` (and the raw `errorCode`, and a console warning);
+ * a recogniser that ends on its own within `earlyEndMs` of starting without
+ * hearing anything (Brave's speech recognition does this) is an error too.
+ *
+ * Recording fallback: give it a `transcribe` function and, when the browser
+ * has no speech recognition (Firefox), or it fails with no speech service
+ * behind it (Brave: Web Speech `network` / `service-not-allowed`, or an end
+ * straight away), it records the message with `MediaRecorder` instead
+ * (WebM/Opus, or MP4 on Safari; capped at `maxDurationMs` and `maxBytes`).
+ * When the person stops, the state is `transcribing` ("Writing it down…")
+ * while `transcribe(audio, { mimeType, language })` turns the recording into
+ * text, which goes to `onText` like a spoken phrase. Once the browser's
+ * recogniser has failed, this `Dictation` records straight away next time.
+ */
+import { type DictationAudioCaptureFactory } from './audio-capture.js';
+import type { DictationTranscribe } from './dictation-transcribe.js';
+export type DictationState = 'idle' | 'starting' | 'listening' | 'stopping' | 'transcribing' | 'error';
+/**
+ * Why dictation stopped with an error:
+ * - `unsupported`: this browser cannot recognise speech, or has no speech
+ *   service behind it (Web Speech `network` / `service-not-allowed`: Brave);
+ * - `denied`: the microphone is blocked;
+ * - `no-speech`: nothing was heard;
+ * - `microphone`: no microphone, or it could not be opened (`audio-capture`);
+ * - `interrupted`: it stopped straight away without hearing anything
+ *   (`aborted`, or an early end with no error);
+ * - `too-long`: the recording was too long or too large to write down;
+ * - `not-transcribed`: the recording could not be written down;
+ * - `unavailable`: writing recordings down is not set up here;
+ * - `forbidden`: this person may not use it here;
+ * - `failed`: anything else.
+ */
+export type DictationErrorKind = 'unsupported' | 'denied' | 'no-speech' | 'microphone' | 'interrupted' | 'too-long' | 'not-transcribed' | 'unavailable' | 'forbidden' | 'failed';
+export interface DictationSpeechResult {
+    text: string;
+    isFinal: boolean;
+}
+export interface DictationStartOptions {
+    language?: string;
+    continuous?: boolean;
+    interimResults?: boolean;
+}
+/**
+ * A speech recogniser. smrt-svelte's `STTAdapter` satisfies it structurally.
+ * `start` may reject (not supported, microphone blocked); later failures
+ * arrive through `onError`, and `onEnd` fires when it stops listening.
+ */
+export interface DictationSpeechSource {
+    start(options?: DictationStartOptions): Promise<void>;
+    stop(): Promise<void>;
+    onResult(callback: (result: DictationSpeechResult) => void): () => void;
+    onError(callback: (error: Error) => void): () => void;
+    onEnd(callback: () => void): () => void;
+    /** When given, listening (and the beep) starts on this event. */
+    onStart?(callback: () => void): () => void;
+}
+/** Resolves the speech source on first use (it may load lazily). */
+export type DictationSourceProvider = () => DictationSpeechSource | Promise<DictationSpeechSource>;
+export interface DictationOptions {
+    /** The speech source; without one dictation reports `unsupported`. */
+    source?: DictationSourceProvider | null;
+    /** A finished phrase to put into the field. */
+    onText: (text: string) => void;
+    /** The phrase in progress (also on `interim`). */
+    onInterim?: (text: string) => void;
+    /** BCP-47 language. Default: the page's `lang`, else `en-US`. */
+    language?: string;
+    /**
+     * The ready beep: `true` (default) plays the built-in beep, `false` none,
+     * or a function that plays one and resolves whether it did.
+     */
+    beep?: boolean | (() => Promise<boolean> | boolean);
+    /** How long to wait for the source to confirm it stopped. Default 1500ms. */
+    stopTimeoutMs?: number;
+    /**
+     * Ask for the microphone (`getUserMedia`) and wait for the answer before
+     * starting the source, once per `Dictation`. Default `true`; skipped where
+     * the browser has no `navigator.mediaDevices`.
+     */
+    requestMicrophone?: boolean;
+    /**
+     * A source that ends by itself this soon after it started listening,
+     * without a result and without being asked to stop, failed
+     * (`interrupted`). Default 1000ms; `0` turns the check off.
+     */
+    earlyEndMs?: number;
+    /**
+     * Where problems are reported (default: `console.warn`). Never given the
+     * audio or the words heard.
+     */
+    log?: (event: DictationLogEvent) => void;
+    /**
+     * Turns a recorded message into text. With it, dictation records instead
+     * when the browser cannot recognise speech (see the module comment), and
+     * without a `source` it always records. Normally
+     * `createHttpTranscriber('/your/route')`: the speech service's key stays on
+     * the server.
+     */
+    transcribe?: DictationTranscribe | null;
+    /** Records the message (default: `MediaRecorder`). For tests and hosts. */
+    capture?: DictationAudioCaptureFactory;
+    /** Longest recording, in ms; it stops and is written down then. Default 120000. */
+    maxDurationMs?: number;
+    /** Largest recording, in bytes. Default 10 MB. */
+    maxBytes?: number;
+    /** How long writing a recording down may take. Default 60000ms. */
+    transcribeTimeoutMs?: number;
+}
+/** A dictation problem, for logs. */
+export interface DictationLogEvent {
+    kind: DictationErrorKind;
+    /** Raw code: the Web Speech error (`network`, …) or the error's name. */
+    code: string | null;
+    message: string;
+    /**
+     * Where it happened: `microphone`, `source`, `start`, `error`, `end`, or
+     * in the recording fallback `record` / `transcribe`.
+     */
+    stage: 'microphone' | 'source' | 'start' | 'error' | 'end' | 'record' | 'transcribe';
+    /** Set when dictation carried on by recording instead of stopping. */
+    fallback?: 'recording';
+}
+/** The raw code of a speech or media error, when it has one. */
+export declare function dictationErrorCode(error: unknown): string | null;
+/**
+ * Sort a speech error into a `DictationErrorKind`. Reads the error's `code`
+ * and `name` (smrt-svelte browser-ai errors: `PERMISSION_DENIED`,
+ * `CAPABILITY_NOT_AVAILABLE`) and the Web Speech error names.
+ */
+export declare function classifyDictationError(error: unknown): DictationErrorKind;
+export declare class Dictation {
+    #private;
+    /** Where dictation is (see the module comment). */
+    state: DictationState;
+    /** Why it stopped, while `state` is `error`. */
+    errorKind: DictationErrorKind | null;
+    /** The raw error code behind `errorKind` (`network`, `NotAllowedError`…). */
+    errorCode: string | null;
+    /** The phrase being spoken right now. */
+    interim: string;
+    /** The ready beep could not play yet (no user gesture); `unlock` plays it. */
+    beepPending: boolean;
+    /**
+     * `true` while this message is being recorded (the fallback) rather than
+     * recognised by the browser.
+     */
+    recording: boolean;
+    constructor(options: DictationOptions);
+    /** A speech source or a `transcribe` was given (the browser may still turn out unable). */
+    get available(): boolean;
+    /** Starting or listening. */
+    get active(): boolean;
+    /** Replace options (for example a new `onText`). */
+    setOptions(options: Partial<DictationOptions>): void;
+    /** Start listening. A no-op while already starting, listening, or writing down. */
+    start(): Promise<void>;
+    /**
+     * Stop listening; the phrase in progress is kept if the source finishes it.
+     * A recording is written down (`transcribing`) and its text handed over.
+     */
+    stop(): Promise<void>;
+    /** Tap on the microphone: start, or stop while listening. */
+    toggle(): Promise<void>;
+    /** Clear an error so the field looks normal again. */
+    clearError(): void;
+    /**
+     * Call from a user gesture (a tap, a long press's release): plays the
+     * ready beep if it could not play when listening started.
+     */
+    unlock(): Promise<void>;
+    dispose(): void;
+}
+//# sourceMappingURL=dictation.svelte.d.ts.map

package/dist/components/forms/dictation.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dictation.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/dictation.svelte.ts"],"names":[],"mappings":"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"}