@alia.onl/sdk 13.2.0 → 15.3.0

package/src/hooks/useSpeechToText.ts

@@ -1,268 +0,0 @@
-import { useState, useCallback, useRef, useEffect } from 'react';
-import { create } from 'zustand';
-import {
-  chooseSpeechRecognizer,
-  isSpeechRecognitionAvailable,
-  requestSpeechRecognitionPermission,
-  startSpeechRecognition,
-} from '../lib/speech-recognition';
-import type { SpeechRecognitionSession } from '../lib/speech-recognition-types';
-import type { SpeechRecognizerChoice } from '../lib/speech-recognition-types';
-import {
-  speechFailureCode,
-  VOICE_ERROR_MESSAGES,
-  type VoiceErrorCode,
-} from '../lib/speech-messages';
-import { defaultSpeechLanguage } from '../lib/speech-language';
-
-// ============== OPTIONS ==============
-
-export interface UseSTTOptions {
-  /**
-   * Language to recognize, as a BCP-47 tag (`es-ES`). Defaults to the
-   * platform's own language. The Alia app passes its UI locale.
-   */
-  lang?: string;
-}
-
-// ============== INLINE STT STORE ==============
-
-interface STTStoreState {
-  isRecording: boolean;
-  metering: number;
-  setRecording: (v: boolean) => void;
-  setMetering: (v: number) => void;
-}
-
-export const useSTTStore = create<STTStoreState>((set) => ({
-  isRecording: false,
-  metering: 0,
-  setRecording: (isRecording) => set({ isRecording }),
-  setMetering: (metering) => set({ metering }),
-}));
-
-// ============== HOOK ==============
-
-type STTState = 'idle' | 'recording' | 'transcribing';
-
-/** How long `stopAndTranscribe` waits for the engine's final words. */
-const FINAL_RESULT_TIMEOUT_MS = 2_000;
-
-/**
- * How many times one dictation may quietly re-open the recognizer.
- *
- * Browsers end a continuous session on their own — Chrome after a stretch of
- * silence or about a minute of audio — and the person is still looking at a
- * dictation bar that says it is listening. Re-opening keeps what was already
- * heard and carries on. The cap is what stops an engine that ends the instant
- * it starts from spinning.
- */
-const MAX_SILENT_RESTARTS = 20;
-
-/**
- * Dictation, recognized on the device.
- *
- * The public shape is the one the recorder-and-upload version had —
- * `startRecording`, `stopAndTranscribe`, `cancel`, the three states and
- * `useSTTStore`'s metering — so the composer and the dictation bar did not
- * change. What changed underneath: words arrive while the person speaks
- * (`speech-recognition.ts` on web, `.native.ts` on iOS/Android), so
- * `transcribing` is now the moment between "stop" and the engine's final
- * result rather than an upload, and there is no transcription endpoint.
- */
-export function useSpeechToText(options: UseSTTOptions = {}) {
-  const lang = options.lang ?? defaultSpeechLanguage();
-
-  const [state, setState] = useState<STTState>('idle');
-  const [errorCode, setErrorCode] = useState<VoiceErrorCode | null>(null);
-  const [isSupported] = useState(isSpeechRecognitionAvailable);
-
-  const stateRef = useRef<STTState>('idle');
-  const sessionRef = useRef<SpeechRecognitionSession | null>(null);
-  /** Text from sessions that already ended during this dictation. */
-  const earlierTextRef = useRef('');
-  /** Text from the live session. */
-  const currentTextRef = useRef('');
-  const restartsRef = useRef(0);
-  /** The recognizer and tag this dictation uses, chosen once when it starts. */
-  const recognizerRef = useRef<{ lang: string; service?: string; silent: boolean }>({
-    lang,
-    silent: false,
-  });
-  const endWaitersRef = useRef<Array<() => void>>([]);
-  const lastMeteringRef = useRef(0);
-  const mountedRef = useRef(true);
-
-  /** What went wrong, as a code; `null` clears it. */
-  const report = useCallback((code: VoiceErrorCode | null) => {
-    if (mountedRef.current) setErrorCode(code);
-  }, []);
-
-  const setPhase = useCallback((next: STTState) => {
-    stateRef.current = next;
-    if (mountedRef.current) setState(next);
-  }, []);
-
-  // Sync recording state to store + reset metering on stop
-  useEffect(() => {
-    useSTTStore.getState().setRecording(state === 'recording');
-    if (state !== 'recording') {
-      lastMeteringRef.current = 0;
-      useSTTStore.getState().setMetering(0);
-    }
-  }, [state]);
-
-  const fullText = (): string =>
-    `${earlierTextRef.current} ${currentTextRef.current}`.replace(/\s+/g, ' ').trim();
-
-  const openSession = useCallback(() => {
-    currentTextRef.current = '';
-    let failed = false;
-    const recognizer = recognizerRef.current;
-    sessionRef.current = startSpeechRecognition(
-      { lang: recognizer.lang, service: recognizer.service },
-      {
-        onResult: ({ transcript }) => {
-          currentTextRef.current = transcript;
-        },
-        onLevel: (level) => {
-          if (stateRef.current !== 'recording') return;
-          // Epsilon guard: quiet should not thrash the store's subscribers.
-          if (Math.abs(level - lastMeteringRef.current) < 0.02) return;
-          lastMeteringRef.current = level;
-          useSTTStore.getState().setMetering(level);
-        },
-        onError: (failure) => {
-          const code = speechFailureCode(failure);
-          if (code === null) return;
-          failed = true;
-          // Every recognizer on the device named no language, and the
-          // default refused this one: it is the device that cannot recognize
-          // speech, not the language that is wrong.
-          report(code === 'speech-language' && recognizer.silent ? 'speech-unsupported' : code);
-        },
-        onEnd: () => {
-          sessionRef.current = null;
-          earlierTextRef.current = fullText();
-          currentTextRef.current = '';
-          const waiters = endWaitersRef.current;
-          endWaitersRef.current = [];
-          for (const resolve of waiters) resolve();
-          if (waiters.length > 0) return;
-
-          // The engine ended on its own while the person is still dictating.
-          if (stateRef.current !== 'recording') return;
-          if (failed || restartsRef.current >= MAX_SILENT_RESTARTS) {
-            setPhase('idle');
-            return;
-          }
-          restartsRef.current += 1;
-          openSession();
-        },
-      },
-    );
-  }, [report, setPhase]);
-
-  const startRecording = useCallback(async () => {
-    if (stateRef.current !== 'idle') return;
-    report(null);
-
-    if (!isSpeechRecognitionAvailable()) {
-      report('speech-unsupported');
-      return;
-    }
-
-    // Claim the state before the first await so a double tap cannot open two.
-    setPhase('recording');
-    const refusal = await requestSpeechRecognitionPermission();
-    if ((stateRef.current as STTState) !== 'recording') return; // cancelled while asking
-    if (refusal !== null) {
-      report(speechFailureCode(refusal));
-      setPhase('idle');
-      return;
-    }
-
-    const choice: SpeechRecognizerChoice = await chooseSpeechRecognizer(lang);
-    if ((stateRef.current as STTState) !== 'recording') return; // cancelled while choosing
-    if ('failure' in choice) {
-      report(speechFailureCode(choice.failure));
-      setPhase('idle');
-      return;
-    }
-    recognizerRef.current = choice;
-
-    earlierTextRef.current = '';
-    currentTextRef.current = '';
-    restartsRef.current = 0;
-    openSession();
-  }, [lang, openSession, report, setPhase]);
-
-  const waitForEnd = useCallback((): Promise<void> => {
-    if (sessionRef.current === null) return Promise.resolve();
-    return new Promise<void>((resolve) => {
-      const timer = setTimeout(() => {
-        sessionRef.current?.abort();
-        resolve();
-      }, FINAL_RESULT_TIMEOUT_MS);
-      endWaitersRef.current.push(() => {
-        clearTimeout(timer);
-        resolve();
-      });
-    });
-  }, []);
-
-  const stopAndTranscribe = useCallback(async (): Promise<string | null> => {
-    if (stateRef.current !== 'recording') return null;
-    setPhase('transcribing');
-    const ended = waitForEnd();
-    sessionRef.current?.stop();
-    await ended;
-    const text = fullText();
-    earlierTextRef.current = '';
-    currentTextRef.current = '';
-    setPhase('idle');
-    return text === '' ? null : text;
-  }, [setPhase, waitForEnd]);
-
-  const cancel = useCallback(() => {
-    const session = sessionRef.current;
-    setPhase('idle');
-    earlierTextRef.current = '';
-    currentTextRef.current = '';
-    session?.abort();
-    report(null);
-  }, [report, setPhase]);
-
-  useEffect(() => {
-    mountedRef.current = true;
-    return () => {
-      mountedRef.current = false;
-      const wasListening = stateRef.current !== 'idle';
-      stateRef.current = 'idle';
-      sessionRef.current?.abort();
-      // The effect that mirrors the phase into the store will not run again,
-      // and the store outlives this hook: a composer unmounted mid-dictation —
-      // the call controls replacing it — would otherwise leave the ambient
-      // field and the dictation bar reading "recording" for the rest of the call.
-      if (wasListening) {
-        useSTTStore.getState().setRecording(false);
-        useSTTStore.getState().setMetering(0);
-      }
-    };
-  }, []);
-
-  return {
-    state,
-    /** What went wrong, in English. */
-    error: errorCode === null ? null : VOICE_ERROR_MESSAGES[errorCode],
-    /** The same, as a code an app can translate. */
-    errorCode,
-    /** False where the platform cannot recognize speech at all (Firefox). */
-    isSupported,
-    startRecording,
-    stopAndTranscribe,
-    cancel,
-    isRecording: state === 'recording',
-    isTranscribing: state === 'transcribing',
-  };
-}

