Skip to main content

Avatars

Avatars are the conversational characters you talk to. Pets stay cosmetic sprites; selecting a pet also creates a matching Avatar profile under <VIBEOS_HOME>/avatars/.

For pet installation, sprites, and overlay gestures, see Pets. This page is the Avatar dialogue surface.

What you get​

CapabilityBehavior
Text reply on petSpeech bubble preview on overlay / floating pet; full answer in chat
PersonaOptional personality / system prompt via cache-safe ephemeral overlay
Voice inOverlay mic → STT → submit (works even when auto-speak is off)
Voice outTTS with avatar voice preset while the pet is visible (display.avatar.auto_speak)
Multi-avatarCmd+K Avatars…, /avatar, Settings → Appearance → Pet
Soft memoryWrites tagged avatar:<id> by default; set memory=shared to opt out
Hard Core (opt-in)Separate memories/avatars/<id>/ Core — needs display.avatar.hard_memory + isolation=hard; binds next session
Talking-headoff | wave (celebrate during TTS) | skill (local talking-photo; optional vendor plugin)

Quick start​

  1. Adopt a pet (Settings → Appearance → Pet, or /pet <slug>).
  2. An Avatar with the same id is created automatically.
  3. Optionally set personality, voice, talking-head mode, and memory scope.
  4. Message from the pet overlay composer (or normal chat with the pet visible).
  5. Hear replies when Auto-speak is on; use the mic anytime.

Commands​

Same on desktop, classic CLI, and messaging gateways:

/avatar list
/avatar <id>
/avatar none
/avatar create boba pet=boba personality=concise voice=edge:en-US-AriaNeural
/avatar update boba talking-head=skill memory=shared

Fields: pet=, name=, personality=, voice=, memory= (shared or default per-avatar), isolation= (soft | hard), talking-head= (off | wave | skill), portrait=.

On messaging, /avatar also updates the live session (persona + soft memory

  • a one-shot note on the next turn). Classic CLI rebuilds the agent when the persona changes and refreshes memory scope in place otherwise.

Hard memory never creates a second profile. It only relocates Core/User under memories/avatars/<id>/ inside the active VIBEOS_HOME, and only at session start. Mid-chat switches keep the frozen snapshot (prompt cache). True multi-HOME isolation remains vibeos -p <profile>.

Kanban / Fleet may show a visual [avatar:<id>] tag on cards — label only, no HOME swap.

Talking-head modes​

ModeBehavior
wave (default)Pet celebrate/jump while avatar TTS plays
offNo celebrate / no skill clip
skillLocal talking-photo via avatar.talking_head.render (TTS + ffmpeg); falls back to TTS if render fails
Prefer vendor (opt-in)When prefer_vendor: true, try user plugin talking_head_vendor_render first, then ffmpeg

Portrait: leave blank to auto-crop the pet idle frame into avatars/<id>-portrait.png, or set a local image. Settings has Regenerate from pet.

vibeos skills install official/creative/talking-head

Vendor lip-sync (standalone plugin)​

Vendor SaaS (HeyGen, D-ID, …) stays out of the VibeOS core tree. Install under ~/.vibeos/plugins/ only:

bash scripts/scaffold-talking-head-vendor-plugin.sh
  1. Add TALKING_HEAD_VENDOR_API_KEY (+ TALKING_HEAD_VENDOR_BASE_URL) to ~/.vibeos/.env.
  2. Implement the HTTP client in the scaffolded __init__.py.
  3. Set talking-head mode to skill and enable Prefer vendor lip-sync plugin in Settings (or prefer_vendor: true below).
  4. Offline wiring check: TALKING_HEAD_VENDOR_MOCK=1 (still+audio labeled mock-vendor — not real lip-sync).

Built-in clips remain honest talking-photo (backend: ffmpeg-still) unless the vendor tool succeeds.

Configuration​

display:
  avatar:
    enabled: false
    id: ""
    auto_speak: true
    hard_memory: false   # opt-in hard Core under memories/avatars/<id>/
    talking_head:
      enabled: true
      mode: wave          # off | wave | skill
      portrait_path: ""
      prefer_vendor: false  # try ~/.vibeos/plugins talking_head_vendor_render first

Secrets (API keys for TTS / optional vendor plugins) belong in .env, not here.

Verify​

bash scripts/smoke-avatar-dialogue.sh