@absolutejs/voice 0.0.20 → 0.0.21

package/dist/client/index.d.ts

@@ -1,4 +1,5 @@
 export { createVoiceConnection } from './connection';
 export { createVoiceStream } from './createVoiceStream';
+export { createVoiceController } from './controller';
 export { bindVoiceHTMX } from './htmx';
 export { createMicrophoneCapture } from './microphone';

package/dist/client/index.js

@@ -76,24 +76,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) => {
@@ -136,6 +142,7 @@ var createVoiceConnection = (path, options = {}) => {
   const state = {
     isConnected: false,
     pendingMessages: [],
+    scenarioId: options.scenarioId ?? null,
     pingInterval: null,
     reconnectAttempts: 0,
     reconnectTimeout: null,
@@ -173,13 +180,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"
@@ -197,6 +205,7 @@ var createVoiceConnection = (path, options = {}) => {
       }
       if (parsed.type === "session") {
         state.sessionId = parsed.sessionId;
+        state.scenarioId = parsed.scenarioId ?? state.scenarioId;
       }
       listeners.forEach((listener) => listener(parsed));
     };
@@ -220,6 +229,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);
   };
@@ -243,9 +265,11 @@ var createVoiceConnection = (path, options = {}) => {
   };
   connect();
   return {
+    start,
     close,
     endTurn,
     getReadyState: () => state.ws?.readyState ?? WS_CLOSED,
+    getScenarioId: () => state.scenarioId ?? "",
     getSessionId: () => state.sessionId,
     send,
     sendAudio,
@@ -310,6 +334,7 @@ var serverMessageToAction = (message) => {
     case "session":
       return {
         sessionId: message.sessionId,
+        scenarioId: message.scenarioId,
         status: message.status,
         type: "session"
       };
@@ -328,6 +353,7 @@ var createInitialState = () => ({
   assistantTexts: [],
   error: null,
   isConnected: false,
+  scenarioId: null,
   partial: "",
   sessionId: null,
   status: "idle",
@@ -389,6 +415,7 @@ var createVoiceStreamStore = () => {
         state = {
           ...state,
           error: null,
+          scenarioId: action.scenarioId ?? state.scenarioId,
           isConnected: action.status === "active",
           sessionId: action.sessionId,
           status: action.status
@@ -422,6 +449,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());
   };
@@ -454,6 +487,10 @@ var createVoiceStream = (path, options = {}) => {
     get isConnected() {
       return store.getSnapshot().isConnected;
     },
+    get scenarioId() {
+      return store.getSnapshot().scenarioId;
+    },
+    start,
     get partial() {
       return store.getSnapshot().partial;
     },
@@ -527,6 +564,7 @@ var bindVoiceHTMX = (stream, options) => {
     unsubscribe();
   };
 };
+
 // src/client/microphone.ts
 var clampSample = (value) => Math.max(-1, Math.min(1, value));
 var floatTo16BitPCM = (input) => {
@@ -537,6 +575,22 @@ var floatTo16BitPCM = (input) => {
   }
   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;
@@ -584,7 +638,9 @@ var createMicrophoneCapture = (options) => {
     processorNode.onaudioprocess = (event) => {
       const channel = event.inputBuffer.getChannelData(0);
       const downsampled = downsampleBuffer(channel, audioContext?.sampleRate ?? 48000, options.sampleRateHz ?? 16000);
-      options.onAudio(floatTo16BitPCM(downsampled));
+      const pcm = floatTo16BitPCM(downsampled);
+      options.onLevel?.(getPcmLevel(pcm));
+      options.onAudio(pcm);
     };
     sourceNode.connect(processorNode);
     processorNode.connect(audioContext.destination);
@@ -594,6 +650,7 @@ var createMicrophoneCapture = (options) => {
     sourceNode?.disconnect();
     mediaStream?.getTracks().forEach((track) => track.stop());
     audioContext?.close();
+    options.onLevel?.(0);
     audioContext = null;
     mediaStream = null;
     processorNode = null;
@@ -601,8 +658,434 @@ var createMicrophoneCapture = (options) => {
   };
   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;
+    }
+  };
+};
 export {
   createVoiceStream,
+  createVoiceController,
   createVoiceConnection,
   createMicrophoneCapture,
   bindVoiceHTMX

package/dist/client/microphone.d.ts

@@ -1,7 +1,9 @@
+import type { VoiceCaptureOptions } from '../types';
 type MicrophoneCaptureOptions = {
-    channelCount?: 1 | 2;
+    channelCount?: VoiceCaptureOptions['channelCount'];
+    onLevel?: VoiceCaptureOptions['onLevel'];
     onAudio: (audio: Uint8Array) => void;
-    sampleRateHz?: number;
+    sampleRateHz?: VoiceCaptureOptions['sampleRateHz'];
 };
 type MicrophoneCapture = {
     start: () => Promise<void>;

package/dist/correction.d.ts

@@ -0,0 +1,16 @@
+import type { VoicePhraseHint, VoiceTurnCorrectionHandler } from './types';
+export type VoicePhraseHintCorrectionMatch = {
+    alias: string;
+    hint: VoicePhraseHint;
+};
+export type VoicePhraseHintCorrectionResult = {
+    changed: boolean;
+    matches: VoicePhraseHintCorrectionMatch[];
+    text: string;
+};
+export type VoicePhraseHintCorrectionOptions = {
+    provider?: string;
+    reason?: string;
+};
+export declare const applyPhraseHintCorrections: (text: string, phraseHints: VoicePhraseHint[]) => VoicePhraseHintCorrectionResult;
+export declare const createPhraseHintCorrectionHandler: (options?: VoicePhraseHintCorrectionOptions) => VoiceTurnCorrectionHandler;

package/dist/index.d.ts

@@ -2,4 +2,8 @@ export { voice } from './plugin';
 export { createVoiceMemoryStore } from './memoryStore';
 export { createVoiceSession } from './session';
 export { createId, createVoiceSessionRecord } from './store';
+export { applyPhraseHintCorrections, createPhraseHintCorrectionHandler } from './correction';
+export { conditionAudioChunk, resolveAudioConditioningConfig } from './audioConditioning';
+export { resolveVoiceRuntimePreset } from './presets';
+export { resolveTurnDetectionConfig, TURN_PROFILE_DEFAULTS } from './turnProfiles';
 export * from './types';