package/src/lib/speech-recognition-types.ts

@@ -1,108 +0,0 @@
-/**
- * The one shape on-device speech recognition has in this package.
- *
- * Two engines sit behind it and neither leaks through: the browser's Web
- * Speech API (`speech-recognition.ts`, picked by web bundlers and by tests) and
- * `expo-speech-recognition` on iOS and Android (`speech-recognition.native.ts`,
- * picked by Metro's platform resolution). Dictation and the voice loop are
- * written against this file only, so the audio never leaves the device through
- * Alia — there is no transcription endpoint, and nothing here posts audio
- * anywhere. Whether the ENGINE uses a network service is the platform's
- * business and is stated in `docs/voice.mdx`.
- */
-
-/** Why a recognition session failed, in the vocabulary both engines share. */
-export type SpeechRecognitionFailureCode =
-  /** Microphone or speech-recognition permission was refused. */
-  | 'not-allowed'
-  /** No microphone, or it could not be opened. */
-  | 'audio-capture'
-  /** The engine needed the network and could not reach it. */
-  | 'network'
-  /** The engine does not recognize this language. */
-  | 'language-not-supported'
-  /** Nothing was said before the engine gave up. Recoverable: start again. */
-  | 'no-speech'
-  /** The session was aborted on purpose. Never an error to report. */
-  | 'aborted'
-  /** Recognition is not available on this device or in this browser. */
-  | 'unsupported'
-  /** Anything else — the engine was busy, interrupted, or said nothing useful. */
-  | 'other';
-
-export interface SpeechRecognitionFailure {
-  readonly code: SpeechRecognitionFailureCode;
-  /** The engine's own words, for logs. Never shown as-is. */
-  readonly detail?: string;
-}
-
-export interface SpeechRecognitionHandlers {
-  /**
-   * The whole of what this session has heard so far, and whether the engine
-   * considers it settled. It is the FULL transcript each time, never a delta:
-   * both engines revise earlier words as more audio arrives.
-   */
-  onResult(result: { transcript: string; isFinal: boolean }): void;
-  /** Input level, 0..1, on the same scale as dictation's metering. */
-  onLevel?(level: number): void;
-  onError(failure: SpeechRecognitionFailure): void;
-  /** The session is over, whichever way it ended. Always the last call. */
-  onEnd(): void;
-}
-
-export interface SpeechRecognitionOptions {
-  /** BCP-47 tag, e.g. `es-ES`. */
-  readonly lang: string;
-  /**
-   * Android: the recognition service to use, by package, instead of the
-   * system's default. `chooseSpeechRecognizer` picks it.
-   */
-  readonly service?: string;
-  /**
-   * Remove the device's own playback from what the microphone hears, where the
-   * platform can (iOS voice processing). Voice mode listens while it speaks,
-   * so without this it can hear itself.
-   */
-  readonly echoCancellation?: boolean;
-}
-
-export interface SpeechRecognitionSession {
-  /** Stop listening and deliver a final result, then `onEnd`. */
-  stop(): void;
-  /** Stop listening and discard; `onEnd` still follows. */
-  abort(): void;
-}
-
-/** Map a raw 0..1-ish reading to the field's level, clamped. */
-export function clampLevel(level: number): number {
-  if (!Number.isFinite(level)) return 0;
-  return Math.min(1, Math.max(0, level));
-}
-
-/**
- * What to start a session with, decided before the first one opens.
- *
- * `silent` is set when the device has recognition services and every one of
- * them, asked, named no language at all. A `language-not-supported` from such
- * a device is not about the language: nothing on it recognizes speech (a Pixel
- * without Google's speech services, whose remaining service has no language
- * pack). Where nobody could be asked — the web, iOS — it is `false` and a
- * language error stays one.
- */
-export type SpeechRecognizerChoice =
-  | { readonly lang: string; readonly service?: string; readonly silent: boolean }
-  | { readonly failure: SpeechRecognitionFailure };
-
-/**
- * The tag in `offered` that recognizes `lang`: the same tag (`en-US`, however
- * the service spells it — `en_US`, `en-us`), else another region of the same
- * language (`es-US` for `es-ES`), else `null`.
- */
-export function matchSpeechLocale(lang: string, offered: readonly string[]): string | null {
-  const norm = (tag: string) => tag.replace(/_/g, '-').toLowerCase();
-  const wanted = norm(lang);
-  const exact = offered.find((tag) => norm(tag) === wanted);
-  if (exact !== undefined) return exact;
-  const language = wanted.split('-')[0];
-  return offered.find((tag) => norm(tag).split('-')[0] === language) ?? null;
-}

