Start

Set up a machine

From a Linux machine with an NVIDIA card to ./alive check saying everything is in place. About an hour, most of it installing packages. Do this once.

What lives where

Four folders matter. Only the first is in git; the other three are yours, and can be links to any disk with room.

The order

1. System

Linux with an NVIDIA driver new enough for CUDA 12.8, then these tools:

sudo apt install ffmpeg git cmake build-essential
python3 -m pip install --user yt-dlp   # downloads the videos; any Python, it only has to be on PATH
curl -fsSL https://deno.land/install.sh | sh   # yt-dlp needs a JavaScript runtime for YouTube now
# Miniconda, into ~/miniconda3 (the default the scripts look in):
curl -LO https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p ~/miniconda3
# uv, a fast pip, for the three plain venvs:
curl -LsSf https://astral.sh/uv/install.sh | sh

Claude Code (claude.com/claude-code): the recipes are written for it. Start it in the repository and ask it to build a creator; it runs ./alive build, and where the build stops for a decision it looks at the sheets and makes the call, as it did for both example creators' resting poses. You can make those calls by hand instead.

2. Clone

git clone https://github.com/pavanteja295/alive && cd alive

Steps 3 to 5 in one command./alive install fetches the outside code, creates all six environments, builds the shared face assets once your MetaHuman rig is in place, and finishes with a list of the files only you can supply. Rerun it after adding them; it skips whatever is done. The sections below say what it does, for when one step needs a hand.

3. Outside code

Three projects this builds on, each at the exact commit used, with our changes applied as patches: the face tracker (VHAP), the face renderer (STAvatar) and the voice model (F5-TTS).

bash env/setup_externals.sh

4. Environments

Six separate Python environments, because their libraries conflict. Each file in env/ is the exact package list. bash env/install.sh builds all six (or name some: bash env/install.sh face tracker), installing each list exactly and compiling the renderer's and tracker's GPU code for your card:

environment	for	build it with
`~/.venvs/vc-f5`	voice training and serving	`uv venv --python 3.11`, `-r env/voice-f5.txt`, then `-e externals/F5-TTS`
`~/.venvs/vc-prep`	voice data preparation	`uv venv --python 3.11`, `-r env/voice-prep.txt`
`stavatar` (conda)	face motion, renderer, live face	`python=3.10`, `-r env/face.txt`, then the renderer's three CUDA extensions
`vhap` (conda)	face tracking	`python=3.10`, `-r env/tracker.txt`, `-e externals/vhap`, plus conda's `gxx_linux-64` and `cuda-nvcc=12.8`
`faceid` (conda)	checking it's the right person in each shot	`python=3.10`, `-r env/faceid.txt`
`~/.venvs/mh-offset`	the speech encoder pass	`uv venv --python 3.13`, `-r env/speech-encoder.txt`

The renderer's three CUDA extensions are diff-gaussian-rasterization, simple-knn and fused-ssim, under externals/stavatar/submodules/; env/README.md has the one pip install line that builds them. The answer engine and the viewer only need the system Python 3.11+ with python3 -m pip install --user anthropic.

You never activate an environment./alive, ./alive build and the answer engine run on the system python3, and every step calls its own environment's Python by path. The paths default to the ones in the table; if yours differ, set ENV_F5, ENV_PREP, ENV_STAVATAR or ENV_VHAP to the environment's folder. The stage pages show the Python to use when you run a step by hand.

Reusing environments from another projectThe tracker and voice environments install externals/vhap and externals/F5-TTS in editable mode, and F5 keeps its training data and saved models beside its own code. An environment installed from another checkout will train from that checkout's files, and can resume someone else's training run. Check with ~/.venvs/vc-f5/bin/python -c "import f5_tts; print(f5_tts.__path__)"; it must print a path inside this repository's externals/. If not: uv pip install --python <env>/bin/python --no-deps -e externals/F5-TTS (and the same for externals/vhap in the tracker's environment). Voice training refuses to start on a mismatch.

On a card other than the RTX 50 seriesset TORCH_CUDA_ARCH_LIST (for example 8.9 for an RTX 40) before the tracker and renderer first build their CUDA code.

5. Licensed files

These cannot be redistributed; each user gets their own.

what	where it goes	where to get it
FLAME 2023 head model `flame2023.pkl`, `FLAME_masks.pkl`	`externals/vhap/asset/flame/` and `externals/stavatar/flame_model/assets/flame/`	register at flame.is.tue.mpg.de
Audio2Face-3D speech models `audio_encoder.onnx`, `animation_decoder.onnx`	`data/face/onnx/`	NVIDIA's Audio2Face-3D models, under NVIDIA's licence. The model meant is the one that outputs 81 MetaHuman face curves at 50 frames a second; other versions will fail on shape
a MetaHuman face rig `face.dna`, `face_identity.dna`	`data/face/assets/`	Epic's MetaHuman Creator, under Epic's licence. Must be DNA 2.5 (263 controls, 545 corrective shapes)
the shared face assets built from that rig	`data/face/head/`, `data/face/offset/`	built once from the rig: below
an Anthropic API key	the file `data/answers/.protokey`: the key alone, on one line	console.anthropic.com

The shared face assets

Every creator's face is the same MetaHuman rig reshaped to them, so a few files are built once from your rig and shared. The rig must be MetaHuman DNA version 2.5 (263 controls, 545 corrective shapes); older ones do not fit. Make a MetaHuman in Epic's MetaHuman Creator and export its face DNA; whose face it is matters little, because each creator's face is reshaped from it. face.dna and face_identity.dna are both read from data/face/assets/; the rig's arithmetic is taken from face_identity.dna. First build the DNA reader: bash env/setup_externals.sh --with-riglogic.

file, in `data/face/`	what it is	built by
`offset/rig_tables.npz`	the rig's arithmetic, so it runs without the DNA library	`engines/audio2face/offset/riglogic_numpy.py`
`offset/cache/rig_names.npz`	control names, and the map from the animator's sliders to the rig's raw controls	`engines/audio2face/offset/data/extract_rig_names.py`. Also needs Unreal Engine 5.8 with the MetaHuman plugin installed: it reads one header file from it (set `UE_ROOT`)
`head/head_assets.npz`	the head mesh: triangles, texture coordinates, rest shape	`engines/audio2face/extend_head_assets.py --meshes 0`: `--dump` under the DNA reader, then `--build`. Needs `rig_tables.npz` first
`head/head_assets_0134.npz`	that head plus teeth and eyeballs	the same script, `--meshes 0,1,3,4`
`head/eye_mask.npz`	which vertices are eyelid: how far each moves under the lid controls, and how near it is to Epic's eyelid landmarks	Needs Unreal Engine: made once from `face_landmarks.json` in the MetaHuman plugin
`head/uv_region_masks.pkl`, `uv_region_masks_256.pkl`	eye, nose, lip and forehead regions on the face's texture map	`engines/audio2face/make_region_masks.py`; one run writes both

Build them in the table's order. The script's header shows the exact two commands for each --dump / --build pair.

Two files need Unreal Enginerig_names.npz and eye_mask.npz each read a file from an Unreal Engine 5.8 install with the MetaHuman plugin. Make them once on any machine that has it and copy them across; everything else here runs without Unreal. The rest of the table was rebuilt from scratch and matches the files the two example creators were trained with.

Check

./alive check drk
  ok    data/answers
  ok    externals/vhap
  ...
  MISSING checkpoints/drk/face/render/G4_teeth (mesh-to-render recipe, promote)

Every line that says MISSING names what to add and which recipe makes it. Before you have built anything, the creator's models will be missing; that is what building is for.