@airsurfer09/web-handsfree/dist/types/index.d.ts

A React package for integrating Convai's AI-powered voice assistants with LiveKit for real-time audio/video conversations

import { Room } from 'livekit-client';
/**
 * Audio processing settings for the microphone input.
 * These settings help optimize the audio quality and reduce interruptions.
 */
export interface AudioSettings {
    /** Enable echo cancellation to prevent audio feedback (default: true) */
    echoCancellation?: boolean;
    /** Enable noise suppression to reduce background noise (default: true) */
    noiseSuppression?: boolean;
    /** Enable automatic gain control for consistent volume (default: true) */
    autoGainControl?: boolean;
    /** Audio sample rate in Hz (default: 48000) */
    sampleRate?: number;
    /** Number of audio channels, 1 for mono, 2 for stereo (default: 1) */
    channelCount?: number;
}
/**
 * Configuration object for connecting to a Convai character.
 *
 * @example
 * ```tsx
 * const config: ConvaiConfig = {
 *   apiKey: 'your-api-key',
 *   characterId: 'your-character-id',
 *   enableVideo: true,
 *   enableAudio: true,
 *   audioSettings: {
 *     echoCancellation: true,
 *     noiseSuppression: true,
 *     autoGainControl: true,
 *     sampleRate: 48000,
 *   }
 * };
 * ```
 */
export interface ConvaiConfig {
    /** Your Convai API key from convai.com dashboard (required) */
    apiKey: string;
    /** The Character ID to connect to (required) */
    characterId: string;
    /** Custom Convai API URL (optional, defaults to production endpoint) */
    url?: string;
    /** Enable audio capability (default: true) */
    enableAudio?: boolean;
    /** Enable video capability (default: false) */
    enableVideo?: boolean;
    /** Audio processing settings for microphone input */
    audioSettings?: AudioSettings;
    /** Configuration for character actions and environmental context */
    actionConfig?: {
        /** List of action names the character can perform */
        actions: string[];
        /** Other characters present in the scene or conversation */
        characters: Array<{
            /** Character name */
            name: string;
            /** Character biography or description */
            bio: string;
        }>;
        /** Objects available in the scene or environment */
        objects: Array<{
            /** Object name */
            name: string;
            /** Object description or properties */
            description: string;
        }>;
        /** Name of the object the character is currently focused on */
        currentAttentionObject?: string;
    };
}
/**
 * Represents a single message in the chat conversation.
 * Different message types are used for various parts of the conversation flow.
 */
export interface ChatMessage {
    /** Unique identifier for the message */
    id: string;
    /**
     * Type of message:
     * - `user`: User's sent message
     * - `convai`: Character's response
     * - `user-transcription`: Real-time speech-to-text from user
     * - `bot-llm-text`: Character's LLM-generated text
     * - `emotion`: Character's emotional state
     * - `behavior-tree`: Behavior tree response
     * - `action`: Action execution
     * - `bot-emotion`: Bot emotional response
     * - `user-llm-text`: User text processed by LLM
     */
    type: 'user' | 'convai' | 'emotion' | 'behavior-tree' | 'action' | 'user-transcription' | 'bot-llm-text' | 'bot-emotion' | 'user-llm-text';
    /** The text content of the message */
    content: string;
    /** ISO timestamp string of when the message was created */
    timestamp: string;
    /** Whether this is the final version of the message (for streaming) */
    isFinal?: boolean;
}
/**
 * Represents the current state of the Convai client connection and activity.
 * Use this to provide UI feedback about the conversation state.
 *
 * @example
 * ```tsx
 * const { state } = convaiClient;
 *
 * if (state.isConnected) {
 *   console.log('Connected to character');
 * }
 *
 * if (state.isSpeaking) {
 *   console.log('Character is speaking');
 * }
 *
 * // Or use the combined state
 * console.log(state.agentState); // 'listening' | 'thinking' | 'speaking'
 * ```
 */
