solid-drift 0.25.0 → 0.27.0

package/dist/voice.d.ts

@@ -0,0 +1,292 @@
+import { type Accessor } from "solid-js";
+type MaybeElement = () => Element | null | undefined;
+/** Phase of a voice interaction. */
+export type VoiceStatus = "idle" | "listening" | "thinking" | "speaking";
+export interface VoiceStateControls {
+    /** Current phase. */
+    state: Accessor<VoiceStatus>;
+    toIdle: () => void;
+    toListening: () => void;
+    toThinking: () => void;
+    toSpeaking: () => void;
+}
+/**
+ * The state machine behind a voice assistant turn: the user speaks
+ * (`listening`), the app works (`thinking`), the app replies
+ * (`speaking`), then back to `idle`. Wire the phases to
+ * `createSpeech` (listening), your model call (thinking), and
+ * `createTTS` (speaking).
+ *
+ * ```ts
+ * const voice = createVoiceState();
+ * voice.toListening();          // mic open
+ * // ... transcript arrives
+ * voice.toThinking();           // calling the model
+ * // ... reply ready
+ * voice.toSpeaking();           // TTS playing
+ * voice.toIdle();
+ * ```
+ */
+export declare function createVoiceState(): VoiceStateControls;
+export interface MicLevelOptions {
+    /** Analyser FFT size. Default 512. */
+    fftSize?: number;
+    /** EMA smoothing factor 0..1 (higher = smoother). Default 0.7. */
+    smoothing?: number;
+    /** Gain applied to the RMS before clamping to 0..1. Default 3. */
+    gain?: number;
+    /** Use an existing stream instead of requesting the microphone. */
+    stream?: MediaStream;
+    /** Called with each smoothed level. */
+    onLevel?: (level: number) => void;
+}
+export interface MicLevelControls {
+    /** Smoothed volume 0..1. */
+    level: Accessor<number>;
+    /** Whether the meter is running. */
+    active: Accessor<boolean>;
+    /** False on the server or without WebAudio/getUserMedia. */
+    supported: boolean;
+    /** The analyser node, for wiring into `createWaveform`. */
+    analyser: Accessor<AnalyserNode | null>;
+    /** The last error, if any. */
+    error: Accessor<Error | null>;
+    /** Request the mic (call from a user gesture) and start metering. */
+    start: () => Promise<void>;
+    /** Stop metering and release the microphone. */
+    stop: () => void;
+}
+/**
+ * A live microphone volume meter: `getUserMedia` plus an
+ * `AnalyserNode`, smoothed to a 0..1 level signal.
+ *
+ * ```ts
+ * const mic = createMicLevel();
+ * // in a click handler:
+ * await mic.start();
+ * <div style={{ width: `${mic.level() * 100}%` }} />
+ * ```
+ *
+ * SSR-safe: `supported` is false without WebAudio/getUserMedia and
+ * `start()` rejects there.
+ */
+export declare function createMicLevel(options?: MicLevelOptions): MicLevelControls;
+export interface SpeechOptions {
+    /** BCP-47 language tag. Default the browser language. */
+    lang?: string;
+    /** Keep listening across utterances. Default false. */
+    continuous?: boolean;
+    /** Emit interim (non-final) results. Default true. */
+    interimResults?: boolean;
+    /** Called per result: the result text and whether it is final. */
+    onResult?: (transcript: string, isFinal: boolean) => void;
+    /** Called on recognition errors. */
+    onError?: (error: Error) => void;
+}
+export interface SpeechControls {
+    /** False on the server or without the Web Speech API. */
+    supported: boolean;
+    /** Whether recognition is running. */
+    listening: Accessor<boolean>;
+    /** Accumulated final transcript. */
+    transcript: Accessor<string>;
+    /** Latest interim transcript (empty when the last result was final). */
+    interim: Accessor<string>;
+    /** The last error, if any. */
+    error: Accessor<Error | null>;
+    /** Start listening (call from a user gesture). */
+    start: () => void;
+    /** Stop listening. */
+    stop: () => void;
+    /** Clear the accumulated transcript. */
+    reset: () => void;
+}
+/**
+ * Speech-to-text via the Web Speech API (`SpeechRecognition` with
+ * `webkitSpeechRecognition` fallback).
+ *
+ * ```ts
+ * const speech = createSpeech({ lang: "en-US" });
+ * // in a click handler:
+ * speech.start();
+ * <p>{speech.transcript()}<span class="dim">{speech.interim()}</span></p>
+ * ```
+ *
+ * SSR-safe: `supported` is false without the API and `start()` is a
+ * no-op there. Note the API itself is a browser/cloud service with
+ * per-browser availability and limits.
+ */
+export declare function createSpeech(options?: SpeechOptions): SpeechControls;
+export interface WaveformOptions {
+    /** Analyser node to draw (wire to `createMicLevel().analyser`). */
+    analyser: () => AnalyserNode | null;
+    /** Stroke color. Default "#3e6c99". */
+    color?: string;
+    /** Line width in px. Default 2. */
+    lineWidth?: number;
+    /** `"line"` draws the time-domain wave, `"bars"` the spectrum. Default `"line"`. */
+    mode?: "line" | "bars";
+    /** Background fill, or null for a transparent clear. Default null. */
+    background?: string | null;
+    /** Pause rendering. Default true. */
+    enabled?: boolean | Accessor<boolean>;
+}
+export interface WaveformControls {
+    /** Whether the render loop is running. */
+    active: Accessor<boolean>;
+}
+/**
+ * A canvas waveform renderer driven by an `AnalyserNode`.
+ *
+ * ```tsx
+ * const mic = createMicLevel();
+ * createWaveform(() => canvas, { analyser: mic.analyser, mode: "bars" });
+ * <canvas ref={canvas} style={{ width: "100%", height: "64px" }} />
+ * ```
+ *
+ * The canvas is sized to its CSS box times the device pixel ratio.
+ * Under reduced motion it redraws at most every 250ms. SSR-safe:
+ * nothing renders without a canvas.
+ */
+export declare function createWaveform(canvas: MaybeElement, options: WaveformOptions): WaveformControls;
+/** Cloud TTS upgrade: implement `speak` with your provider. */
+export interface TTSProvider {
+    speak: (text: string, opts: {
+        signal: AbortSignal;
+    }) => Promise<void>;
+}
+export interface TTSOptions {
+    /**
+     * `"browser"` uses `speechSynthesis`; pass a `TTSProvider` to
+     * upgrade to a cloud voice (fetch the audio in `speak`).
+     * Default `"browser"`.
+     */
+    provider?: "browser" | TTSProvider;
+    /** BCP-47 language tag. Default the browser language. */
+    lang?: string;
+    /** 0.1..10. Default 1. */
+    rate?: number;
+    /** 0..2. Default 1. */
+    pitch?: number;
+    /** 0..1. Default 1. */
+    volume?: number;
+    /**
+     * Pick the voice: a voice name, or a function choosing from the
+     * available voices.
+     */
+    voice?: string | ((voices: SpeechSynthesisVoice[]) => SpeechSynthesisVoice | undefined);
+    onStart?: () => void;
+    onEnd?: () => void;
+    onError?: (error: Error) => void;
+}
+export interface TTSControls {
+    /** False on the server or without `speechSynthesis` (browser provider). */
+    supported: boolean;
+    /** Whether speech is currently playing. */
+    speaking: Accessor<boolean>;
+    /** Available browser voices (loads asynchronously). */
+    voices: Accessor<SpeechSynthesisVoice[]>;
+    /** Speak the text (cancels anything currently playing). */
+    speak: (text: string) => void;
+    /** Stop playback. */
+    cancel: () => void;
+}
+/**
+ * Text-to-speech with `speechSynthesis` by default and a clean
+ * upgrade path to cloud voices.
+ *
+ * ```ts
+ * const tts = createTTS({ rate: 1.05 });
+ * tts.speak("Your report is ready.");
+ *
+ * // Cloud upgrade:
+ * const tts = createTTS({
+ *   provider: {
+ *     speak: async (text, { signal }) => {
+ *       const res = await fetch("/api/tts", {
+ *         method: "POST",
+ *         body: JSON.stringify({ text }),
+ *         signal,
+ *       });
+ *       await playAudioBlob(await res.blob(), signal);
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * SSR-safe: `supported` is false without `speechSynthesis` and
+ * `speak()` is a no-op there.
+ */
+export declare function createTTS(options?: TTSOptions): TTSControls;
+export interface ThinkingOptions {
+    /** Phrases to cycle through. Default `["Thinking"]`. */
+    phrases?: string[];
+    /** Time per step in ms. Default 400. */
+    interval?: number;
+}
+export interface ThinkingControls {
+    /** Current label, e.g. `"Thinking.."`. Empty when stopped. */
+    text: Accessor<string>;
+    /** Whether the indicator is running. */
+    running: Accessor<boolean>;
+    /** Start cycling. */
+    start: () => void;
+    /** Stop and clear the label. */
+    stop: () => void;
+}
+/**
+ * An animated "thinking" indicator for voice reply latency: cycles
+ * trailing dots, then moves through phrases.
+ *
+ * ```ts
+ * const thinking = createThinking({ phrases: ["Thinking", "Searching"] });
+ * thinking.start();
+ * <p>{thinking.text()}</p> // "Thinking", "Thinking.", "Thinking..", ...
+ * ```
+ */
+export declare function createThinking(options?: ThinkingOptions): ThinkingControls;
+export interface PromptOptions {
+    /** Called with the submitted text. */
+    onSubmit?: (text: string) => void;
+    /** Clear the input after submit. Default true. */
+    clearOnSubmit?: boolean;
+    /** Language for dictation. */
+    lang?: string;
+}
+export interface PromptControls {
+    /** Current input text (typed or dictated). */
+    value: Accessor<string>;
+    /** Set the input text. */
+    setValue: (value: string) => void;
+    /** Whether the mic is listening. */
+    listening: Accessor<boolean>;
+    /** Latest interim dictation. */
+    interim: Accessor<string>;
+    /** False on the server or without the Web Speech API. */
+    supported: boolean;
+    /** Toggle mic dictation. */
+    toggleMic: () => void;
+    /** Submit the current text. */
+    submit: () => void;
+    /** Clear the input. */
+    clear: () => void;
+}
+/**
+ * A voice-enabled prompt input: a text value plus mic dictation,
+ * built for chat boxes and voice assistants. Dictated finals are
+ * appended to the value as they arrive; pairs with `createChatModel`
+ * for a full voice loop.
+ *
+ * ```tsx
+ * const prompt = createPrompt({ onSubmit: (t) => chat.send(t) });
+ * <input
+ *   value={prompt.value()}
+ *   onInput={(e) => prompt.setValue(e.currentTarget.value)}
+ *   onKeyDown={(e) => e.key === "Enter" && prompt.submit()}
+ *   placeholder={prompt.listening() ? prompt.interim() || "Listening..." : "Ask anything"}
+ * />
+ * <button onClick={() => prompt.toggleMic()}>Mic</button>
+ * ```
+ */
+export declare function createPrompt(options?: PromptOptions): PromptControls;
+export {};