Configuration

Configuration objects for AI providers, text-to-speech, speech-to-text, animations, and UI settings.

DefaultAIConfig

Default AI provider configuration with support for Chrome AI, OpenAI, and Ollama.

Structure

const DefaultAIConfig = {
  provider: 'chrome-ai', // 'chrome-ai' | 'openai' | 'ollama'
  
  chromeAi: {
    temperature: 1.0,
    topK: 3,
    outputLanguage: 'en', // 'en' | 'es' | 'ja'
    enableImageSupport: true,
    enableAudioSupport: true,
    systemPromptType: 'default',
    systemPrompt: '',
  },
  
  openai: {
    apiKey: '',
    model: 'gpt-4-turbo-preview',
    temperature: 0.7,
    maxTokens: 2000,
    enableImageSupport: true,
    enableAudioSupport: true,
    systemPromptType: 'default',
    systemPrompt: '',
  },
  
  ollama: {
    endpoint: 'http://localhost:11434',
    model: 'llama2',
    temperature: 0.7,
    maxTokens: 2000,
    enableImageSupport: true,
    enableAudioSupport: true,
    systemPromptType: 'default',
    systemPrompt: '',
  },
  
  systemPrompt: 'You are a helpful virtual assistant.',
  
  aiFeatures: {
    translator: {
      enabled: true,
      defaultTargetLanguage: 'en',
    },
    languageDetector: {
      enabled: true,
    },
    summarizer: {
      enabled: true,
      defaultType: 'tldr',
      defaultFormat: 'plain-text',
      defaultLength: 'medium',
    },
    rewriter: {
      enabled: true,
      defaultTone: 'as-is',
      defaultFormat: 'as-is',
      defaultLength: 'as-is',
    },
    writer: {
      enabled: true,
      defaultTone: 'neutral',
      defaultFormat: 'plain-text',
      defaultLength: 'medium',
    },
  },
};

Chrome AI Settings

number

Sampling temperature (0.0-2.0). Higher = more random.

number

default:3

Top-K sampling. Lower = more focused, higher = more diverse.

string

default:"en"

Model output language: ‘en’ | ‘es’ | ‘ja’

boolean

default:true

Enable multi-modal image support (requires Chrome AI multimodal flag)

boolean

default:true

Enable multi-modal audio support (requires Chrome AI multimodal flag)

string

default:"default"

Personality type from PromptConfig.systemPrompts or ‘custom’

string

default:""

Custom system prompt (only used when systemPromptType is ‘custom’)

OpenAI Settings

string

required

OpenAI API key

string

default:"gpt-4-turbo-preview"

Model name: ‘gpt-4’ | ‘gpt-4-turbo-preview’ | ‘gpt-4o’ | ‘gpt-3.5-turbo’

number

Sampling temperature (0.0-2.0)

number

default:2000

Maximum tokens in response

boolean

default:true

Enable multi-modal image support (GPT-4 Vision)

boolean

default:true

Enable audio transcription via Whisper

Ollama Settings

string

default:"http://localhost:11434"

Ollama server endpoint

string

default:"llama2"

Model name (e.g., ‘llama2’, ‘mistral’, ‘mixtral’, ‘llava’)

number

Sampling temperature

number

default:2000

Maximum tokens in response

boolean

default:true

Enable multi-modal image support (requires vision model like LLaVA)

DefaultTTSConfig

Default Text-to-Speech configuration with support for Kokoro, OpenAI TTS, and generic APIs.

Structure

const DefaultTTSConfig = {
  enabled: false,
  provider: 'kokoro', // 'kokoro' | 'openai' | 'openai-compatible'
  
  kokoro: {
    modelId: 'onnx-community/Kokoro-82M-v1.0-ONNX',
    voice: 'af_heart',
    speed: 1.0,
    device: 'auto', // 'auto' | 'webgpu' | 'wasm'
    keepModelLoaded: true,
  },
  
  openai: {
    apiKey: '',
    model: 'tts-1', // 'tts-1' | 'tts-1-hd'
    voice: 'nova', // 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer'
    speed: 1.0,
  },
  
  'openai-compatible': {
    endpoint: 'http://localhost:8000',
    apiKey: '',
    model: 'tts',
    voice: 'default',
    speed: 1.0,
  },
  
  chunkSize: 500,
  minChunkSize: 100,
};

