@ephia/dova-sdk 1.0.0

package/src/devices/speechmike/browser.ts

@@ -0,0 +1,80 @@
+export type HidDeviceLike = {
+  productName?: string;
+  manufacturerName?: string;
+  vendorId?: number;
+  productId?: number;
+};
+
+export type HidConnectionEventLike = Event & {
+  device?: HidDeviceLike;
+};
+
+export type HidLike = {
+  getDevices: () => Promise<HidDeviceLike[]>;
+  addEventListener: (
+    type: "connect" | "disconnect",
+    listener: (event: Event) => void,
+  ) => void;
+  removeEventListener: (
+    type: "connect" | "disconnect",
+    listener: (event: Event) => void,
+  ) => void;
+};
+
+type NavigatorWithHid = Navigator & {
+  hid?: HidLike;
+};
+
+export function isBrowser(): boolean {
+  return typeof window !== "undefined" && typeof navigator !== "undefined";
+}
+
+export function getNavigatorHid(): HidLike | null {
+  if (!isBrowser()) return null;
+  return (navigator as NavigatorWithHid).hid ?? null;
+}
+
+export function isWebHidAvailable(): boolean {
+  return getNavigatorHid() !== null;
+}
+
+export function createTimeoutError(operation: string, timeoutMs: number): Error {
+  return new Error(`${operation} timeout after ${timeoutMs}ms`);
+}
+
+export function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  operation: string,
+): Promise<T> {
+  if (typeof window === "undefined") return promise;
+
+  let timeoutId: number | null = null;
+
+  return Promise.race([
+    promise.finally(() => {
+      if (timeoutId !== null) window.clearTimeout(timeoutId);
+    }),
+    new Promise<T>((_, reject) => {
+      timeoutId = window.setTimeout(() => {
+        reject(createTimeoutError(operation, timeoutMs));
+      }, timeoutMs);
+    }),
+  ]);
+}
+
+export function matchesSpeechMikeIdentity(device: {
+  productName?: string;
+  manufacturerName?: string;
+  vendorId?: number;
+  productId?: number;
+}): boolean {
+  const productName = device.productName?.toLowerCase() ?? "";
+  const manufacturerName = device.manufacturerName?.toLowerCase() ?? "";
+
+  return (
+    productName.includes("speechmike") ||
+    productName.includes("philips") ||
+    manufacturerName.includes("philips")
+  );
+}

package/src/devices/speechmike/constants.ts

@@ -0,0 +1,74 @@
+import type { EphiaSpeechMikeAction, EphiaSpeechMikeLedIntent } from "./types";
+
+export const SPEECHMIKE_VENDOR_IDS = {
+  PHILIPS: 0x0911,
+} as const;
+
+export const SPEECHMIKE_CONFIG = {
+  BUTTON_DEBOUNCE_MS: 150,
+  WATCHDOG_INTERVAL_MS: 10_000,
+  DEVICE_OPERATION_TIMEOUT_MS: 2_000,
+  REQUEST_DEVICE_TIMEOUT_MS: 15_000,
+  LED_OPERATION_TIMEOUT_MS: 500,
+} as const;
+
+export const LED_MODE = {
+  OFF: 0,
+  ON: 1,
+  ON_BRIGHT: 3,
+} as const;
+
+export const DEFAULT_BUTTON_MAPPING: Record<string, EphiaSpeechMikeAction> = {
+  RECORD: "record.toggle",
+  PLAY: "play.toggle",
+  FORWARD: "seek.forward",
+  REWIND: "seek.backward",
+
+  F1: "audio.discard",
+  F1_A: "audio.discard",
+  F2: "audio.discard",
+  F2_B: "audio.discard",
+
+  F3: "audio.submit",
+  F3_C: "audio.submit",
+  F4: "audio.submit",
+  F4_D: "audio.submit",
+
+  INS: "agent.open",
+  OVR: "exam.new",
+  INS_OVR: "exam.new",
+
+  EOL: "resources.toggle",
+  EOL_PRIO: "resources.toggle",
+};
+
+const ALL_LEDS_OFF: Record<number, number> = {
+  0: 0,
+  1: 0,
+  2: 0,
+  3: 0,
+  4: 0,
+  5: 0,
+  6: 0,
+  7: 0,
+  8: 0,
+  9: 0,
+};
+
+export const DEFAULT_LED_INTENTS: Record<EphiaSpeechMikeLedIntent, Record<number, number>> = {
+  off: { ...ALL_LEDS_OFF },
+  idle: { ...ALL_LEDS_OFF, 2: LED_MODE.ON_BRIGHT },
+  recording: { ...ALL_LEDS_OFF, 1: LED_MODE.ON_BRIGHT },
+  processing: { ...ALL_LEDS_OFF, 2: LED_MODE.ON, 4: LED_MODE.ON },
+  audio_available: {
+    ...ALL_LEDS_OFF,
+    6: LED_MODE.ON_BRIGHT,
+    7: LED_MODE.ON_BRIGHT,
+    8: LED_MODE.ON_BRIGHT,
+    9: LED_MODE.ON_BRIGHT,
+  },
+  success: { ...ALL_LEDS_OFF, 2: 2 },
+  error: { ...ALL_LEDS_OFF, 3: 2 },
+  cancelled: { ...ALL_LEDS_OFF, 3: LED_MODE.ON_BRIGHT },
+};
+

