@volley/recognition-client-sdk 0.1.200

package/src/vgf-recognition-mapper.ts

@@ -0,0 +1,225 @@
+/**
+ * VGF Recognition Mapper
+ *
+ * Maps between the existing recognition client types and the simplified VGF state.
+ * This provides a clean abstraction layer for game developers.
+ */
+
+import {
+    RecognitionState,
+    RecordingStatus,
+    TranscriptionStatus,
+    createInitialRecognitionState
+} from './vgf-recognition-state.js';
+import {
+    ClientState,
+    IRecognitionClientConfig
+} from './recognition-client.types.js';
+import {
+    TranscriptionResultV1,
+    MetadataResultV1,
+    ErrorResultV1,
+    ASRRequestConfig
+} from '@recog/shared-types';
+
+/**
+ * Maps ClientState to RecordingStatus for VGF state
+ */
+export function mapClientStateToRecordingStatus(clientState: ClientState): string {
+    switch (clientState) {
+        case ClientState.INITIAL:
+        case ClientState.CONNECTING:
+        case ClientState.CONNECTED:
+            return RecordingStatus.NOT_READY;
+
+        case ClientState.READY:
+            // Ready to record, but not recording yet
+            return RecordingStatus.READY;
+
+        case ClientState.STOPPING:
+        case ClientState.STOPPED:
+        case ClientState.FAILED:
+            return RecordingStatus.FINISHED;
+
+        default:
+            return RecordingStatus.NOT_READY;
+    }
+}
+
+/**
+ * Creates a VGF state from transcription result
+ */
+export function mapTranscriptionResultToState(
+    currentState: RecognitionState,
+    result: TranscriptionResultV1,
+    isRecording: boolean
+): RecognitionState {
+    const newState = { ...currentState };
+
+    // Update recording status if actively recording
+    if (isRecording && currentState.startRecordingStatus !== RecordingStatus.FINISHED) {
+        newState.startRecordingStatus = RecordingStatus.RECORDING;
+
+        // Set start timestamp on first audio
+        if (!newState.startRecordingTimestamp) {
+            newState.startRecordingTimestamp = new Date().toISOString();
+        }
+    }
+
+    // Update transcription status
+    if (!result.is_finished) {
+        // Has pending transcript - STEP 2 support
+        newState.transcriptionStatus = TranscriptionStatus.IN_PROGRESS;
+
+        // Direct copy of pending transcript without any combination
+        newState.pendingTranscript = result.pendingTranscript || "";
+
+        // Direct copy of pending confidence
+        if (result.pendingTranscriptConfidence !== undefined) {
+            newState.pendingConfidence = result.pendingTranscriptConfidence;
+        }
+
+        // Also update final transcript if we have it (even if not finished)
+        if (result.finalTranscript) {
+            newState.finalTranscript = result.finalTranscript;
+            if (result.finalTranscriptConfidence !== undefined) {
+                newState.finalConfidence = result.finalTranscriptConfidence;
+            }
+        }
+    } else {
+        // Transcription is finished
+        newState.transcriptionStatus = TranscriptionStatus.FINALIZED;
+        newState.finalTranscript = result.finalTranscript || "";
+        if (result.finalTranscriptConfidence !== undefined) {
+            newState.finalConfidence = result.finalTranscriptConfidence;
+        }
+        newState.finalTranscriptionTimestamp = new Date().toISOString();
+
+        // Clear pending when we have final
+        newState.pendingTranscript = "";
+        newState.pendingConfidence = undefined;
+    }
+
+    return newState;
+}
+
+/**
+ * Maps metadata result to update state timestamps
+ */
+export function mapMetadataToState(
+    currentState: RecognitionState,
+    metadata: MetadataResultV1
+): RecognitionState {
+    const newState = { ...currentState };
+
+    // Update final recording timestamp when metadata arrives
+    if (!newState.finalRecordingTimestamp) {
+        newState.finalRecordingTimestamp = new Date().toISOString();
+    }
+
+    // Recording is finished when metadata arrives
+    newState.startRecordingStatus = RecordingStatus.FINISHED;
+
+    return newState;
+}
+
+/**
+ * Maps error to state
+ */
+export function mapErrorToState(
+    currentState: RecognitionState,
+    error: ErrorResultV1
+): RecognitionState {
+    return {
+        ...currentState,
+        transcriptionStatus: TranscriptionStatus.ERROR,
+        startRecordingStatus: RecordingStatus.FINISHED,
+        finalRecordingTimestamp: new Date().toISOString()
+    };
+}
+
+/**
+ * Creates initial VGF state from client config
+ */
+export function createVGFStateFromConfig(config: IRecognitionClientConfig): RecognitionState {
+    const audioUtteranceId = config.audioUtteranceId || generateUUID();
+    const state = createInitialRecognitionState(audioUtteranceId);
+
+    // Store ASR config as JSON if provided
+    if (config.asrRequestConfig) {
+        state.asrConfig = JSON.stringify(config.asrRequestConfig);
+    }
+
+    return state;
+}
+
+/**
+ * Updates state when recording stops
+ */
+export function updateStateOnStop(currentState: RecognitionState): RecognitionState {
+    return {
+        ...currentState,
+        startRecordingStatus: RecordingStatus.FINISHED,
+        finalRecordingTimestamp: new Date().toISOString()
+    };
+}
+
+/**
+ * Updates state when client becomes ready
+ */
+export function updateStateOnReady(currentState: RecognitionState): RecognitionState {
+    return {
+        ...currentState,
+        startRecordingStatus: RecordingStatus.READY
+    };
+}
+
+/**
+ * Parses function call from transcript (STEP 3 support)
+ * This is a placeholder - actual implementation would use NLP/LLM
+ */
+export function extractFunctionCallFromTranscript(
+    transcript: string,
+    gameContext?: any
+): { metadata?: string; confidence?: number } | null {
+    // This would be replaced with actual function call extraction logic
+    // For example, using an LLM to parse intent from the transcript
+    // and map it to game actions
+
+    // Example stub implementation:
+    const lowerTranscript = transcript.toLowerCase();
+
+    // Simple pattern matching for demo
+    if (lowerTranscript.includes("play") && lowerTranscript.includes("artist")) {
+        return {
+            metadata: JSON.stringify({ action: "play", target: "artist" }),
+            confidence: 0.8
+        };
+    }
+
+    return null;
+}
+
+/**
+ * Updates state with function call results (STEP 3)
+ */
+export function updateStateWithFunctionCall(
+    currentState: RecognitionState,
+    functionCall: { metadata?: string; confidence?: number }
+): RecognitionState {
+    return {
+        ...currentState,
+        functionCallMetadata: functionCall.metadata,
+        functionCallConfidence: functionCall.confidence,
+        finalFunctionCallTimestamp: new Date().toISOString()
+    };
+}
+
+// Helper function to generate UUID (simplified version)
+function generateUUID(): string {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+        const r = Math.random() * 16 | 0;
+        const v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}