Kokoro TTS Settings

string

default:"onnx-community/Kokoro-82M-v1.0-ONNX"

HuggingFace model ID for Kokoro TTS

string

default:"af_heart"

Voice ID. Available voices:

Female American: af_heart, af_alloy, af_aoede, af_bella, af_jessica, af_kore, af_nicole, af_nova, af_river, af_sarah, af_sky
Male American: am_adam, am_echo, am_eric, am_fenrir, am_liam, am_michael, am_onyx, am_puck, am_santa
Female British: bf_alice, bf_emma, bf_isabella, bf_lily
Male British: bm_daniel, bm_fable, bm_george, bm_lewis

number

Speech speed multiplier (0.25-4.0)

string

default:"auto"

Inference backend:

'auto': WebGPU if available, else WASM
'webgpu': GPU acceleration (2-10x faster, fp32/fp16 dtype)
'wasm': CPU fallback (universal compatibility, q8 dtype)

boolean

default:true

Keep model in memory between generations (faster but uses ~163MB RAM)

OpenAI TTS Settings

string

required

OpenAI API key

string

default:"tts-1"

TTS model: ‘tts-1’ (fast) | ‘tts-1-hd’ (high quality)

string

default:"nova"

number

Speech speed (0.25-4.0)

Chunking Settings

number

default:500

Target chunk size in characters for streaming TTS

number

default:100

Minimum chunk size (prevents too many tiny chunks)

DefaultSTTConfig

Default Speech-to-Text configuration with support for Chrome AI, OpenAI Whisper, and generic APIs.

Structure

const DefaultSTTConfig = {
  enabled: false,
  provider: 'chrome-ai-multimodal', // 'chrome-ai-multimodal' | 'openai' | 'openai-compatible'
  
  'chrome-ai-multimodal': {
    temperature: 0.1,
    topK: 3,
  },
  
  openai: {
    apiKey: '',
    model: 'whisper-1',
    language: 'en',
    temperature: 0.0,
  },
  
  'openai-compatible': {
    endpoint: 'http://localhost:8000',
    apiKey: '',
    model: 'whisper',
    language: 'en',
    temperature: 0.0,
  },
};

Chrome AI Multimodal Settings

number

Low temperature for accurate transcription

number

default:3

Top-K sampling for token selection

OpenAI Whisper Settings

string

required

OpenAI API key

string

default:"whisper-1"

Whisper model (currently only ‘whisper-1’ available)

string

default:"en"

Input audio language (ISO 639-1 code)

number

Temperature for transcription (0.0 = deterministic)

AnimationConfig

Animation configuration defines available animations, categories, and transition settings.

Animation Categories

export const AnimationCategory = {
  IDLE: 'idle',
  THINKING: 'thinking',
  CELEBRATING: 'celebrating',
  WALKING: 'walking',
  TALKING: 'talking',
};

Assistant States

export const AssistantState = {
  INTRO: 'INTRO',         // Initial entrance
  IDLE: 'IDLE',           // Default idle state
  BUSY: 'BUSY',           // Doing something
  SPEAKING: 'SPEAKING',   // Talking to user
  SPEAKING_HOLD: 'SPEAKING_HOLD', // Holding between TTS chunks
  CELEBRATING: 'CELEBRATING', // Celebration animation
  COMPOSITE: 'COMPOSITE', // Blended composite
};

Transition Settings

number

default:30

Default transition duration (1 second at 30fps)

object

Bezier easing curve for smooth S-curve transitions:

