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

chromeAi.temperature

number

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

chromeAi.topK

number

default:3

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

chromeAi.outputLanguage

string

default:"en"

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

chromeAi.enableImageSupport

boolean

default:true

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

chromeAi.enableAudioSupport

boolean

default:true

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

chromeAi.systemPromptType

string

default:"default"

Personality type from PromptConfig.systemPrompts or ‘custom’

chromeAi.systemPrompt

string

default:""

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

OpenAI Settings

openai.apiKey

string

required

OpenAI API key

openai.model

string

default:"gpt-4-turbo-preview"

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

openai.temperature

number

Sampling temperature (0.0-2.0)

openai.maxTokens

number

default:2000

Maximum tokens in response

openai.enableImageSupport

boolean

default:true

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

openai.enableAudioSupport

boolean

default:true

Enable audio transcription via Whisper

Ollama Settings

ollama.endpoint

string

default:"http://localhost:11434"

Ollama server endpoint

ollama.model

string

default:"llama2"

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

ollama.temperature

number

Sampling temperature

ollama.maxTokens

number

default:2000

Maximum tokens in response

ollama.enableImageSupport

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

kokoro.modelId

string

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

HuggingFace model ID for Kokoro TTS

kokoro.voice

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

kokoro.speed

number

Speech speed multiplier (0.25-4.0)

kokoro.device

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)

kokoro.keepModelLoaded

boolean

default:true

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

OpenAI TTS Settings

openai.apiKey

string

required

OpenAI API key

openai.model

string

default:"tts-1"

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

openai.voice

string

default:"nova"

openai.speed

number

Speech speed (0.25-4.0)

Chunking Settings

chunkSize

number

default:500

Target chunk size in characters for streaming TTS

minChunkSize

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

chrome-ai-multimodal.temperature

number

Low temperature for accurate transcription

chrome-ai-multimodal.topK

number

default:3

Top-K sampling for token selection

OpenAI Whisper Settings

openai.apiKey

string

required

OpenAI API key

openai.model

string

default:"whisper-1"

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

openai.language

string

default:"en"

Input audio language (ISO 639-1 code)

openai.temperature

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

DEFAULT_TRANSITION_FRAMES

number

default:30

Default transition duration (1 second at 30fps)

DEFAULT_EASING_CURVE

object

Bezier easing curve for smooth S-curve transitions:

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

QUICK_TRANSITION_FRAMES

number

default:15

Quick transition duration (0.5 seconds)

SLOW_TRANSITION_FRAMES

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

name

string

required

Human-readable name

filePath

string

required

Path to .bvmd animation file (resolved at runtime)

transitionFrames

number

default:30

Transition duration when entering/exiting

loop

boolean

default:false

Whether animation should loop

loopTransition

boolean

default:false

Smooth blend between loop cycles (creates overlap)

weight

number

Default blending weight (0.0-1.0)

metadata

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

enableModelLoading

boolean

default:true

Show 3D character model

enablePortraitMode

boolean

default:false

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

fpsLimit

number | string

default:60

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

autoLoadOnAllPages

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

backgroundDetection.mode

string

default:"adaptive"

Theme mode:

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

backgroundDetection.sampleGridSize

number

default:5

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

backgroundDetection.showDebug

boolean

default:false

Show debug markers for brightness detection

Chat Settings

smoothStreamingAnimation

boolean

default:false

Enable smooth character-by-character streaming animation

Keyboard Shortcuts

shortcuts.enabled

boolean

default:false

Enable keyboard shortcuts

shortcuts.openChat

string

default:""

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

shortcuts.toggleMode

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

Build docs developers (and LLMs) love

Contributing

API 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

​AI Toolbar Settings

​Position Presets

​Position Preset Structure

​Background Detection Settings

​Chat Settings

​Keyboard Shortcuts

​Usage Examples

Build docs developers (and LLMs) love

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