export interface ConvaiClientState {
    /** Whether the client is currently connected to Convai */
    isConnected: boolean;
    /** Whether a connection attempt is in progress */
    isConnecting: boolean;
    /** Whether the system is actively listening to user input */
    isListening: boolean;
    /** Whether the character is processing/thinking about a response */
    isThinking: boolean;
    /** Whether the character is currently speaking */
    isSpeaking: boolean;
    /**
     * Combined state indicator for the character's current activity.
     * Use this as a single source of truth for UI state.
     */
    agentState: 'disconnected' | 'connected' | 'listening' | 'thinking' | 'speaking';
}
import { AudioControls } from "../hooks/useAudioControls";
import { VideoControls } from "../hooks/useVideoControls";
import { ScreenShareControls } from "../hooks/useScreenShare";
/**
 * Main Convai client interface returned by useConvaiClient() hook.
 * Provides complete control over Convai character connections and interactions.
 *
 * @example
 * ```tsx
 * import { useConvaiClient } from '@convai/web-sdk';
 *
 * function App() {
 *   const convaiClient = useConvaiClient();
 *
 *   // Connect to character
 *   await convaiClient.connect({
 *     apiKey: 'your-api-key',
 *     characterId: 'your-character-id'
 *   });
 *
 *   // Send a message
 *   convaiClient.sendUserTextMessage('Hello!');
 *
 *   // Check state
 *   console.log(convaiClient.state.isConnected);
 * }
 * ```
 */
export interface ConvaiClient {
    /** Current connection and activity state of the client */
    state: ConvaiClientState;
    /** Connect to a Convai character with the provided configuration */
    connect: (config: ConvaiConfig) => Promise<void>;
    /** Disconnect from the current character session */
    disconnect: () => Promise<void>;
    /** Reset the session ID to start a new conversation (clears history) */
    resetSession: () => void;
    /** Internal LiveKit Room instance (for advanced usage) */
    room: Room;
    /** Current video track (for advanced usage) */
    videoTrack: any;
    /** Current audio track (for advanced usage) */
    audioTrack: any;
    /** Send a text message to the character */
    sendUserTextMessage: (text: string) => void;
    /**
     * Send a trigger message to invoke specific character actions or responses.
     * @param triggerName - Name of the trigger to invoke
     * @param triggerMessage - Optional message to accompany the trigger
     */
    sendTriggerMessage: (triggerName?: string, triggerMessage?: string) => void;
    /**
     * Update template keys in the character's context (e.g., user name, location).
     * These keys can be referenced in the character's responses.
     */
    updateTemplateKeys: (templateKeys: {
        [key: string]: string;
    }) => void;
    /**
     * Update dynamic information about the current context.
     * This helps the character understand the current situation.
     */
    updateDynamicInfo: (dynamicInfo: {
        text: string;
    }) => void;
    /** Array of all chat messages in the current conversation */
    chatMessages: ChatMessage[];
    /** Current real-time transcription of user speech */
    userTranscription: string;
    /** Unique session ID for the current character conversation */
    characterSessionId: string | null;
    /** Whether the bot is ready to receive messages (true after bot-ready message) */
    isBotReady: boolean;
    /** Audio control methods for managing microphone mute/unmute */
    audioControls: AudioControls;
    /** Video control methods for enabling/disabling camera */
    videoControls: VideoControls;
    /** Screen sharing control methods */
    screenShareControls: ScreenShareControls;
    /**
     * Toggle text-to-speech on or off.
     * When disabled, character responses won't be spoken aloud.
     */
    toggleTts: (enabled: boolean) => void;
    /** Current audio processing settings */
    audioSettings: AudioSettings;
    /** Update audio processing settings dynamically */
    updateAudioSettings: (settings: Partial<AudioSettings>) => Promise<void>;
}
//# sourceMappingURL=index.d.ts.map