{
  x1: 0.25,
  y1: 0.1,
  x2: 0.75,
  y2: 0.9,
}

number

default:15

Quick transition duration (0.5 seconds)

number

default:60

Slow transition duration (2 seconds)

Animation Registry

Animations are organized by category:

export const AnimationRegistry = {
  idle: [
    {
      id: 'idle_1',
      name: 'Idle 1',
      filePath: 'res/assets/motion/idle1.bvmd',
      transitionFrames: 30,
      loop: true,
      loopTransition: true,
      weight: 1.0,
      metadata: {
        description: 'Primary idle animation',
        tags: ['default', 'idle', 'calm'],
      },
    },
    // ... more idle animations
  ],
  thinking: [ /* ... */ ],
  celebrating: [ /* ... */ ],
  walking: [ /* ... */ ],
  talking: [ /* ... */ ],
};

Animation Entry Fields

string

required

Unique identifier for the animation

string

required

Human-readable name

string

required

Path to .bvmd animation file (resolved at runtime)

number

default:30

Transition duration when entering/exiting

boolean

default:false

Whether animation should loop

boolean

default:false

Smooth blend between loop cycles (creates overlap)

number

Default blending weight (0.0-1.0)

object

Additional information:

description: Detailed description
tags: Array of tags for categorization

UIConfig

User interface configuration for positioning, appearance, and behavior.

Structure

export const DefaultUIConfig = {
  enableModelLoading: true,
  enablePortraitMode: false,
  fpsLimit: 60, // 30 | 60 | 90 | 'native'
  autoLoadOnAllPages: true,
  enableAIToolbar: true,
  
  aiToolbar: {
    showOnInputFocus: true,
    showOnImageHover: true,
  },
  
  enableColoredIcons: false,
  enableColoredIconsToolbarOnly: false,
  enableDebugPanel: false,
  
  position: {
    preset: 'bottom-right',
    lastLocation: null,
  },
  
  backgroundDetection: {
    mode: 'adaptive', // 'adaptive' | 'light' | 'dark'
    sampleGridSize: 5,
    showDebug: false,
  },
  
  smoothStreamingAnimation: false,
  
  shortcuts: {
    enabled: false,
    openChat: '',
    toggleMode: '',
  },
};

Display Settings

boolean

default:true

Show 3D character model

boolean

default:false

Enable portrait mode (clips model at waist, shows upper body only)

number | string

default:60

Frame rate limit: 30 | 60 | 90 | ‘native’

boolean

default:true

Auto-load assistant on all pages (extension mode only)

Enable floating AI toolbar for text/image operations

Show toolbar when focusing text inputs (for dictation)

Show toolbar when hovering over images

Position Presets

Available position presets:

'bottom-right': Default chatbot position
'bottom-left': Bottom-left corner
'bottom-center': Bottom center
'center': Large centered view
'top-right': Top-right corner
'top-left': Top-left corner
'top-center': Top center
'last-location': Restore last saved position

Position Preset Structure

{
  name: 'Bottom Right',
  modelSize: { width: 300, height: 500 },
  portraitModelSize: { width: 300, height: 500 },
  padding: 0,
  offset: { x: -2, y: 2 },
  portraitOffset: { x: 0, y: 6.2 },
  customBoundaries: { left: 80, right: 0, top: 100, bottom: 0 },
  portraitCustomBoundaries: { left: 0, right: 0, top: 100, bottom: 0 },
  portraitClipPlaneY: 12,
  description: 'Default chatbot position'
}

Background Detection Settings

string

default:"adaptive"

Theme mode:

'adaptive': Auto-detect background brightness
'light': Force light theme
'dark': Force dark theme

number

default:5

Grid size for brightness sampling (5 = 25 sample points)

boolean

default:false

Show debug markers for brightness detection

Chat Settings

boolean

default:false

Enable smooth character-by-character streaming animation

Keyboard Shortcuts

boolean

default:false

Enable keyboard shortcuts

string

default:""