package/src/devices/speechmike/dictation-support-loader.ts

@@ -0,0 +1,81 @@
+export type DictationDevice = unknown;
+
+export type DictationButtonCallback = (
+  device: DictationDevice,
+  bitMask: number,
+) => void;
+
+export type DictationDeviceCallback = (device: DictationDevice) => void;
+
+export type DictationMotionCallback = (
+  device: DictationDevice,
+  motion: number,
+) => void;
+
+export type DictationDeviceManagerLike = {
+  init?: () => Promise<void>;
+  requestDevice: () => Promise<DictationDevice[]>;
+  getDeviceInfo?: (device: DictationDevice) => Promise<unknown>;
+  getDevices?: () => DictationDevice[];
+
+  addButtonEventListener?: (cb: DictationButtonCallback) => void;
+  removeButtonEventListener?: (cb: DictationButtonCallback) => void;
+
+  addDeviceConnectedEventListener?: (cb: DictationDeviceCallback) => void;
+  removeDeviceConnectedEventListener?: (cb: DictationDeviceCallback) => void;
+
+  addDeviceDisconnectedEventListener?: (cb: DictationDeviceCallback) => void;
+  removeDeviceDisconnectedEventListener?: (cb: DictationDeviceCallback) => void;
+
+  addMotionEventListener?: (cb: DictationMotionCallback) => void;
+  removeMotionEventListener?: (cb: DictationMotionCallback) => void;
+
+  disconnect?: () => void;
+};
+
+export type DictationSupportEnum = Record<number, string> & Record<string, number>;
+
+export type DictationSupportRuntime = {
+  DictationDeviceManager: new () => DictationDeviceManagerLike;
+  ButtonEvent: DictationSupportEnum;
+  MotionEvent?: DictationSupportEnum;
+};
+
+let runtimePromise: Promise<DictationSupportRuntime> | null = null;
+
+type DictationSupportModule = {
+  DictationDeviceManager?: new () => DictationDeviceManagerLike;
+  ButtonEvent?: DictationSupportEnum;
+  MotionEvent?: DictationSupportEnum;
+};
+
+export function resetDictationSupportLoaderForTests(): void {
+  runtimePromise = null;
+}
+
+export function loadDictationSupport(): Promise<DictationSupportRuntime> {
+  if (runtimePromise) return runtimePromise;
+
+  const specifier = "dictation_support";
+  runtimePromise = import(/* @vite-ignore */ specifier)
+    .then((mod: DictationSupportModule) => {
+      if (!mod.DictationDeviceManager || !mod.ButtonEvent) {
+        throw new Error("dictation_support exports are incomplete");
+      }
+
+      return {
+        DictationDeviceManager: mod.DictationDeviceManager,
+        ButtonEvent: mod.ButtonEvent,
+        MotionEvent: mod.MotionEvent,
+      };
+    })
+    .catch((error: unknown) => {
+      runtimePromise = null;
+      throw Object.assign(new Error("dictation_support unavailable"), {
+        code: "speechmike.driver_missing",
+        cause: error,
+      });
+    });
+
+  return runtimePromise;
+}

package/src/devices/speechmike/index.ts

@@ -0,0 +1,11 @@
+export * from "./types";
+export * from "./constants";
+export * from "./dictation-support-loader";
+export * from "./speechmike-audio-resolver";
+export * from "./speechmike-button-router";
+export * from "./speechmike-led-controller";
+export * from "./speechmike-device-manager";
+export * from "./react/EphiaSpeechMikeProvider";
+export * from "./react/EphiaSpeechMikeContext";
+export * from "./react/useEphiaSpeechMike";
+

package/src/devices/speechmike/react/EphiaSpeechMikeContext.ts

