# kwaivgi/liveportrait architecture

> Architecture diagram of the GitHub repository kwaivgi/liveportrait, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kwaivgi/liveportrait
- Repository: https://github.com/kwaivgi/liveportrait

## Overview

LivePortrait is a PyTorch portrait-animation application for human and animal subjects. Users provide a source portrait or video and driving video or motion template through the command-line or Gradio interfaces; the runtime prepares crops and motion, animates frames, and produces image or video output. The graph separates human and animal pipelines, shared preprocessing, and the learned model components. README-described editing and regional controls are represented in the Gradio branch. Some internal calls are omitted where excerpts show imports or partial code but not execution; dashed links mark unverified integration.

Main entry points: [`src/live_portrait_pipeline.py`](https://github.com/kwaivgi/liveportrait/blob/main/src/live_portrait_pipeline.py) (Human pipeline), [`src/live_portrait_pipeline_animal.py`](https://github.com/kwaivgi/liveportrait/blob/main/src/live_portrait_pipeline_animal.py) (Animal pipeline), [`src/utils/cropper.py`](https://github.com/kwaivgi/liveportrait/blob/main/src/utils/cropper.py) (Face cropper), [`src/gradio_pipeline.py`](https://github.com/kwaivgi/liveportrait/blob/main/src/gradio_pipeline.py) (Gradio controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI inference<br/>[inference.py]"]
  node_animal_cli["Animal CLI"]
  node_web["Gradio controls<br/>[gradio_pipeline.py]"]
end

subgraph group_runtime["Animation runtime"]
  node_human_pipe["Human pipeline"]
  node_animal_pipe["Animal pipeline"]
  node_wrapper["Inference wrapper"]
  node_config["Runtime configuration"]
end

subgraph group_prep["Input preparation"]
  node_cropper["Face cropper<br/>[cropper.py]"]
  node_crop_math["Crop geometry<br/>[crop.py]"]
  node_landmarks["Landmark detection"]
  node_animal_landmarks["Animal landmarks"]
  node_io["Image video I/O<br/>[io.py]"]
  node_video["Video utilities<br/>[video.py]"]
end

subgraph group_models["Learned models"]
  node_networks["Animation networks"]
  node_xpose["X-Pose dependency"]
end

node_user(("User"))
node_output["Generated media"]

node_user -->|"supplies inputs"| node_cli
node_user -->|"supplies inputs"| node_animal_cli
node_user -->|"edits animation"| node_web
node_cli -->|"runs"| node_human_pipe
node_animal_cli -->|"runs"| node_animal_pipe
node_web -->|"dispatches"| node_human_pipe
node_web -->|"dispatches"| node_animal_pipe
node_human_pipe -->|"uses settings"| node_config
node_animal_pipe -->|"uses settings"| node_config
node_human_pipe -->|"crops frames"| node_cropper
node_animal_pipe -->|"crops frames"| node_cropper
node_human_pipe -->|"runs inference"| node_wrapper
node_animal_pipe -.->|"runs inference"| node_wrapper
node_human_pipe -->|"loads media"| node_io
node_animal_pipe -->|"loads media"| node_io
node_human_pipe -->|"reads video metadata"| node_video
node_cropper -->|"uses geometry"| node_crop_math
node_cropper -->|"requests landmarks"| node_landmarks
node_cropper -->|"requests landmarks"| node_animal_landmarks
node_animal_landmarks -.->|"detects keypoints"| node_xpose
node_wrapper -.->|"runs networks"| node_networks
node_human_pipe -.->|"writes animation"| node_output
node_animal_pipe -.->|"writes animation"| node_output

click node_cli "https://github.com/kwaivgi/liveportrait/blob/main/inference.py"
click node_animal_cli "https://github.com/kwaivgi/liveportrait/blob/main/inference_animals.py"
click node_web "https://github.com/kwaivgi/liveportrait/blob/main/src/gradio_pipeline.py"
click node_human_pipe "https://github.com/kwaivgi/liveportrait/blob/main/src/live_portrait_pipeline.py"
click node_animal_pipe "https://github.com/kwaivgi/liveportrait/blob/main/src/live_portrait_pipeline_animal.py"
click node_wrapper "https://github.com/kwaivgi/liveportrait/blob/main/src/live_portrait_wrapper.py"
click node_config "https://github.com/kwaivgi/liveportrait/blob/main/src/config/inference_config.py"
click node_cropper "https://github.com/kwaivgi/liveportrait/blob/main/src/utils/cropper.py"
click node_crop_math "https://github.com/kwaivgi/liveportrait/blob/main/src/utils/crop.py"
click node_landmarks "https://github.com/kwaivgi/liveportrait/blob/main/src/utils/human_landmark_runner.py"
click node_animal_landmarks "https://github.com/kwaivgi/liveportrait/blob/main/src/utils/animal_landmark_runner.py"
click node_io "https://github.com/kwaivgi/liveportrait/blob/main/src/utils/io.py"
click node_video "https://github.com/kwaivgi/liveportrait/blob/main/src/utils/video.py"
click node_networks "https://github.com/kwaivgi/liveportrait/tree/main/src/modules"
click node_xpose "https://github.com/kwaivgi/liveportrait/tree/main/src/utils/dependencies/XPose"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_animal_cli,node_web,node_user toneBlue
class node_human_pipe,node_animal_pipe,node_wrapper,node_config toneAmber
class node_cropper,node_crop_math,node_landmarks,node_animal_landmarks,node_io,node_video toneMint
class node_networks,node_xpose toneRose
class node_output toneIndigo
```

## Components

### User interfaces

- [CLI inference](https://github.com/kwaivgi/liveportrait/blob/main/inference.py): `inference.py`
- [Animal CLI](https://github.com/kwaivgi/liveportrait/blob/main/inference_animals.py): `inference_animals.py`
- [Gradio controls](https://github.com/kwaivgi/liveportrait/blob/main/src/gradio_pipeline.py): `src/gradio_pipeline.py`

### Animation runtime

- [Human pipeline](https://github.com/kwaivgi/liveportrait/blob/main/src/live_portrait_pipeline.py): `src/live_portrait_pipeline.py`
- [Animal pipeline](https://github.com/kwaivgi/liveportrait/blob/main/src/live_portrait_pipeline_animal.py): `src/live_portrait_pipeline_animal.py`
- [Inference wrapper](https://github.com/kwaivgi/liveportrait/blob/main/src/live_portrait_wrapper.py): `src/live_portrait_wrapper.py`
- [Runtime configuration](https://github.com/kwaivgi/liveportrait/blob/main/src/config/inference_config.py): `src/config/inference_config.py`

### Input preparation

- [Face cropper](https://github.com/kwaivgi/liveportrait/blob/main/src/utils/cropper.py): `src/utils/cropper.py`
- [Crop geometry](https://github.com/kwaivgi/liveportrait/blob/main/src/utils/crop.py): `src/utils/crop.py`
- [Landmark detection](https://github.com/kwaivgi/liveportrait/blob/main/src/utils/human_landmark_runner.py): `src/utils/human_landmark_runner.py`
- [Animal landmarks](https://github.com/kwaivgi/liveportrait/blob/main/src/utils/animal_landmark_runner.py): `src/utils/animal_landmark_runner.py`
- [Image video I/O](https://github.com/kwaivgi/liveportrait/blob/main/src/utils/io.py): `src/utils/io.py`
- [Video utilities](https://github.com/kwaivgi/liveportrait/blob/main/src/utils/video.py): `src/utils/video.py`

### Learned models

- [Animation networks](https://github.com/kwaivgi/liveportrait/tree/main/src/modules): `src/modules`
- [X-Pose dependency](https://github.com/kwaivgi/liveportrait/tree/main/src/utils/dependencies/XPose): `src/utils/dependencies/XPose`

### Other components

- **User**
- **Generated media**

## Connections

- User → CLI inference: supplies inputs
- User → Animal CLI: supplies inputs
- User → Gradio controls: edits animation
- CLI inference → Human pipeline: runs (evidence: `inference.py`)
- Animal CLI → Animal pipeline: runs (evidence: `inference_animals.py`)
- Gradio controls → Human pipeline: dispatches (evidence: `src/gradio_pipeline.py`)
- Gradio controls → Animal pipeline: dispatches (evidence: `src/gradio_pipeline.py`)
- Human pipeline → Runtime configuration: uses settings (evidence: `src/live_portrait_pipeline.py`)
- Animal pipeline → Runtime configuration: uses settings (evidence: `src/live_portrait_pipeline_animal.py`)
- Human pipeline → Face cropper: crops frames (evidence: `src/live_portrait_pipeline.py`)
- Animal pipeline → Face cropper: crops frames (evidence: `src/live_portrait_pipeline_animal.py`)
- Human pipeline → Inference wrapper: runs inference (evidence: `src/live_portrait_pipeline.py`)
- Animal pipeline → Inference wrapper: runs inference (evidence: `src/live_portrait_pipeline_animal.py`)
- Human pipeline → Image video I/O: loads media (evidence: `src/live_portrait_pipeline.py`)
- Animal pipeline → Image video I/O: loads media (evidence: `src/live_portrait_pipeline_animal.py`)
- Human pipeline → Video utilities: reads video metadata (evidence: `src/live_portrait_pipeline.py`)
- Face cropper → Crop geometry: uses geometry (evidence: `src/utils/cropper.py`)
- Face cropper → Landmark detection: requests landmarks (evidence: `src/utils/cropper.py`)
- Face cropper → Animal landmarks: requests landmarks (evidence: `src/utils/cropper.py`)
- Animal landmarks → X-Pose dependency: detects keypoints
- Inference wrapper → Animation networks: runs networks
- Human pipeline → Generated media: writes animation
- Animal pipeline → Generated media: writes animation
