@absolutejs/voice 0.0.20 → 0.0.21

package/dist/testing/sessionBenchmark.d.ts

@@ -1,13 +1,23 @@
-import type { STTAdapter } from '../types';
+import type { STTAdapter, VoiceAudioConditioningConfig, VoicePhraseHint, VoiceSTTFallbackConfig, VoiceSTTLifecycle, VoiceTurnCorrectionHandler, VoiceTurnProfile, VoiceTranscriptQuality } from '../types';
 import { type VoiceTranscriptAccuracy } from './accuracy';
 import type { VoiceTestFixture } from './fixtures';
 export type VoiceSessionBenchmarkScenario = VoiceTestFixture & {
     expectedTurnTexts: string[];
+    phraseHints?: VoicePhraseHint[];
     reconnectAtChunkIndex?: number;
     reconnectPauseMs?: number;
     silenceMs?: number;
     speechThreshold?: number;
+    transcriptStabilityMs?: number;
     transcriptThreshold?: number;
+    turnProfile?: VoiceTurnProfile;
+    audioConditioning?: VoiceAudioConditioningConfig;
+    sttLifecycle?: VoiceSTTLifecycle;
+};
+export type VoiceSessionBenchmarkTraceEntry = {
+    atMs: number;
+    data?: unknown;
+    phase: string;
 };
 export type VoiceSessionBenchmarkTurnResult = {
     actualText: string;
@@ -15,6 +25,7 @@ export type VoiceSessionBenchmarkTurnResult = {
     expectedText?: string;
     index: number;
     passes: boolean;
+    quality?: VoiceTranscriptQuality;
 };
 export type VoiceSessionBenchmarkScenarioResult = {
     actualTurns: string[];
@@ -28,6 +39,7 @@ export type VoiceSessionBenchmarkScenarioResult = {
     title: string;
     turnCountDelta: number;
     turnResults: VoiceSessionBenchmarkTurnResult[];
+    trace?: VoiceSessionBenchmarkTraceEntry[];
 };
 export type VoiceSessionBenchmarkSummary = {
     adapterId: string;
@@ -47,15 +59,68 @@ export type VoiceSessionBenchmarkReport = {
     scenarios: VoiceSessionBenchmarkScenarioResult[];
     summary: VoiceSessionBenchmarkSummary;
 };
-export declare const runVoiceSessionBenchmarkScenario: (adapter: STTAdapter, fixture: VoiceSessionBenchmarkScenario) => Promise<VoiceSessionBenchmarkScenarioResult>;
+export type VoiceSessionBenchmarkScenarioAggregate = {
+    averageElapsedMs: number;
+    averageWordErrorRate: number;
+    bestWordErrorRate: number;
+    fixtureId: string;
+    passCount: number;
+    passRate: number;
+    reconnectSuccessRate: number;
+    runCount: number;
+    tags: string[];
+    title: string;
+    worstWordErrorRate: number;
+};
+export type VoiceSessionBenchmarkSeriesSummary = {
+    adapterId: string;
+    averageElapsedMs: number;
+    averagePassRate: number;
+    averageWordErrorRate: number;
+    flakyScenarioCount: number;
+    generatedRunCount: number;
+    reconnectSuccessRate: number;
+    scenarioCount: number;
+    stableScenarioCount: number;
+    totalPassCount: number;
+    totalRunCount: number;
+};
+export type VoiceSessionBenchmarkSeriesReport = {
+    adapterId: string;
+    generatedAt: number;
+    runCount: number;
+    scenarios: VoiceSessionBenchmarkScenarioAggregate[];
+    summary: VoiceSessionBenchmarkSeriesSummary;
+};
+export declare const runVoiceSessionBenchmarkScenario: (adapter: STTAdapter, fixture: VoiceSessionBenchmarkScenario, options?: {
+    correctTurn?: VoiceTurnCorrectionHandler;
+    sttFallback?: VoiceSTTFallbackConfig;
+    trace?: boolean;
+}) => Promise<VoiceSessionBenchmarkScenarioResult>;
 export declare const summarizeVoiceSessionBenchmark: (adapterId: string, scenarios: VoiceSessionBenchmarkScenarioResult[]) => VoiceSessionBenchmarkSummary;
+export declare const summarizeVoiceSessionBenchmarkSeries: (input: {
+    adapterId: string;
+    reports: VoiceSessionBenchmarkReport[];
+}) => VoiceSessionBenchmarkSeriesReport;
 export declare const runVoiceSessionBenchmark: (input: {
     adapter: STTAdapter;
     adapterId: string;
+    correctTurn?: VoiceTurnCorrectionHandler;
     scenarios: VoiceSessionBenchmarkScenario[];
+    sttFallback?: VoiceSTTFallbackConfig;
+    trace?: boolean;
 }) => Promise<{
     adapterId: string;
     generatedAt: number;
     scenarios: VoiceSessionBenchmarkScenarioResult[];
     summary: VoiceSessionBenchmarkSummary;
 }>;
+export declare const runVoiceSessionBenchmarkSeries: (input: {
+    adapter: STTAdapter;
+    adapterId: string;
+    correctTurn?: VoiceTurnCorrectionHandler;
+    runs: number;
+    scenarios: VoiceSessionBenchmarkScenario[];
+    sttFallback?: VoiceSTTFallbackConfig;
+    trace?: boolean;
+}) => Promise<VoiceSessionBenchmarkSeriesReport>;

package/dist/testing/stt.d.ts

@@ -17,6 +17,7 @@ export type VoiceSTTAdapterHarnessResult = {
     finalEvents: VoiceFinalEvent[];
     finalText: string;
     partialEvents: VoicePartialEvent[];
+    speechEndedAt: number;
     startedAt: number;
 };
 export declare const runSTTAdapterFixture: (adapter: STTAdapter, fixture: VoiceTestFixture, options?: VoiceSTTAdapterHarnessOptions) => Promise<VoiceSTTAdapterHarnessResult>;

package/dist/turnDetection.d.ts

@@ -2,4 +2,8 @@ import type { AudioChunk, Transcript } from './types';
 export declare const DEFAULT_SILENCE_MS = 700;
 export declare const DEFAULT_SPEECH_THRESHOLD = 0.015;
 export declare const measureAudioLevel: (audio: AudioChunk) => number;
-export declare const buildTurnText: (transcripts: Transcript[], partialText: string) => string;
+export declare const selectPreferredTranscriptText: (currentText: string, nextText: string) => string;
+export declare const buildTurnText: (transcripts: Transcript[], partialText: string, options?: {
+    partialEndedAtMs?: number;
+    partialStartedAtMs?: number;
+}) => string;

package/dist/turnProfiles.d.ts

@@ -0,0 +1,6 @@
+import type { VoiceResolvedTurnDetectionConfig, VoiceTurnDetectionConfig, VoiceTurnQualityProfile, VoiceTurnProfile } from './types';
+export declare const TURN_PROFILE_DEFAULTS: Record<VoiceTurnProfile, Omit<VoiceResolvedTurnDetectionConfig, 'profile'>>;
+export declare const QUALITY_PROFILE_DEFAULTS: Record<VoiceTurnQualityProfile, Partial<VoiceResolvedTurnDetectionConfig>>;
+export declare const DEFAULT_TURN_PROFILE: VoiceTurnProfile;
+export declare const DEFAULT_QUALITY_PROFILE: VoiceTurnQualityProfile;
+export declare const resolveTurnDetectionConfig: (config?: VoiceTurnDetectionConfig) => VoiceResolvedTurnDetectionConfig;

package/dist/types.d.ts

@@ -6,6 +6,12 @@ export type AudioFormat = {
     channels: 1 | 2;
 };
 export type AudioChunk = ArrayBuffer | ArrayBufferView;
+export type VoicePhraseHint = {
+    text: string;
+    aliases?: string[];
+    boost?: number;
+    metadata?: Record<string, unknown>;
+};
 export type Transcript = {
     id: string;
     text: string;
@@ -16,6 +22,39 @@ export type Transcript = {
     endedAtMs?: number;
     vendor?: string;
 };
+export type VoiceTranscriptQuality = {
+    averageConfidence?: number;
+    confidenceSampleCount: number;
+    correction?: VoiceTurnCorrectionDiagnostics;
+    fallbackUsed: boolean;
+    finalTranscriptCount: number;
+    fallback?: VoiceFallbackDiagnostics;
+    partialTranscriptCount: number;
+    selectedTranscriptCount: number;
+    source: 'fallback' | 'primary';
+};
+export type VoiceTurnCorrectionDiagnostics = {
+    attempted: boolean;
+    changed: boolean;
+    correctedText: string;
+    metadata?: Record<string, unknown>;
+    originalText: string;
+    provider?: string;
+    reason?: string;
+};
+export type VoiceFallbackSelectionReason = 'fallback-empty' | 'primary-empty' | 'word-count-margin' | 'confidence-margin' | 'word-count-tiebreak' | 'kept-primary';
+export type VoiceFallbackDiagnostics = {
+    attempted: boolean;
+    fallbackConfidence?: number;
+    fallbackText?: string;
+    fallbackWordCount?: number;
+    primaryConfidence: number;
+    primaryText: string;
+    primaryWordCount: number;
+    selected: boolean;
+    selectionReason: VoiceFallbackSelectionReason;
+    trigger: 'empty-turn' | 'low-confidence' | 'empty-or-low-confidence' | 'always';
+};
 export type VoicePartialEvent = {
     type: 'partial';
     transcript: Transcript;
@@ -58,6 +97,7 @@ export type STTAdapterSession = {
 export type STTAdapterOpenOptions = {
     sessionId: string;
     format: AudioFormat;
+    phraseHints?: VoicePhraseHint[];
     signal?: AbortSignal;
 };
 export type STTAdapter<TOptions extends STTAdapterOpenOptions = STTAdapterOpenOptions> = {
@@ -99,6 +139,7 @@ export type RealtimeAdapterSession = {
 export type RealtimeAdapterOpenOptions = {
     sessionId: string;
     format: AudioFormat;
+    phraseHints?: VoicePhraseHint[];
     signal?: AbortSignal;
 };
 export type RealtimeAdapter<TOptions extends RealtimeAdapterOpenOptions = RealtimeAdapterOpenOptions> = {
@@ -109,6 +150,7 @@ export type VoiceSessionStatus = 'active' | 'reconnecting' | 'completed' | 'fail
 export type VoiceTurnRecord<TResult = unknown> = {
     id: string;
     text: string;
+    quality?: VoiceTranscriptQuality;
     transcripts: Transcript[];
     assistantText?: string;
     committedAt: number;
@@ -123,8 +165,13 @@ export type VoiceSessionRecord<TMeta = Record<string, never>, TResult = unknown>
     currentTurn: {
         transcripts: Transcript[];
         partialText: string;
+        partialStartedAt?: number;
+        partialEndedAt?: number;
         finalText: string;
         lastAudioAt?: number;
+        lastSpeechAt?: number;
+        lastTranscriptAt?: number;
+        silenceStartedAt?: number;
     };
     turns: VoiceTurnRecord<TResult>[];
     committedTurnIds: string[];
@@ -132,7 +179,14 @@ export type VoiceSessionRecord<TMeta = Record<string, never>, TResult = unknown>
         attempts: number;
         lastDisconnectAt?: number;
     };
+    lastCommittedTurn?: {
+        signature: string;
+        text: string;
+        transcriptIds: string[];
+        committedAt: number;
+    };
     metadata?: TMeta;
+    scenarioId?: string;
 };
 export type VoiceSessionSummary = {
     id: string;
@@ -153,6 +207,59 @@ export type VoiceReconnectConfig = {
     timeout?: number;
     maxAttempts?: number;
 };
+export type VoiceRuntimePreset = 'default' | 'chat' | 'guided-intake' | 'dictation' | 'noisy-room' | 'reliability';
+export type VoiceSTTLifecycle = 'continuous' | 'turn-scoped';
+export type VoiceTurnProfile = 'fast' | 'balanced' | 'long-form';
+export type VoiceTurnQualityProfile = 'general' | 'accent-heavy' | 'noisy-room' | 'short-command';
+export type VoiceTurnFallbackTrigger = 'empty-turn' | 'low-confidence' | 'empty-or-low-confidence' | 'always';
+export type VoiceSTTFallbackConfig = {
+    adapter: STTAdapter;
+    trigger?: VoiceTurnFallbackTrigger;
+    confidenceThreshold?: number;
+    minTextLength?: number;
+    replayWindowMs?: number;
+    settleMs?: number;
+    completionTimeoutMs?: number;
+    maxAttemptsPerTurn?: number;
+};
+export type VoiceResolvedSTTFallbackConfig = {
+    adapter: STTAdapter;
+    trigger: VoiceTurnFallbackTrigger;
+    confidenceThreshold: number;
+    minTextLength: number;
+    replayWindowMs: number;
+    settleMs: number;
+    completionTimeoutMs: number;
+    maxAttemptsPerTurn: number;
+};
+export type VoiceTurnDetectionConfig = {
+    profile?: VoiceTurnProfile;
+    qualityProfile?: VoiceTurnQualityProfile;
+    silenceMs?: number;
+    speechThreshold?: number;
+    transcriptStabilityMs?: number;
+};
+export type VoiceResolvedTurnDetectionConfig = {
+    qualityProfile: VoiceTurnQualityProfile;
+    profile: VoiceTurnProfile;
+    silenceMs: number;
+    speechThreshold: number;
+    transcriptStabilityMs: number;
+};
+export type VoiceAudioConditioningConfig = {
+    enabled?: boolean;
+    targetLevel?: number;
+    maxGain?: number;
+    noiseGateThreshold?: number;
+    noiseGateAttenuation?: number;
+};
+export type VoiceResolvedAudioConditioningConfig = {
+    enabled: true;
+    targetLevel: number;
+    maxGain: number;
+    noiseGateThreshold: number;
+    noiseGateAttenuation: number;
+};
 export type VoiceSocket = {
     send: (data: string | Uint8Array | ArrayBuffer) => void | Promise<void>;
     close: (code?: number, reason?: string) => void | Promise<void>;
@@ -173,6 +280,26 @@ export type VoiceRouteResult<TResult = unknown> = {
     result?: TResult;
     assistantText?: string;
 };
+export type VoiceTurnCorrectionResult = string | {
+    text: string;
+    reason?: string;
+    provider?: string;
+    metadata?: Record<string, unknown>;
+};
+export type VoiceTurnCorrectionHandler<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = (input: {
+    api: VoiceSessionHandle<TContext, TSession, TResult>;
+    context: TContext;
+    fallback?: VoiceFallbackDiagnostics;
+    phraseHints: VoicePhraseHint[];
+    session: TSession;
+    text: string;
+    transcripts: Transcript[];
+}) => Promise<VoiceTurnCorrectionResult | void> | VoiceTurnCorrectionResult | void;
+export type VoicePhraseHintResolver<TContext = unknown> = (input: {
+    context: TContext;
+    scenarioId?: string;
+    sessionId: string;
+}) => Promise<VoicePhraseHint[] | void> | VoicePhraseHint[] | void;
 export type VoiceOnTurnObjectHandler<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = (input: {
     context: TContext;
     session: TSession;
@@ -186,6 +313,7 @@ export type VoiceRouteConfig<TContext = unknown, TSession extends VoiceSessionRe
         session: TSession;
         api: VoiceSessionHandle<TContext, TSession, TResult>;
     }) => Promise<void> | void;
+    correctTurn?: VoiceTurnCorrectionHandler<TContext, TSession, TResult>;
     onTurn: VoiceOnTurnHandler<TContext, TSession, TResult>;
     onComplete: (input: {
         context: TContext;
@@ -203,16 +331,24 @@ export type VoiceRouteConfig<TContext = unknown, TSession extends VoiceSessionRe
 export type VoiceNormalizedRouteConfig<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = Omit<VoiceRouteConfig<TContext, TSession, TResult>, 'onTurn'> & {
     onTurn: VoiceOnTurnObjectHandler<TContext, TSession, TResult>;
 };
+export type VoiceScenario = {
+    id: string;
+    name?: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+};
 export type VoicePluginConfig<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     path: string;
+    phraseHints?: VoicePhraseHint[] | VoicePhraseHintResolver<TContext>;
+    preset?: VoiceRuntimePreset;
     stt: STTAdapter;
+    sttFallback?: VoiceSTTFallbackConfig;
+    sttLifecycle?: VoiceSTTLifecycle;
     tts?: TTSAdapter;
     session: VoiceSessionStore<NoInfer<TSession>>;
     reconnect?: VoiceReconnectConfig;
-    turnDetection?: {
-        silenceMs?: number;
-        speechThreshold?: number;
-    };
+    turnDetection?: VoiceTurnDetectionConfig;
+    audioConditioning?: VoiceAudioConditioningConfig;
     logger?: VoiceLogger;
     htmx?: boolean | VoiceHTMXConfig<TSession, NoInfer<TResult>>;
 } & VoiceRouteConfig<TContext, TSession, TResult>;
@@ -221,12 +357,14 @@ export type CreateVoiceSessionOptions<TContext = unknown, TSession extends Voice
     context: TContext;
     socket: VoiceSocket;
     stt: STTAdapter;
+    sttFallback?: VoiceResolvedSTTFallbackConfig;
     store: VoiceSessionStore<TSession>;
     reconnect: Required<VoiceReconnectConfig>;
-    turnDetection: {
-        silenceMs: number;
-        speechThreshold: number;
-    };
+    phraseHints?: VoicePhraseHint[];
+    scenarioId?: string;
+    sttLifecycle: VoiceSTTLifecycle;
+    turnDetection: VoiceResolvedTurnDetectionConfig;
+    audioConditioning?: VoiceResolvedAudioConditioningConfig;
     route: VoiceNormalizedRouteConfig<TContext, TSession, TResult>;
     logger?: VoiceLogger;
 };
@@ -234,6 +372,7 @@ export type CreateVoiceSession = <TContext = unknown, TSession extends VoiceSess
 export type VoiceClientStartMessage = {
     type: 'start';
     sessionId?: string;
+    scenarioId?: string;
 };
 export type VoiceClientEndTurnMessage = {
     type: 'end_turn';
@@ -250,6 +389,7 @@ export type VoiceServerSessionMessage = {
     type: 'session';
     sessionId: string;
     status: VoiceSessionStatus;
+    scenarioId?: string;
 };
 export type VoiceServerPartialMessage = {
     type: 'partial';
@@ -283,14 +423,27 @@ export type VoiceServerPongMessage = {
 export type VoiceServerMessage<TResult = unknown> = VoiceServerSessionMessage | VoiceServerPartialMessage | VoiceServerFinalMessage | VoiceServerTurnMessage<TResult> | VoiceServerAssistantMessage | VoiceServerCompleteMessage | VoiceServerErrorMessage | VoiceServerPongMessage;
 export type VoiceConnectionOptions = {
     protocols?: string[];
+    scenarioId?: string;
     reconnect?: boolean;
     maxReconnectAttempts?: number;
     pingInterval?: number;
     sessionId?: string;
 };
+export type VoiceCaptureOptions = {
+    channelCount?: 1 | 2;
+    onLevel?: (level: number) => void;
+    sampleRateHz?: number;
+};
+export type VoiceControllerOptions = {
+    preset?: VoiceRuntimePreset;
+    connection?: VoiceConnectionOptions;
+    capture?: VoiceCaptureOptions;
+    autoStopOnComplete?: boolean;
+};
 export type VoiceHTMXRenderInput<TResult = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord> = {
     assistantTexts: string[];
     partial: string;
+    scenarioId?: string;
     result?: TResult;
     session?: TSession;
     sessionId?: string;
@@ -322,6 +475,7 @@ export type VoiceHTMXOptions<TSession extends VoiceSessionRecord = VoiceSessionR
 export type VoiceHTMXConfig<TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = VoiceHTMXRenderer<TSession, TResult> | VoiceHTMXOptions<TSession, TResult>;
 export type VoiceStreamState<TResult = unknown> = {
     sessionId: string | null;
+    scenarioId: string | null;
     status: VoiceSessionStatus | 'idle';
     partial: string;
     turns: VoiceTurnRecord<TResult>[];
@@ -331,6 +485,10 @@ export type VoiceStreamState<TResult = unknown> = {
 };
 export type VoiceStream<TResult = unknown> = {
     close: () => void;
+    start: (input?: {
+        scenarioId?: string;
+        sessionId?: string;
+    }) => Promise<void>;
     endTurn: () => void;
     error: string | null;
     getServerSnapshot: () => VoiceStreamState<TResult>;
@@ -339,8 +497,39 @@ export type VoiceStream<TResult = unknown> = {
     partial: string;
     sendAudio: (audio: Uint8Array | ArrayBuffer) => void;
     sessionId: string | null;
+    scenarioId: string | null;
+    status: VoiceSessionStatus | 'idle';
+    subscribe: (subscriber: () => void) => () => void;
+    turns: VoiceTurnRecord<TResult>[];
+    assistantTexts: string[];
+};
+export type VoiceControllerState<TResult = unknown> = VoiceStreamState<TResult> & {
+    isRecording: boolean;
+    recordingError: string | null;
+};
+export type VoiceController<TResult = unknown> = {
+    bindHTMX: (options: VoiceHTMXBindingOptions) => () => void;
+    close: () => void;
+    endTurn: () => void;
+    start: (input?: {
+        scenarioId?: string;
+        sessionId?: string;
+    }) => Promise<void>;
+    error: string | null;
+    getServerSnapshot: () => VoiceControllerState<TResult>;
+    getSnapshot: () => VoiceControllerState<TResult>;
+    isConnected: boolean;
+    isRecording: boolean;
+    partial: string;
+    recordingError: string | null;
+    sendAudio: (audio: Uint8Array | ArrayBuffer) => void;
+    sessionId: string | null;
+    scenarioId: string | null;
+    startRecording: () => Promise<void>;
     status: VoiceSessionStatus | 'idle';
+    stopRecording: () => void;
     subscribe: (subscriber: () => void) => () => void;
+    toggleRecording: () => Promise<void>;
     turns: VoiceTurnRecord<TResult>[];
     assistantTexts: string[];
 };
@@ -353,6 +542,7 @@ export type VoiceHTMXBindingOptions = {
 export type VoiceStoreAction<TResult = unknown> = {
     type: 'session';
     sessionId: string;
+    scenarioId?: string;
     status: VoiceSessionStatus;
 } | {
     type: 'partial';

package/dist/vue/index.d.ts

@@ -1 +1,2 @@
 export { useVoiceStream } from './useVoiceStream';
+export { useVoiceController } from './useVoiceController';