package/src/vgf-recognition-state.ts

@@ -0,0 +1,89 @@
+import { z } from "zod"
+
+/**
+ * VGF-style state schema for game-side recognition state/results management.
+ *
+ * This schema provides a standardized way for game developers to manage
+ * voice recognition state and results in their applications. It supports:
+ *
+ * STEP 1: Basic transcription flow
+ * STEP 2: Mic auto-stop upon correct answer (using partial transcripts)
+ * STEP 3: Semantic/function-call outcomes for game actions
+ *
+ * Ideally this should be part of a more centralized shared type library to free
+ * game developers and provide helper functions (VGF? Platform SDK?).
+ */
+export const RecognitionVGFStateSchema = z.object({
+    // Core STT state
+    audioUtteranceId: z.string(),
+    startRecordingStatus: z.string().optional(), // "NOT_READY", "READY", "RECORDING", "FINISHED". States follow this order.
+    // Streaming should only start when "READY". Other states control mic UI and recording.
+    transcriptionStatus: z.string().optional(), // "NOT_STARTED", "IN_PROGRESS", "FINALIZED", "ERROR"
+    finalTranscript: z.string().optional(), // Full finalized transcript for the utterance. Will not change.
+    finalConfidence: z.number().optional(),
+
+    // Tracking-only metadata
+    asrConfig: z.string().optional(), // Json format of the ASR config
+    startRecordingTimestamp: z.string().optional(), // Start of recording. Immutable after set.
+    finalRecordingTimestamp: z.string().optional(), // End of recording. Immutable after set. Transcription may still be in progress.
+    finalTranscriptionTimestamp: z.string().optional(), // When the final transcript was produced. Immutable after set.
+
+    // STEP 2: Support for mic auto-stop upon correct answer
+    pendingTranscript: z.string().optional().default(""), // Non-final transcript that may change (matches existing naming)
+    pendingConfidence: z.number().optional(),
+
+    // STEP 3: Support for semantic/function-call outcomes
+    functionCallMetadata: z.string().optional(), // Function call metadata in JSON, e.g. "{artist: true, title: true}"
+    functionCallConfidence: z.number().optional(), // Confidence score for the function call.
+    finalFunctionCallTimestamp: z.string().optional(), // When the final action after interpreting the transcript was taken. Immutable.
+
+    // Support for prompt slot mapping - passed to recognition context when present
+    promptSlotMap: z.record(z.string(), z.array(z.string())).optional(), // Optional map of slot names to prompt values for recognition context
+})
+
+export type RecognitionState = z.infer<typeof RecognitionVGFStateSchema>
+
+// Status constants for better type safety and consistency
+export const RecordingStatus = {
+    NOT_READY: "NOT_READY",
+    READY: "READY",
+    RECORDING: "RECORDING",
+    FINISHED: "FINISHED",
+} as const
+
+export type RecordingStatusType = typeof RecordingStatus[keyof typeof RecordingStatus]
+
+export const TranscriptionStatus = {
+    NOT_STARTED: "NOT_STARTED",
+    IN_PROGRESS: "IN_PROGRESS",
+    FINALIZED: "FINALIZED",
+    ERROR: "ERROR",
+} as const
+
+export type TranscriptionStatusType = typeof TranscriptionStatus[keyof typeof TranscriptionStatus]
+
+// Helper function to create initial state
+export function createInitialRecognitionState(audioUtteranceId: string): RecognitionState {
+    return {
+        audioUtteranceId,
+        startRecordingStatus: RecordingStatus.NOT_READY,
+        transcriptionStatus: TranscriptionStatus.NOT_STARTED,
+        pendingTranscript: "",
+    }
+}
+
+// Helper function to validate state transitions
+export function isValidRecordingStatusTransition(from: string | undefined, to: string): boolean {
+    const statusOrder = [
+        RecordingStatus.NOT_READY,
+        RecordingStatus.READY,
+        RecordingStatus.RECORDING,
+        RecordingStatus.FINISHED,
+    ]
+
+    const fromIndex = from ? statusOrder.indexOf(from as RecordingStatusType) : -1
+    const toIndex = statusOrder.indexOf(to as RecordingStatusType)
+
+    // Can only move forward in the status order
+    return toIndex > fromIndex && toIndex !== -1
+}