@@ -0,0 +1,34 @@
+"use client";
+
+import { createContext } from "react";
+import type {
+  EphiaSpeechMikeAction,
+  EphiaSpeechMikeLedIntent,
+  EphiaSpeechMikeState,
+} from "../types";
+
+export type EphiaSpeechMikeContextValue = EphiaSpeechMikeState & {
+  isConnected: boolean;
+  isReady: boolean;
+  requestAuthorization: () => Promise<void>;
+  reconnect: () => Promise<void>;
+  setLedIntent: (intent: EphiaSpeechMikeLedIntent) => void;
+  setButtonMapping: (mapping: Partial<Record<string, EphiaSpeechMikeAction>>) => void;
+};
+
+export const FALLBACK_EPHIA_SPEECHMIKE_STATE: EphiaSpeechMikeState = {
+  status: { hid: "unsupported", audio: "idle" },
+  device: null,
+  deviceInfo: null,
+  physicallyPresent: false,
+  audioInputDeviceId: null,
+  audioInputDeviceLabel: null,
+  pressedButtons: new Set<string>(),
+  lastButton: null,
+  lastAction: null,
+  error: null,
+};
+
+export const EphiaSpeechMikeContext =
+  createContext<EphiaSpeechMikeContextValue | null>(null);
+

package/src/devices/speechmike/react/EphiaSpeechMikeProvider.tsx

