# Blender Facial Shapekeys

Facial rigs and shape keys in Blender 5.2 - ARKit 52 blendshapes, visemes for lip-sync...

- Repository: https://github.com/EL4CTEO/blender-skills (651 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add EL4CTEO/blender-skills --skill blender-facial-shapekeys -g -a claude-code -y`
Codex: `npx skills add EL4CTEO/blender-skills --skill blender-facial-shapekeys -g -a codex -y`
Cursor: `npx skills add EL4CTEO/blender-skills --skill blender-facial-shapekeys -g -a cursor -y`
Gemini CLI: `npx skills add EL4CTEO/blender-skills --skill blender-facial-shapekeys -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add EL4CTEO/blender-skills`

## Description

Facial rigs and shape keys in Blender 5.2 - ARKit 52 blendshapes, visemes for lip-sync, sculpting expressions, splitting symmetric shapes into Left/Right, mirroring, corrective and combination shapes, drivers and control rigs, bone+blendshape hybrids, export to engines (Unity, Unreal, Roblox dynamic heads, VRM/web). Use for faces, expressions, lip-sync, or any shape-key work.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Facial Rig & Shape Keys

The execution model is in `blender-core`. The body rig is in `blender-character-rigging`.

## Choose the approach
| Approach | Use | Notes |
|---|---|---|
| **Blendshapes (ARKit 52)** | games, VTubers, mocap (iPhone/Live Link Face), web/VRM | the industry interchange set; each shape is sculpted |
| **Bones** (jaw, eyes, lids, brows, lips) | stylized, low memory, mobile | jaw + eyes as bones are almost always right |
| **Hybrid** | most production game heads | jaw/eye/tongue bones + blendshapes for everything soft |
| **Rigify face** (`human` metarig) | film-style keyframe animation inside Blender | 100+ face bones, heavy for engines |

## Procedure (blendshapes)
1. The head mesh needs clean loops around the eyes and mouth (`blender-retopology-uv`), with eyes, teeth and tongue as separate objects parented or weighted to bones.
2. `scripts/shapekeys.py -- --mesh Head --create arkit` (or `--create visemes` for the 15 Oculus visemes) creates empty, correctly named keys.
3. Sculpt each key (live: sculpt mode on the active key, `use_shape_key_edit_mode`). Symmetric expressions can be sculpted once, then `--split eyeBlink` gives `eyeBlinkLeft/Right` with a soft blend across X=0 (`--falloff` m).
4. `--mirror browDownLeft` builds `browDownRight` (topology-independent mirror).
5. `--report` lists unsculpted keys, the max offset per key, and missing ARKit names. A shape is done only when every key moves and nothing is left over.
6. Optional: `--drivers FaceCtrl` adds a controller with 0, 1 custom properties driving each key, for keyframing in Blender.
7. Check the extremes and **combinations** (jawOpen + mouthSmile, eyeBlink + eyeSquint) with `look`. Fix them with corrective combination keys driven by the product of two keys.

The rest: https://github.com/EL4CTEO/blender-skills/blob/HEAD/skills/blender-facial-shapekeys/SKILL.md