# Adom Avatar — 3D Talking Narrator

A cartoonish 3D avatar that appears as an overlay in the Adom Viewer and speaks text aloud using Piper TTS (text-to-speech) with lip-sync animation.

## Commands

All commands go through the `avatar` CLI:

```bash
# Show the avatar in the bottom-right corner
avatar show

# Make the avatar speak (triggers TTS + lip-sync)
avatar say "Step 1: Open the schematic editor"

# Hide the avatar
avatar hide

# Run a quick demo
avatar demo
```

The `avatar say` command blocks for an estimated speech duration (~150ms per word) so you can chain commands sequentially.

## Narrated Demo Pattern

Use the avatar to create narrated walkthroughs of any Adom feature:

```bash
# 1. Show avatar
avatar show

# 2. Introduce the demo
avatar say "Welcome! Today I'll show you how to parse a datasheet."

# 3. Perform actions with narration
avatar say "First, we download the manufacturer PDF."
# ... perform the actual action ...

avatar say "Next, we extract images and run FXAA anti-aliasing."
# ... perform the action ...

avatar say "Finally, we publish to the Adom Wiki."
# ... publish ...

# 4. Wrap up
avatar say "That's it! The datasheet is now live on the wiki."
avatar hide
```

## Narrated Video Recording

Combine with Hydrogen's screen recording for narrated demo videos:

```bash
# Request sharing permission
adom-cli hydrogen sharing request --share tab --reason "Recording narrated demo"

# Start recording
adom-cli hydrogen recording start --countdown 3

# Run the narrated demo
avatar show
avatar say "Welcome to this demo of the symbol creator."
# ... perform actions with avatar narration ...
avatar say "Thanks for watching!"
avatar hide

# Stop and save
adom-cli hydrogen recording stop --output ~/project/project-content/videos/demo.webm

# Upload to wiki
adom-wiki asset upload skills/symbol-creator --asset-type video \
  --file ~/project/project-content/videos/demo.webm \
  --caption "Narrated demo — symbol creation walkthrough"
```

## TTS Details

- **Engine:** Piper (offline neural TTS)
- **Voice:** en_US-lessac-medium
- **Port:** 8840 (Piper TTS HTTP server)
- **Latency:** ~100-300ms per sentence
- **Audio:** Played in-browser with Web Audio API, drives lip-sync via amplitude analysis

## Avatar Appearance

The avatar is a cartoonish 3D character rendered in Three.js:
- Round head with the Adom baseball cap
- Gold round glasses
- Big friendly smile that animates during speech
- Teal shirt (Adom brand color)
- Transparent background, positioned in bottom-right corner
- Idle bobbing animation + eye blinks

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| No audio | Check Piper TTS is running: `curl http://127.0.0.1:8840/health` |
| Avatar not visible | Ensure Adom Viewer panel is open |
| Mouth not moving | Audio may be blocked by browser autoplay policy — click the viewer first |
| TTS server not running | Start it: `cd ~/gallia && nohup node services/piper-tts/server.js > /tmp/piper-tts.log 2>&1 &` |