@@ -0,0 +1,287 @@
+"use client";
+
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useEphiaInternal } from "../../../react/provider/EphiaInternalContext";
+import { SpeechMikeDeviceManager } from "../speechmike-device-manager";
+import { SpeechMikeLedController } from "../speechmike-led-controller";
+import { resolveSpeechMikeAudioInput } from "../speechmike-audio-resolver";
+import {
+  EphiaSpeechMikeContext,
+  type EphiaSpeechMikeContextValue,
+} from "./EphiaSpeechMikeContext";
+import type {
+  EphiaSpeechMikeAction,
+  EphiaSpeechMikeAudioStatus,
+  EphiaSpeechMikeError,
+  EphiaSpeechMikeLedIntent,
+  EphiaSpeechMikeState,
+} from "../types";
+
+export type EphiaSpeechMikeProviderProps = {
+  children: React.ReactNode;
+  enabled?: boolean;
+  autoConnect?: boolean;
+  preferAudioInput?: boolean;
+  requestAudioPermissionOnInit?: boolean;
+  ledSync?: boolean;
+  initialLedIntent?: EphiaSpeechMikeLedIntent;
+  buttonMapping?: Partial<Record<string, EphiaSpeechMikeAction>>;
+  onAction?: (action: EphiaSpeechMikeAction) => void;
+  onError?: (error: EphiaSpeechMikeError) => void;
+  onStatusChange?: (state: EphiaSpeechMikeState) => void;
+};
+
+const INITIAL_STATE: EphiaSpeechMikeState = {
+  status: { hid: "idle", audio: "idle" },
+  device: null,
+  deviceInfo: null,
+  physicallyPresent: false,
+  audioInputDeviceId: null,
+  audioInputDeviceLabel: null,
+  pressedButtons: new Set<string>(),
+  lastButton: null,
+  lastAction: null,
+  error: null,
+};
+
+type StatePatch =
+  | Partial<EphiaSpeechMikeState>
+  | ((prev: EphiaSpeechMikeState) => EphiaSpeechMikeState);
+
+export function EphiaSpeechMikeProvider({
+  children,
+  enabled = true,
+  autoConnect = true,
+  preferAudioInput = true,
+  requestAudioPermissionOnInit = false,
+  ledSync = true,
+  initialLedIntent = "idle",
+  buttonMapping,
+  onAction,
+  onError,
+  onStatusChange,
+}: EphiaSpeechMikeProviderProps): React.ReactElement {
+  const internal = useEphiaInternal();
+  const managerRef = useRef<SpeechMikeDeviceManager | null>(null);
+  const ledRef = useRef<SpeechMikeLedController | null>(null);
+  const onActionRef = useRef(onAction);
+  const onErrorRef = useRef(onError);
+  const onStatusChangeRef = useRef(onStatusChange);
+  const ledSyncRef = useRef(ledSync);
+  const initialLedIntentRef = useRef(initialLedIntent);
+  const buttonMappingRef = useRef(buttonMapping);
+
+  const [state, setState] = useState<EphiaSpeechMikeState>(INITIAL_STATE);
+
+  onActionRef.current = onAction;
+  onErrorRef.current = onError;
+  onStatusChangeRef.current = onStatusChange;
+  ledSyncRef.current = ledSync;
+  initialLedIntentRef.current = initialLedIntent;
+  buttonMappingRef.current = buttonMapping;
+
+  const patchState = useCallback((patch: StatePatch): void => {
+    setState((prev) => {
+      const next =
+        typeof patch === "function"
+          ? patch(prev)
+          : {
+              ...prev,
+              ...patch,
+            };
+      onStatusChangeRef.current?.(next);
+      return next;
+    });
+  }, []);
+
+  const setAudioStatus = useCallback(
+    (audio: EphiaSpeechMikeAudioStatus): void => {
+      patchState((prev) => ({
+        ...prev,
+        status: { ...prev.status, audio },
+      }));
+    },
+    [patchState],
+  );
+
+  const resolveAndApplyAudioInput = useCallback(async (): Promise<void> => {
+    if (!preferAudioInput) return;
+
+    setAudioStatus("resolving");
+
+    try {
+      const match = await resolveSpeechMikeAudioInput({
+        requestPermission: requestAudioPermissionOnInit,
+      });
+
+      if (!match) {
+        patchState((prev) => ({
+          ...prev,
+          status: { ...prev.status, audio: "not_found" },
+          audioInputDeviceId: null,
+          audioInputDeviceLabel: null,
+        }));
+        return;
+      }
+
+      internal.clientRef.current?.setPreferredAudioInputDeviceId(match.deviceId);
+      patchState((prev) => ({
+        ...prev,
+        status: { ...prev.status, audio: "ready" },
+        audioInputDeviceId: match.deviceId,
+        audioInputDeviceLabel: match.label,
+        error: null,
+      }));
+    } catch (error) {
+      const err = {
+        code: "speechmike.audio_resolve_failed",
+        message: error instanceof Error ? error.message : String(error),
+      };
+      patchState((prev) => ({
+        ...prev,
+        status: { ...prev.status, audio: "error" },
+        error: err,
+      }));
+      onErrorRef.current?.(err);
+    }
+  }, [
+    internal.clientRef,
+    patchState,
+    preferAudioInput,
+    requestAudioPermissionOnInit,
+    setAudioStatus,
+  ]);
+
+  useEffect(() => {
+    if (!enabled) {
+      patchState(INITIAL_STATE);
+      return;
+    }
+
+    const manager = new SpeechMikeDeviceManager({
+      buttonMapping: buttonMappingRef.current,
+    });
+    const led = new SpeechMikeLedController(() => manager.getCurrentDevice());
+    managerRef.current = manager;
+    ledRef.current = led;
+
+    const unsubs = [
+      manager.on("status", (hidStatus) => {
+        patchState((prev) => ({
+          ...prev,
+          status: { ...prev.status, hid: hidStatus },
+        }));
+      }),
+      manager.on("presence", (physicallyPresent) => {
+        patchState({ physicallyPresent });
+      }),
+      manager.on("deviceInfo", (deviceInfo) => {
+        patchState({ deviceInfo });
+      }),
+      manager.on("device", (device) => {
+        patchState({ device });
+        if (device && ledSyncRef.current) {
+          led.setIntent(initialLedIntentRef.current);
+        }
+        if (device && preferAudioInput) {
+          void resolveAndApplyAudioInput();
+        }
+      }),
+      manager.on("button", ({ buttons, actions }) => {
+        const buttonList = [...buttons];
+        const lastButton = buttonList[buttonList.length - 1] ?? null;
+        const lastAction = actions[actions.length - 1] ?? null;
+
+        patchState({
+          pressedButtons: new Set(buttons),
+          lastButton,
+          lastAction,
+        });
+
+        for (const action of actions) {
+          onActionRef.current?.(action);
+        }
+      }),
+      manager.on("error", (error) => {
+        patchState({ error });
+        onErrorRef.current?.(error);
+      }),
+    ];
+
+    if (autoConnect) {
+      manager.initialize().catch((error: unknown) => {
+        const err = {
+          code: "speechmike.initialize_failed",
+          message: error instanceof Error ? error.message : String(error),
+        };
+        patchState({ error: err });
+        onErrorRef.current?.(err);
+      });
+    }
+
+    return () => {
+      unsubs.forEach((unsub) => unsub());
+      led.clear();
+      manager.dispose();
+      managerRef.current = null;
+      ledRef.current = null;
+    };
+  }, [
+    autoConnect,
+    enabled,
+    patchState,
+    preferAudioInput,
+    resolveAndApplyAudioInput,
+  ]);
+
+  useEffect(() => {
+    managerRef.current?.setButtonMapping(buttonMapping ?? {});
+  }, [buttonMapping]);
+
+  useEffect(() => {
+    if (!enabled || !preferAudioInput) return;
+    if (typeof navigator === "undefined" || !navigator.mediaDevices?.addEventListener) return;
+
+    const handler = (): void => {
+      void resolveAndApplyAudioInput();
+    };
+
+    navigator.mediaDevices.addEventListener("devicechange", handler);
+    return () => {
+      navigator.mediaDevices.removeEventListener("devicechange", handler);
+    };
+  }, [enabled, preferAudioInput, resolveAndApplyAudioInput]);
+
+  const value = useMemo<EphiaSpeechMikeContextValue>(
+    () => ({
+      ...state,
+      isConnected: state.status.hid === "connected",
+      isReady: state.status.hid === "connected" && state.status.audio === "ready",
+      requestAuthorization: async () => {
+        if (!enabled) {
+          throw new Error("EphiaSpeechMikeProvider is disabled");
+        }
+        await managerRef.current?.requestAuthorization();
+        await resolveAndApplyAudioInput();
+      },
+      reconnect: async () => {
+        if (!enabled) return;
+        await managerRef.current?.reconnect();
+        await resolveAndApplyAudioInput();
+      },
+      setLedIntent: (intent) => {
+        ledRef.current?.setIntent(intent);
+      },
+      setButtonMapping: (mapping) => {
+        managerRef.current?.setButtonMapping(mapping);
+      },
+    }),
+    [enabled, resolveAndApplyAudioInput, state],
+  );
+
+  return (
+    <EphiaSpeechMikeContext.Provider value={value}>
+      {children}
+    </EphiaSpeechMikeContext.Provider>
+  );
+}