Shortcut to open chat (e.g., ‘Ctrl+Shift+A’)

string

default:""

Shortcut to toggle portrait mode

Usage Examples

Configure Chrome AI

import { DefaultAIConfig } from './config/aiConfig';
import AIServiceProxy from './services/proxies/AIServiceProxy';

// Override defaults
const config = {
  ...DefaultAIConfig,
  provider: 'chrome-ai',
  chromeAi: {
    ...DefaultAIConfig.chromeAi,
    temperature: 0.8,
    enableImageSupport: true,
    enableAudioSupport: true,
  },
};

await AIServiceProxy.configure(config);

Configure Kokoro TTS

import { DefaultTTSConfig } from './config/aiConfig';
import { TTSServiceProxy } from './services/proxies';

const config = {
  ...DefaultTTSConfig,
  enabled: true,
  provider: 'kokoro',
  kokoro: {
    modelId: 'onnx-community/Kokoro-82M-v1.0-ONNX',
    voice: 'af_sarah',
    speed: 1.2,
    device: 'webgpu',
    keepModelLoaded: true,
  },
};

TTSServiceProxy.configure(config);

Set Model Position

import { PositionPresets } from './config/uiConfig';

// Use preset
assistantRef.current.setPosition('bottom-right');

// Or get position manager and customize
const posMgr = assistantRef.current.getPositionManager();
posMgr.applyPreset('center');

Custom UI Configuration

import { DefaultUIConfig } from './config/uiConfig';
import { useConfig } from './contexts/ConfigContext';

function MyApp() {
  const { updateUIConfig } = useConfig();

  // Update multiple settings
  updateUIConfig('enablePortraitMode', true);
  updateUIConfig('fpsLimit', 90);
  updateUIConfig('position.preset', 'bottom-center');
  updateUIConfig('backgroundDetection.mode', 'dark');
  
  return <VirtualAssistant />;
}

Contributing

API Reference

Configuration Reference

Configuration

DefaultAIConfig

Structure

Chrome AI Settings

OpenAI Settings

Ollama Settings

DefaultTTSConfig

Structure

Kokoro TTS Settings

OpenAI TTS Settings

Chunking Settings

DefaultSTTConfig

Structure

Chrome AI Multimodal Settings

OpenAI Whisper Settings

AnimationConfig

Animation Categories

Assistant States

Transition Settings

Animation Registry

Animation Entry Fields

UIConfig

Structure

Display Settings

Position Presets

Position Preset Structure

Background Detection Settings

Chat Settings

Keyboard Shortcuts

Usage Examples

​Configuration

​DefaultAIConfig

​Structure

​Chrome AI Settings

​OpenAI Settings

​Ollama Settings

​DefaultTTSConfig

​Structure

​Kokoro TTS Settings

​OpenAI TTS Settings

​Chunking Settings

​DefaultSTTConfig

​Structure

​Chrome AI Multimodal Settings

​OpenAI Whisper Settings

​AnimationConfig

​Animation Categories

​Assistant States

​Transition Settings

​Animation Registry

​Animation Entry Fields

​UIConfig

​Structure

​Display Settings

​AI Toolbar Settings

​Position Presets

​Position Preset Structure

​Background Detection Settings

​Chat Settings

​Keyboard Shortcuts

​Usage Examples

Configuration

DefaultAIConfig

Structure

Chrome AI Settings

OpenAI Settings

Ollama Settings

DefaultTTSConfig

Structure

Kokoro TTS Settings

OpenAI TTS Settings

Chunking Settings

DefaultSTTConfig

Structure

Chrome AI Multimodal Settings

OpenAI Whisper Settings

AnimationConfig

Animation Categories

Assistant States

Transition Settings

Animation Registry

Animation Entry Fields

UIConfig

Structure

Display Settings

AI Toolbar Settings

Position Presets

Position Preset Structure

Background Detection Settings

Chat Settings

Keyboard Shortcuts

Usage Examples