avatar
starsforks
How to install avatar?
acnlabs/openpersona/avatar
$npx -y skills add acnlabs/OpenPersona --skill avatarThis faculty bridges OpenPersona to an external avatar skill/runtime. OpenPersona does not implement rendering, lip-sync, or animation engines locally. It delegates those capabilities to the install source configured in faculty.json.
SKILL.md
| 1 | # Avatar Faculty — Expression (External Skill Bridge) |
| 2 | |
| 3 | This faculty bridges OpenPersona to an external avatar skill/runtime. OpenPersona does not implement rendering, lip-sync, or animation engines locally. It delegates those capabilities to the install source configured in `faculty.json`. |
| 4 | |
| 5 | ## Intent |
| 6 | |
| 7 | - Provide a visual embodiment channel for the persona. |
| 8 | - Support progressive forms: image -> 3D -> motion -> voice avatar. |
| 9 | - Keep OpenPersona lightweight while allowing market-ready avatar runtimes to evolve independently. |
| 10 | - Keep visual semantics portable through `references/VISUAL-MANIFEST.md`. |
| 11 | - Keep avatar control semantics portable through `references/AVATAR-CONTROL.md`. |
| 12 | |
| 13 | ## Install Source |
| 14 | |
| 15 | Use the install source declared in `faculty.json`: |
| 16 | |
| 17 | ```bash |
| 18 | npx skills add avatar-runtime |
| 19 | # or directly from GitHub: |
| 20 | npx skills add github:acnlabs/avatar-runtime/skill/avatar-runtime |
| 21 | ``` |
| 22 | |
| 23 | ## Runtime Behavior |
| 24 | |
| 25 | ### If avatar skill is installed |
| 26 | |
| 27 | - Use the external avatar skill as the source of truth for commands, API usage, and runtime constraints. |
| 28 | - Treat avatar rendering and animation as external capabilities. |
| 29 | - Reflect current form/state to the host UI (e.g., active sensory icon states). |
| 30 | |
| 31 | You can run the local bridge script: |
| 32 | |
| 33 | ```bash |
| 34 | # health check |
| 35 | node scripts/avatar-runtime.js health |
| 36 | |
| 37 | # start session |
| 38 | node scripts/avatar-runtime.js start "$PERSONA_SLUG" image |
| 39 | |
| 40 | # send text |
| 41 | node scripts/avatar-runtime.js text "<session-id>" "hello" |
| 42 | |
| 43 | # query status + appearance patch for state.json |
| 44 | node scripts/avatar-runtime.js status "<session-id>" |
| 45 | |
| 46 | # persist appearanceState into soul/state.json (runner CLI first, local fallback) |
| 47 | node scripts/avatar-runtime.js sync-state "<slug>" "<session-id>" |
| 48 | |
| 49 | # keep syncing every 5 seconds (Ctrl+C to stop) |
| 50 | node scripts/avatar-runtime.js sync-loop "<slug>" "<session-id>" 5 |
| 51 | |
| 52 | # output baseline avatar control for a named mood preset |
| 53 | node scripts/avatar-control.js preset calm |
| 54 | node scripts/avatar-control.js preset focus |
| 55 | node scripts/avatar-control.js preset joy |
| 56 | |
| 57 | # map agent state -> control.avatar.{face,emotion} |
| 58 | node scripts/avatar-control.js map '{"intent":"focus","mood":{"valence":0.1,"arousal":0.35,"intensity":0.7},"source":"agent"}' |
| 59 | |
| 60 | # apply to demo state file (writes control + appearanceIntent) |
| 61 | node scripts/avatar-control.js apply demo/living-canvas.state.json preset focus |
| 62 | ``` |
| 63 | |
| 64 | Optional demo output (write state for `demo/living-canvas.html`): |
| 65 | |
| 66 | ```bash |
| 67 | export LIVING_CANVAS_STATE_PATH=demo/living-canvas.state.json |
| 68 | export LIVING_CANVAS_PERSONA_NAME=Samantha |
| 69 | export LIVING_CANVAS_ROLE=companion |
| 70 | export LIVING_CANVAS_AVATAR=../UI/images/samantha-avatar.png |
| 71 | # Optional: if runtime status contains livekit credentials, write token for local demo playback |
| 72 | export LIVING_CANVAS_ALLOW_RUNTIME_TOKEN=true |
| 73 | |
| 74 | node scripts/avatar-runtime.js sync-state "<slug>" "<session-id>" |
| 75 | ``` |
| 76 | |
| 77 | `status` outputs: |
| 78 | |
| 79 | - `runtimeStatus` — raw runtime response |
| 80 | - `sensoryStatus` — icon-ready booleans (`image`, `model3d`, `motion`, `voice`, `hearing`, `worldSense`) |
| 81 | - **`voice: true`** means the avatar provider supports lip-sync / speech output as part of visual rendering (e.g. HeyGen streaming TTS). This is **not** the same as the persona's `voice` faculty — the voice faculty generates standalone audio output (ElevenLabs/OpenAI TTS); `sensoryStatus.voice` indicates only that the avatar's mouth can move in sync with speech. |
| 82 | - `statePatch` — patch payload you can persist into `appearanceState` |
| 83 | |
| 84 | ### If avatar skill is not installed |
| 85 | |
| 86 | - Respond with graceful fallback: continue text conversation normally. |
| 87 | - Clearly state that visual avatar mode is currently unavailable. |
| 88 | - Offer installation guidance using the install source. |
| 89 | |
| 90 | ## Voice × Avatar Configuration Scenarios |
| 91 | |
| 92 | How voice and avatar work together depends on the provider: |
| 93 | |
| 94 | | Scenario | voice faculty | avatar provider | Result | |
| 95 | |---|---|---|---| |
| 96 | | **A — voice only** | declared | none | Standalone TTS audio output; no visual | |
| 97 | | **B — avatar with built-in TTS** | not needed | HeyGen / cloud | Provider speaks natively; `sensoryStatus.voice: true`; voice faculty redundant | |
| 98 | | **C — avatar + external TTS** | declared | VRM / Live2D | voice faculty generates `audioUrl` → `scripts/avatar-runtime.js sendAudio <session> <audioUrl>` → avatar lip-syncs | |
| 99 | |
| 100 | > **Scenario C bridge** (`voice faculty audio → avatar lip-sync`) is not auto-wired. The agent must explicitly call `sendAudio` after TTS generation. See ROADMAP for the planned lip-sync bridge integration. |
| 101 | |
| 102 | ## Conversation Policy |
| 103 | |
| 104 | - Do not pretend visual/voice rendering succeeded when runtime is unavailable. |
| 105 | - Confirm capability state before promising actions like "switch to 3D" or "start lip-sync". |
| 106 | - When `sensoryStatus.voice: true`, the avatar can speak via the provider's built-in channel — do not activate the voice faculty in parallel unless intentionally bridging (Scenario C). |
| 107 | - Keep user-facing language concise and actionable. |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