package/src/devices/speechmike/react/useEphiaSpeechMike.ts

@@ -0,0 +1,26 @@
+"use client";
+
+import { useContext } from "react";
+import {
+  EphiaSpeechMikeContext,
+  FALLBACK_EPHIA_SPEECHMIKE_STATE,
+  type EphiaSpeechMikeContextValue,
+} from "./EphiaSpeechMikeContext";
+
+export function useEphiaSpeechMike(): EphiaSpeechMikeContextValue {
+  const ctx = useContext(EphiaSpeechMikeContext);
+  if (ctx) return ctx;
+
+  return {
+    ...FALLBACK_EPHIA_SPEECHMIKE_STATE,
+    isConnected: false,
+    isReady: false,
+    requestAuthorization: async () => {
+      throw new Error("EphiaSpeechMikeProvider not mounted");
+    },
+    reconnect: async () => {},
+    setLedIntent: () => {},
+    setButtonMapping: () => {},
+  };
+}
+

package/src/devices/speechmike/speechmike-audio-resolver.ts

@@ -0,0 +1,58 @@
+export type SpeechMikeAudioMatch = {
+  deviceId: string;
+  label: string;
+  score: number;
+  raw: MediaDeviceInfo;
+};
+
+export function scoreSpeechMikeAudioDevice(device: MediaDeviceInfo): number {
+  if (device.kind !== "audioinput") return 0;
+
+  const label = (device.label ?? "").toLowerCase();
+  let score = 0;
+
+  if (label.includes("speechmike")) score += 100;
+  if (label.includes("philips")) score += 60;
+  if (label.includes("dictation")) score += 40;
+  if (label.includes("microphone")) score += 10;
+
+  return score;
+}
+
+export async function listAudioInputDevices(): Promise<MediaDeviceInfo[]> {
+  if (typeof navigator === "undefined" || !navigator.mediaDevices?.enumerateDevices) {
+    return [];
+  }
+
+  const devices = await navigator.mediaDevices.enumerateDevices();
+  return devices.filter((device) => device.kind === "audioinput");
+}
+
+export async function resolveSpeechMikeAudioInput(options?: {
+  requestPermission?: boolean;
+}): Promise<SpeechMikeAudioMatch | null> {
+  if (typeof navigator === "undefined" || !navigator.mediaDevices) return null;
+
+  let permissionStream: MediaStream | null = null;
+  if (options?.requestPermission) {
+    permissionStream = await navigator.mediaDevices.getUserMedia({ audio: true });
+  }
+
+  try {
+    const inputs = await listAudioInputDevices();
+    const matches = inputs
+      .map((device) => ({
+        deviceId: device.deviceId,
+        label: device.label,
+        score: scoreSpeechMikeAudioDevice(device),
+        raw: device,
+      }))
+      .filter((match) => match.score > 0)
+      .sort((a, b) => b.score - a.score);
+
+    return matches[0] ?? null;
+  } finally {
+    permissionStream?.getTracks().forEach((track) => track.stop());
+  }
+}
+