package/src/lib/speech-recognition.native.ts

@@ -1,237 +0,0 @@
-/**
- * On-device speech recognition for iOS and Android, through
- * `expo-speech-recognition` (Apple's Speech framework, Android's
- * `SpeechRecognizer`). Metro picks this file over `speech-recognition.ts` on
- * native; the contract is `speech-recognition-types.ts`.
- *
- * `expo-speech-recognition` is a peer of the SDK and a native module: an app
- * must depend on it (the root entry's dictation reaches this file) and list its
- * config plugin (which writes `NSSpeechRecognitionUsageDescription`,
- * `NSMicrophoneUsageDescription` and Android's `RECORD_AUDIO` plus the
- * recognizer-package visibility query), then ship a new native build.
- *
- * The module is a process-wide singleton — one recognition at a time — so the
- * hooks never start a session before the previous one has reported `onEnd`. A
- * late `end` from an aborted session would otherwise land on its successor's
- * listeners.
- */
-
-import type {
-  ExpoSpeechRecognitionErrorCode,
-  ExpoSpeechRecognitionModule as NativeModule,
-} from 'expo-speech-recognition';
-import {
-  clampLevel,
-  matchSpeechLocale,
-  type SpeechRecognizerChoice,
-  type SpeechRecognitionFailure,
-  type SpeechRecognitionFailureCode,
-  type SpeechRecognitionHandlers,
-  type SpeechRecognitionOptions,
-  type SpeechRecognitionSession,
-} from './speech-recognition-types';
-
-type SpeechModule = typeof NativeModule;
-
-let loaded: SpeechModule | null | undefined;
-
-/**
- * The native module, loaded on first use — never at import.
- *
- * `expo-speech-recognition` calls `requireNativeModule` when it is imported,
- * which THROWS in a binary built before the module was added (an older dev
- * client, Expo Go). This file is reachable from the SDK's root entry through
- * dictation, so a top-level import would take the whole app down in such a
- * build over a feature nobody had touched yet. Loaded here, the same build
- * answers "not available" and everything else keeps working.
- */
-function speechModule(): SpeechModule | null {
-  if (loaded !== undefined) return loaded;
-  try {
-    loaded = (require('expo-speech-recognition') as typeof import('expo-speech-recognition'))
-      .ExpoSpeechRecognitionModule;
-  } catch {
-    loaded = null;
-  }
-  return loaded;
-}
-
-export function isSpeechRecognitionAvailable(): boolean {
-  try {
-    return speechModule()?.isRecognitionAvailable() ?? false;
-  } catch {
-    return false;
-  }
-}
-
-export async function requestSpeechRecognitionPermission(): Promise<SpeechRecognitionFailure | null> {
-  const module = speechModule();
-  if (module === null || !isSpeechRecognitionAvailable()) return { code: 'unsupported' };
-  try {
-    const permission = await module.requestPermissionsAsync();
-    return permission.granted ? null : { code: 'not-allowed', detail: permission.status };
-  } catch (error: unknown) {
-    return {
-      code: 'other',
-      detail: error instanceof Error ? error.message : 'permission request failed',
-    };
-  }
-}
-
-function failureOf(error: ExpoSpeechRecognitionErrorCode): SpeechRecognitionFailureCode {
-  switch (error) {
-    case 'not-allowed':
-    case 'service-not-allowed':
-      return 'not-allowed';
-    case 'audio-capture':
-      return 'audio-capture';
-    case 'network':
-      return 'network';
-    case 'language-not-supported':
-      return 'language-not-supported';
-    case 'no-speech':
-    case 'speech-timeout':
-      return 'no-speech';
-    case 'aborted':
-      return 'aborted';
-    default:
-      return 'other';
-  }
-}
-
-/** `volumechange` is -2..10, and anything below 0 is inaudible. */
-const VOLUME_CEILING = 10;
-
-/**
- * Which recognizer to use for `lang`, and the tag it knows the language by.
- *
- * Android leaves recognition to whichever service the device has, and
- * `SpeechRecognizer` answers a language it cannot do only by failing:
- * `language-not-supported`, which dictation showed as "does not support this
- * language" whatever the real reason. On a Pixel the default service is often
- * Android System Intelligence, which recognizes only the languages whose
- * packs are downloaded, while another service on the same phone (Google's
- * speech services) could have done it. So each service is asked what it
- * recognizes — the default first — and the first that has the language wins,
- * under the spelling it uses; a service offering only another region of the
- * language (`es-US` for `es-ES`) is taken over failing.
- *
- * A service that reports nothing (Android 12 and older, a service that does
- * not implement the query) proves nothing, so when none reports, the default
- * is tried as before, with `silent` set if there were services to ask. iOS has
- * none to list and goes straight to Apple's recognizer.
- */
-export async function chooseSpeechRecognizer(lang: string): Promise<SpeechRecognizerChoice> {
-  const module = speechModule();
-  if (module === null) return { failure: { code: 'unsupported' } };
-  const attempt = <T>(read: () => T, fallback: T): T => {
-    try {
-      return read();
-    } catch {
-      return fallback;
-    }
-  };
-  const preferred = attempt(() => module.getDefaultRecognitionService().packageName, '');
-  const services = attempt(() => module.getSpeechRecognitionServices(), [] as string[]);
-  const order = [...new Set([preferred, ...services].filter((name) => name !== ''))];
-
-  let reported = false;
-  let asked = 0;
-  for (const service of order) {
-    let offered: string[];
-    try {
-      offered = (await module.getSupportedLocales({ androidRecognitionServicePackage: service }))
-        .locales;
-    } catch {
-      continue;
-    }
-    asked += 1;
-    if (offered.length === 0) continue;
-    reported = true;
-    const tag = matchSpeechLocale(lang, offered);
-    if (tag !== null) return { lang: tag, service, silent: false };
-  }
-  if (reported) return { failure: { code: 'language-not-supported' } };
-  return { lang, silent: asked > 0 };
-}
-
-export function startSpeechRecognition(
-  options: SpeechRecognitionOptions,
-  handlers: SpeechRecognitionHandlers,
-): SpeechRecognitionSession {
-  const module = speechModule();
-  if (module === null) {
-    handlers.onError({ code: 'unsupported' });
-    handlers.onEnd();
-    return { stop: () => undefined, abort: () => undefined };
-  }
-  const ExpoSpeechRecognitionModule = module;
-  let ended = false;
-  /**
-   * Finals already delivered. Android's continuous mode starts a new segment
-   * after every final result, so the utterance is the settled segments plus
-   * whatever is still in flight; iOS only finalizes on stop and always sends
-   * the whole transcript, so this stays empty there.
-   */
-  let settled = '';
-
-  const subscriptions = [
-    ExpoSpeechRecognitionModule.addListener('result', (event) => {
-      if (ended) return;
-      const current = event.results[0]?.transcript ?? '';
-      const transcript = `${settled} ${current}`.replace(/\s+/g, ' ').trim();
-      if (event.isFinal) settled = transcript;
-      handlers.onResult({ transcript, isFinal: event.isFinal });
-    }),
-    ExpoSpeechRecognitionModule.addListener('error', (event) => {
-      if (ended) return;
-      const code = failureOf(event.error);
-      if (code === 'aborted') return;
-      handlers.onError({ code, detail: event.message });
-    }),
-    ExpoSpeechRecognitionModule.addListener('end', () => finish()),
-    ExpoSpeechRecognitionModule.addListener('volumechange', (event) => {
-      if (ended) return;
-      handlers.onLevel?.(clampLevel(event.value / VOLUME_CEILING));
-    }),
-  ];
-
-  function finish(): void {
-    if (ended) return;
-    ended = true;
-    for (const subscription of subscriptions) subscription.remove();
-    handlers.onLevel?.(0);
-    handlers.onEnd();
-  }
-
-  try {
-    ExpoSpeechRecognitionModule.start({
-      lang: options.lang,
-      ...(options.service ? { androidRecognitionServicePackage: options.service } : {}),
-      interimResults: true,
-      continuous: true,
-      addsPunctuation: true,
-      maxAlternatives: 1,
-      volumeChangeEventOptions: { enabled: handlers.onLevel !== undefined, intervalMillis: 100 },
-      ...(options.echoCancellation ? { iosVoiceProcessingEnabled: true } : {}),
-    });
-  } catch (error: unknown) {
-    if (!ended)
-      handlers.onError({
-        code: 'other',
-        detail: error instanceof Error ? error.message : 'start failed',
-      });
-    finish();
-  }
-
-  return {
-    stop() {
-      if (ended) return;
-      ExpoSpeechRecognitionModule.stop();
-    },
-    abort() {
-      if (ended) return;
-      ExpoSpeechRecognitionModule.abort();
-    },
-  };
-}