# AnimaSync Face V3

V3 of the AnimaSync face model — **currently in development**, not yet deployed.

V3 is a system, not a single trained model. It combines a learned emotion classifier with an authored expression engine to produce more expressive, emotion-aware avatar animation than V1/V2.

## Repo structure

```
animasync-face-v3/
├── scripts/
│   ├── compiler/                  # The V3 expression engine
│   │   ├── parametric.py          # Closed-form VAD → blendshape rules
│   │   ├── archetype.py           # RBF interpolation over preset anchors
│   │   ├── expressive.py          # User-authored L1/L3/L5 preset blending
│   │   ├── blend.py               # Compiler combining all layers
│   │   ├── data_pipeline.py       # Audio + scenarios → training samples
│   │   ├── eye_motion.py          # Blinks + iris drift post-processing
│   │   ├── lam_wrapper.py         # LAM lipsync integration
│   │   ├── abc_experiment.py      # A/B/C variant rendering
│   │   ├── generate_audio.py      # ElevenLabs TTS pipeline
│   │   └── ...
│   ├── clamp_vad.py
│   ├── restore_and_smart_clamp_vad.py
│   ├── stratified_resplit.py
│   ├── export_dataset_xlsx.py
│   └── demo_server.py
│
├── models/
│   └── microalbert/               # V3 emotion-detection model
│       ├── train.py               # Main training loop
│       ├── train_teacher.py       # KLUE teacher pretraining
│       ├── distill.py             # Teacher → student distillation
│       ├── teacher.py
│       ├── model.py               # MicroALBERT architecture
│       ├── tokenizer.py
│       ├── dataset.py
│       ├── losses.py
│       ├── eval.py
│       └── report*.py
│
├── data/
│   └── emotion/                   # V3 dataset pipeline
│       ├── seed_scenarios_final.jsonl
│       ├── seed_train_final.jsonl
│       ├── seed_val.jsonl
│       ├── seed_test.jsonl
│       ├── vad_assignments.jsonl
│       ├── emotion_vad_anchors.json   # 16 emotions × 5 levels VAD anchors
│       ├── emotion_labels.json
│       ├── kote_relabeled.jsonl       # KOTE corpus relabeled to V3 emotion set
│       ├── label_kote.py
│       ├── apply_paraphrases.py
│       ├── augment*.py
│       └── 데이터셋_설명서.md
│
├── tools/
│   ├── blendshape-editor.html     # In-browser preset authoring tool
│   └── blendshape-player.html     # In-browser blendshape playback viewer
│
├── docs/
│   └── INVENTORY.md               # Internal inventory of project state (May 2026)
│   └── (other design docs)
│
└── expression_presets.json        # 47 user-authored L1/L3/L5 presets across 16 emotions
```

## V3 vs V1/V2

| | V1 | V2 | V3 |
|---|---|---|---|
| Approach | Phoneme classifier (CTC) → blendshapes | Distilled student model from LAM teacher → blendshapes | Authored expression engine + learned emotion classifier (MicroALBERT) |
| Outputs | 111-dim blendshapes (V1 phoneme path), 52 ARKit (V1 student path) | 52 ARKit blendshapes | 52 ARKit blendshapes + emotion-conditioned expression layer |
| Status | Deployed (npm + FastAPI) | Deployed (npm `lipsync-wasm-v2`) | **In development** |
| Repo | [animasync-face-v1](https://github.com/GoodGangLabs/animasync-face-v1) | [animasync-face-v2](https://github.com/GoodGangLabs/animasync-face-v2) | this repo |


## Status

Initial commit (2026-05-04) capturing V3 system source code so far. Active development continues. See `docs/INVENTORY.md` for the broader project inventory at this point in time.