@absolutejs/voice 0.0.19 → 0.0.21

package/dist/react/index.js

@@ -130,6 +130,7 @@ var serverMessageToAction = (message) => {
     case "session":
       return {
         sessionId: message.sessionId,
+        scenarioId: message.scenarioId,
         status: message.status,
         type: "session"
       };
@@ -150,24 +151,30 @@ var WS_NORMAL_CLOSURE = 1000;
 var DEFAULT_MAX_RECONNECT_ATTEMPTS = 10;
 var DEFAULT_PING_INTERVAL = 30000;
 var RECONNECT_DELAY_MS = 500;
+var DEFAULT_SCENARIO_QUERY_PARAM = "scenarioId";
 var noop = () => {};
 var noopUnsubscribe = () => noop;
 var NOOP_CONNECTION = {
+  start: () => {},
   close: noop,
   endTurn: noop,
   getReadyState: () => WS_CLOSED,
+  getScenarioId: () => "",
   getSessionId: () => "",
   send: noop,
   sendAudio: noop,
   subscribe: noopUnsubscribe
 };
 var createSessionId = () => crypto.randomUUID();
-var buildWsUrl = (path, sessionId) => {
+var buildWsUrl = (path, sessionId, scenarioId) => {
   const { hostname, port, protocol } = window.location;
   const wsProtocol = protocol === "https:" ? "wss:" : "ws:";
   const portSuffix = port ? `:${port}` : "";
   const url = new URL(`${wsProtocol}//${hostname}${portSuffix}${path}`);
   url.searchParams.set("sessionId", sessionId);
+  if (scenarioId) {
+    url.searchParams.set(DEFAULT_SCENARIO_QUERY_PARAM, scenarioId);
+  }
   return url.toString();
 };
 var isVoiceServerMessage = (value) => {
@@ -210,6 +217,7 @@ var createVoiceConnection = (path, options = {}) => {
   const state = {
     isConnected: false,
     pendingMessages: [],
+    scenarioId: options.scenarioId ?? null,
     pingInterval: null,
     reconnectAttempts: 0,
     reconnectTimeout: null,
@@ -247,13 +255,14 @@ var createVoiceConnection = (path, options = {}) => {
     }, RECONNECT_DELAY_MS);
   };
   const connect = () => {
-    const ws = new WebSocket(buildWsUrl(path, state.sessionId));
+    const ws = new WebSocket(buildWsUrl(path, state.sessionId, state.scenarioId));
     ws.binaryType = "arraybuffer";
     ws.onopen = () => {
       state.isConnected = true;
       state.reconnectAttempts = 0;
       flushPendingMessages();
       listeners.forEach((listener) => listener({
+        scenarioId: state.scenarioId ?? undefined,
         sessionId: state.sessionId,
         status: "active",
         type: "session"
@@ -271,6 +280,7 @@ var createVoiceConnection = (path, options = {}) => {
       }
       if (parsed.type === "session") {
         state.sessionId = parsed.sessionId;
+        state.scenarioId = parsed.scenarioId ?? state.scenarioId;
       }
       listeners.forEach((listener) => listener(parsed));
     };
@@ -294,6 +304,19 @@ var createVoiceConnection = (path, options = {}) => {
   const send = (message) => {
     sendSerialized(JSON.stringify(message));
   };
+  const start = (input = {}) => {
+    if (input.sessionId) {
+      state.sessionId = input.sessionId;
+    }
+    if (input.scenarioId) {
+      state.scenarioId = input.scenarioId;
+    }
+    send({
+      type: "start",
+      sessionId: state.sessionId,
+      scenarioId: state.scenarioId ?? undefined
+    });
+  };
   const sendAudio = (audio) => {
     sendSerialized(audio);
   };
@@ -317,9 +340,11 @@ var createVoiceConnection = (path, options = {}) => {
   };
   connect();
   return {
+    start,
     close,
     endTurn,
     getReadyState: () => state.ws?.readyState ?? WS_CLOSED,
+    getScenarioId: () => state.scenarioId ?? "",
     getSessionId: () => state.sessionId,
     send,
     sendAudio,
@@ -332,6 +357,7 @@ var createInitialState = () => ({
   assistantTexts: [],
   error: null,
   isConnected: false,
+  scenarioId: null,
   partial: "",
   sessionId: null,
   status: "idle",
@@ -393,6 +419,7 @@ var createVoiceStreamStore = () => {
         state = {
           ...state,
           error: null,
+          scenarioId: action.scenarioId ?? state.scenarioId,
           isConnected: action.status === "active",
           sessionId: action.sessionId,
           status: action.status
@@ -426,6 +453,12 @@ var createVoiceStream = (path, options = {}) => {
   const connection = createVoiceConnection(path, options);
   const store = createVoiceStreamStore();
   const subscribers = new Set;
+  const start = (input) => Promise.resolve().then(() => {
+    if (!input?.sessionId && !input?.scenarioId) {
+      return;
+    }
+    connection.start(input);
+  });
   const notify = () => {
     subscribers.forEach((subscriber) => subscriber());
   };
@@ -458,6 +491,10 @@ var createVoiceStream = (path, options = {}) => {
     get isConnected() {
       return store.getSnapshot().isConnected;
     },
+    get scenarioId() {
+      return store.getSnapshot().scenarioId;
+    },
+    start,
     get partial() {
       return store.getSnapshot().partial;
     },
@@ -510,6 +547,608 @@ var useVoiceStream = (path, options = {}) => {
     sendAudio: (audio) => stream.sendAudio(audio)
   };
 };
+// src/react/useVoiceController.tsx
+import { useEffect as useEffect2, useRef as useRef2, useSyncExternalStore as useSyncExternalStore2 } from "react";
+
+// src/client/htmx.ts
+var DEFAULT_EVENT_NAME = "voice-refresh";
+var DEFAULT_QUERY_PARAM = "sessionId";
+var resolveElement = (input) => {
+  if (typeof input !== "string") {
+    return input;
+  }
+  return document.querySelector(input);
+};
+var buildRoute = (element, route, queryParam, sessionId) => {
+  const baseRoute = route ?? element.getAttribute("hx-get") ?? "";
+  if (!baseRoute) {
+    return "";
+  }
+  const url = new URL(baseRoute, window.location.origin);
+  if (sessionId) {
+    url.searchParams.set(queryParam, sessionId);
+  } else {
+    url.searchParams.delete(queryParam);
+  }
+  return `${url.pathname}${url.search}${url.hash}`;
+};
+var bindVoiceHTMX = (stream, options) => {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return () => {};
+  }
+  const element = resolveElement(options.element);
+  if (!element) {
+    return () => {};
+  }
+  const eventName = options.eventName ?? DEFAULT_EVENT_NAME;
+  const queryParam = options.sessionQueryParam ?? DEFAULT_QUERY_PARAM;
+  const sync = () => {
+    const htmxWindow = window;
+    const nextRoute = buildRoute(element, options.route, queryParam, stream.sessionId);
+    if (nextRoute) {
+      element.setAttribute("hx-get", nextRoute);
+    }
+    htmxWindow.htmx?.process?.(element);
+    htmxWindow.htmx?.trigger?.(element, eventName);
+  };
+  const unsubscribe = stream.subscribe(sync);
+  sync();
+  return () => {
+    unsubscribe();
+  };
+};
+
+// src/client/microphone.ts
+var clampSample = (value) => Math.max(-1, Math.min(1, value));
+var floatTo16BitPCM = (input) => {
+  const output = new Int16Array(input.length);
+  for (let index = 0;index < input.length; index += 1) {
+    const sample = clampSample(input[index] ?? 0);
+    output[index] = sample < 0 ? sample * 32768 : sample * 32767;
+  }
+  return new Uint8Array(output.buffer);
+};
+var getPcmLevel = (audio) => {
+  const bytes = audio instanceof Uint8Array ? audio : new Uint8Array(audio);
+  if (bytes.byteLength < 2) {
+    return 0;
+  }
+  const samples = new Int16Array(bytes.buffer, bytes.byteOffset, Math.floor(bytes.byteLength / 2));
+  if (samples.length === 0) {
+    return 0;
+  }
+  let sumSquares = 0;
+  for (const sample of samples) {
+    const normalized = sample / 32768;
+    sumSquares += normalized * normalized;
+  }
+  return Math.min(1, Math.max(0, Math.sqrt(sumSquares / samples.length) * 5.5));
+};
+var downsampleBuffer = (input, sourceRate, targetRate) => {
+  if (sourceRate === targetRate) {
+    return input;
+  }
+  const ratio = sourceRate / targetRate;
+  const length = Math.round(input.length / ratio);
+  const output = new Float32Array(length);
+  let offsetResult = 0;
+  let offsetBuffer = 0;
+  while (offsetResult < output.length) {
+    const nextOffsetBuffer = Math.round((offsetResult + 1) * ratio);
+    let accum = 0;
+    let count = 0;
+    for (let index = offsetBuffer;index < nextOffsetBuffer && index < input.length; index += 1) {
+      accum += input[index] ?? 0;
+      count += 1;
+    }
+    output[offsetResult] = count > 0 ? accum / count : 0;
+    offsetResult += 1;
+    offsetBuffer = nextOffsetBuffer;
+  }
+  return output;
+};
+var createMicrophoneCapture = (options) => {
+  let audioContext = null;
+  let sourceNode = null;
+  let processorNode = null;
+  let mediaStream = null;
+  const start = async () => {
+    if (typeof navigator === "undefined" || !navigator.mediaDevices?.getUserMedia) {
+      throw new Error("Browser microphone capture requires navigator.mediaDevices.getUserMedia.");
+    }
+    const AudioContextCtor = (typeof window !== "undefined" ? window.AudioContext ?? window.webkitAudioContext : undefined) ?? AudioContext;
+    if (!AudioContextCtor) {
+      throw new Error("Browser microphone capture requires AudioContext support.");
+    }
+    mediaStream = await navigator.mediaDevices.getUserMedia({
+      audio: {
+        channelCount: options.channelCount ?? 1
+      }
+    });
+    audioContext = new AudioContextCtor;
+    sourceNode = audioContext.createMediaStreamSource(mediaStream);
+    processorNode = audioContext.createScriptProcessor(4096, 1, 1);
+    processorNode.onaudioprocess = (event) => {
+      const channel = event.inputBuffer.getChannelData(0);
+      const downsampled = downsampleBuffer(channel, audioContext?.sampleRate ?? 48000, options.sampleRateHz ?? 16000);
+      const pcm = floatTo16BitPCM(downsampled);
+      options.onLevel?.(getPcmLevel(pcm));
+      options.onAudio(pcm);
+    };
+    sourceNode.connect(processorNode);
+    processorNode.connect(audioContext.destination);
+  };
+  const stop = () => {
+    processorNode?.disconnect();
+    sourceNode?.disconnect();
+    mediaStream?.getTracks().forEach((track) => track.stop());
+    audioContext?.close();
+    options.onLevel?.(0);
+    audioContext = null;
+    mediaStream = null;
+    processorNode = null;
+    sourceNode = null;
+  };
+  return { start, stop };
+};
+
+// src/audioConditioning.ts
+var DEFAULT_TARGET_LEVEL = 0.08;
+var DEFAULT_MAX_GAIN = 3;
+var DEFAULT_NOISE_GATE_THRESHOLD = 0.006;
+var DEFAULT_NOISE_GATE_ATTENUATION = 0.15;
+var toInt16Array = (audio) => {
+  if (audio instanceof ArrayBuffer) {
+    return new Int16Array(audio, 0, Math.floor(audio.byteLength / 2));
+  }
+  return new Int16Array(audio.buffer, audio.byteOffset, Math.floor(audio.byteLength / 2));
+};
+var computeRms = (samples) => {
+  if (samples.length === 0) {
+    return 0;
+  }
+  let sumSquares = 0;
+  for (const sample of samples) {
+    const normalized = sample / 32768;
+    sumSquares += normalized * normalized;
+  }
+  return Math.sqrt(sumSquares / samples.length);
+};
+var resolveAudioConditioningConfig = (config) => {
+  if (!config || config.enabled === false) {
+    return;
+  }
+  return {
+    enabled: true,
+    maxGain: config.maxGain ?? DEFAULT_MAX_GAIN,
+    noiseGateAttenuation: config.noiseGateAttenuation ?? DEFAULT_NOISE_GATE_ATTENUATION,
+    noiseGateThreshold: config.noiseGateThreshold ?? DEFAULT_NOISE_GATE_THRESHOLD,
+    targetLevel: config.targetLevel ?? DEFAULT_TARGET_LEVEL
+  };
+};
+var conditionAudioChunk = (audio, config) => {
+  if (!config) {
+    return audio;
+  }
+  const source = toInt16Array(audio);
+  if (source.length === 0) {
+    return audio;
+  }
+  const rms = computeRms(source);
+  const output = new Int16Array(source.length);
+  const gateFactor = rms < config.noiseGateThreshold ? config.noiseGateAttenuation : 1;
+  const baseLevel = Math.max(rms * gateFactor, 0.000001);
+  const gain = Math.min(config.maxGain, config.targetLevel / baseLevel);
+  const appliedGain = Math.max(0.25, gain) * gateFactor;
+  for (let index = 0;index < source.length; index += 1) {
+    const next = Math.round(source[index] * appliedGain);
+    output[index] = Math.max(-32768, Math.min(32767, next));
+  }
+  return new Uint8Array(output.buffer);
+};
+
+// src/turnProfiles.ts
+var TURN_PROFILE_DEFAULTS = {
+  balanced: {
+    qualityProfile: "general",
+    silenceMs: 1400,
+    speechThreshold: 0.012,
+    transcriptStabilityMs: 1000
+  },
+  fast: {
+    qualityProfile: "general",
+    silenceMs: 700,
+    speechThreshold: 0.015,
+    transcriptStabilityMs: 450
+  },
+  "long-form": {
+    qualityProfile: "general",
+    silenceMs: 2200,
+    speechThreshold: 0.01,
+    transcriptStabilityMs: 1500
+  }
+};
+var QUALITY_PROFILE_DEFAULTS = {
+  general: {},
+  "accent-heavy": {
+    silenceMs: 1200,
+    speechThreshold: 0.01,
+    transcriptStabilityMs: 1200
+  },
+  "noisy-room": {
+    silenceMs: 2000,
+    speechThreshold: 0.02,
+    transcriptStabilityMs: 1600
+  },
+  "short-command": {
+    silenceMs: 500,
+    speechThreshold: 0.016,
+    transcriptStabilityMs: 420
+  }
+};
+var DEFAULT_TURN_PROFILE = "fast";
+var DEFAULT_QUALITY_PROFILE = "general";
+var resolveTurnDetectionConfig = (config) => {
+  const profile = config?.profile ?? DEFAULT_TURN_PROFILE;
+  const qualityProfile = config?.qualityProfile ?? DEFAULT_QUALITY_PROFILE;
+  const preset = TURN_PROFILE_DEFAULTS[profile];
+  const quality = QUALITY_PROFILE_DEFAULTS[qualityProfile];
+  return {
+    profile,
+    qualityProfile,
+    silenceMs: config?.silenceMs ?? quality.silenceMs ?? preset.silenceMs,
+    speechThreshold: config?.speechThreshold ?? quality.speechThreshold ?? preset.speechThreshold,
+    transcriptStabilityMs: config?.transcriptStabilityMs ?? quality.transcriptStabilityMs ?? preset.transcriptStabilityMs
+  };
+};
+
+// src/presets.ts
+var PRESET_INPUTS = {
+  chat: {
+    audioConditioning: {
+      enabled: true,
+      maxGain: 2.5,
+      noiseGateAttenuation: 0,
+      noiseGateThreshold: 0.004,
+      targetLevel: 0.08
+    },
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 10,
+      pingInterval: 30000,
+      reconnect: true
+    },
+    sttLifecycle: "continuous",
+    turnDetection: {
+      qualityProfile: "short-command",
+      profile: "balanced"
+    }
+  },
+  default: {
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 10,
+      pingInterval: 30000,
+      reconnect: true
+    },
+    sttLifecycle: "continuous",
+    turnDetection: {
+      qualityProfile: "general",
+      profile: "fast"
+    }
+  },
+  dictation: {
+    audioConditioning: {
+      enabled: true,
+      maxGain: 2.25,
+      noiseGateAttenuation: 0.05,
+      noiseGateThreshold: 0.003,
+      targetLevel: 0.08
+    },
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 12,
+      pingInterval: 30000,
+      reconnect: true
+    },
+    sttLifecycle: "continuous",
+    turnDetection: {
+      qualityProfile: "accent-heavy",
+      profile: "long-form"
+    }
+  },
+  "guided-intake": {
+    audioConditioning: {
+      enabled: true,
+      maxGain: 2.5,
+      noiseGateAttenuation: 0,
+      noiseGateThreshold: 0.004,
+      targetLevel: 0.08
+    },
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 12,
+      pingInterval: 30000,
+      reconnect: true
+    },
+    sttLifecycle: "turn-scoped",
+    turnDetection: {
+      qualityProfile: "accent-heavy",
+      profile: "long-form"
+    }
+  },
+  "noisy-room": {
+    audioConditioning: {
+      enabled: true,
+      maxGain: 3,
+      noiseGateAttenuation: 0.12,
+      noiseGateThreshold: 0.006,
+      targetLevel: 0.085
+    },
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 14,
+      pingInterval: 45000,
+      reconnect: true
+    },
+    sttLifecycle: "continuous",
+    turnDetection: {
+      qualityProfile: "noisy-room",
+      profile: "long-form",
+      silenceMs: 2100,
+      speechThreshold: 0.02,
+      transcriptStabilityMs: 1650
+    }
+  },
+  reliability: {
+    audioConditioning: {
+      enabled: true,
+      maxGain: 2.9,
+      noiseGateAttenuation: 0.08,
+      noiseGateThreshold: 0.005,
+      targetLevel: 0.08
+    },
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 14,
+      pingInterval: 45000,
+      reconnect: true
+    },
+    sttLifecycle: "continuous",
+    turnDetection: {
+      qualityProfile: "noisy-room",
+      profile: "long-form"
+    }
+  }
+};
+var resolveVoiceRuntimePreset = (name = "default") => {
+  const preset = PRESET_INPUTS[name];
+  return {
+    audioConditioning: resolveAudioConditioningConfig(preset.audioConditioning),
+    capture: {
+      channelCount: preset.capture?.channelCount ?? 1,
+      sampleRateHz: preset.capture?.sampleRateHz ?? 16000
+    },
+    connection: {
+      ...preset.connection
+    },
+    name,
+    sttLifecycle: preset.sttLifecycle ?? "continuous",
+    turnDetection: resolveTurnDetectionConfig(preset.turnDetection)
+  };
+};
+
+// src/client/controller.ts
+var createInitialState2 = (stream) => ({
+  assistantTexts: [...stream.assistantTexts],
+  error: stream.error,
+  isConnected: stream.isConnected,
+  isRecording: false,
+  partial: stream.partial,
+  recordingError: null,
+  sessionId: stream.sessionId,
+  scenarioId: stream.scenarioId,
+  status: stream.status,
+  turns: [...stream.turns]
+});
+var createVoiceController = (path, options = {}) => {
+  const preset = resolveVoiceRuntimePreset(options.preset);
+  const stream = createVoiceStream(path, {
+    ...preset.connection,
+    ...options.connection
+  });
+  let capture = null;
+  let state = createInitialState2(stream);
+  const subscribers = new Set;
+  const notify = () => {
+    for (const subscriber of subscribers) {
+      subscriber();
+    }
+  };
+  const sync = () => {
+    state = {
+      ...state,
+      assistantTexts: [...stream.assistantTexts],
+      error: stream.error,
+      isConnected: stream.isConnected,
+      partial: stream.partial,
+      sessionId: stream.sessionId,
+      scenarioId: stream.scenarioId,
+      status: stream.status,
+      turns: [...stream.turns]
+    };
+    if (options.autoStopOnComplete !== false && state.status === "completed" && state.isRecording) {
+      capture?.stop();
+      capture = null;
+      state = {
+        ...state,
+        isRecording: false
+      };
+    }
+    notify();
+  };
+  const unsubscribeStream = stream.subscribe(sync);
+  sync();
+  const ensureCapture = () => {
+    if (capture) {
+      return capture;
+    }
+    capture = createMicrophoneCapture({
+      channelCount: options.capture?.channelCount ?? preset.capture.channelCount,
+      onLevel: options.capture?.onLevel,
+      onAudio: (audio) => stream.sendAudio(audio),
+      sampleRateHz: options.capture?.sampleRateHz ?? preset.capture.sampleRateHz
+    });
+    return capture;
+  };
+  const stopRecording = () => {
+    capture?.stop();
+    capture = null;
+    state = {
+      ...state,
+      isRecording: false
+    };
+    notify();
+  };
+  const startRecording = async () => {
+    if (state.isRecording) {
+      return;
+    }
+    try {
+      state = {
+        ...state,
+        recordingError: null
+      };
+      notify();
+      await ensureCapture().start();
+      state = {
+        ...state,
+        isRecording: true
+      };
+      notify();
+    } catch (error) {
+      capture = null;
+      state = {
+        ...state,
+        isRecording: false,
+        recordingError: error instanceof Error ? error.message : String(error)
+      };
+      notify();
+      throw error;
+    }
+  };
+  const close = () => {
+    unsubscribeStream();
+    stopRecording();
+    stream.close();
+  };
+  return {
+    bindHTMX(bindingOptions) {
+      return bindVoiceHTMX(stream, bindingOptions);
+    },
+    close,
+    endTurn: () => stream.endTurn(),
+    get error() {
+      return state.error;
+    },
+    getServerSnapshot: () => state,
+    getSnapshot: () => state,
+    get isConnected() {
+      return state.isConnected;
+    },
+    get isRecording() {
+      return state.isRecording;
+    },
+    get partial() {
+      return state.partial;
+    },
+    get recordingError() {
+      return state.recordingError;
+    },
+    sendAudio: (audio) => stream.sendAudio(audio),
+    get sessionId() {
+      return state.sessionId;
+    },
+    get scenarioId() {
+      return state.scenarioId;
+    },
+    startRecording,
+    get status() {
+      return state.status;
+    },
+    stopRecording,
+    subscribe: (subscriber) => {
+      subscribers.add(subscriber);
+      return () => {
+        subscribers.delete(subscriber);
+      };
+    },
+    toggleRecording: async () => {
+      if (state.isRecording) {
+        stopRecording();
+        return;
+      }
+      await startRecording();
+    },
+    get turns() {
+      return state.turns;
+    },
+    get assistantTexts() {
+      return state.assistantTexts;
+    }
+  };
+};
+
+// src/react/useVoiceController.tsx
+var EMPTY_SNAPSHOT2 = {
+  assistantTexts: [],
+  error: null,
+  isConnected: false,
+  isRecording: false,
+  partial: "",
+  recordingError: null,
+  sessionId: "",
+  status: "idle",
+  turns: []
+};
+var useVoiceController = (path, options = {}) => {
+  const controllerRef = useRef2(null);
+  if (!controllerRef.current) {
+    controllerRef.current = createVoiceController(path, options);
+  }
+  const controller = controllerRef.current;
+  useEffect2(() => () => controller.close(), [controller]);
+  const snapshot = useSyncExternalStore2(controller.subscribe, controller.getSnapshot, controller.getServerSnapshot) ?? EMPTY_SNAPSHOT2;
+  return {
+    ...snapshot,
+    bindHTMX: controller.bindHTMX,
+    close: () => controller.close(),
+    endTurn: () => controller.endTurn(),
+    sendAudio: (audio) => controller.sendAudio(audio),
+    startRecording: () => controller.startRecording(),
+    stopRecording: () => controller.stopRecording(),
+    toggleRecording: () => controller.toggleRecording()
+  };
+};
 export {
-  useVoiceStream
+  useVoiceStream,
+  useVoiceController
 };