LibreFace
[WACV 2024 & FG 2026] LibreFace: An Open-Source Toolkit for Deep Facial Expression Analysis
Install / Use
npx skills add ihp-lab/LibreFaceInstalls into whichever agent you are using.
README
<a href="https://ict.usc.edu/">Institute for Creative Technologies, University of Southern California</a> <br />
📑 Table of Contents
- Introduction
- Getting started with Python installation
- Usage
- Getting Started with Derivative Tools
- Gaze estimation
- Synthetic Data for LibreFace 2.0
- Training models
- Results and Accuracy
- TODO
- License
- Citation
- Contact
- Acknowledgments
👋 Introduction
This is the official implementation of our WACV 2024 Application Track paper: LibreFace: An Open-Source Toolkit for Deep Facial Expression Analysis. The recent update (May 2026) incorporates the code and checkpoints for our FG 2026 paper "LibreFace 2.0: A Generalizable Facial Expression Analysis Toolkit Leveraging Synthetic Data". LibreFace is an open-source and comprehensive toolkit for accurate and real-time facial expression analysis with both CPU-only and GPU-acceleration versions. LibreFace eliminates the gap between cutting-edge research and an easy and free-to-use non-commercial toolbox. We propose to adaptively pre-train the vision encoders with various face datasets and then distillate them to a lightweight ResNet-18 and RepVGG models in a feature-wise matching manner. LibreFace 2.0 additionally supports gaze estimation using a MediaPipe landmark-based MLP pipeline. We conduct extensive experiments of pre-training and distillation to demonstrate that our proposed pipeline achieves comparable results to state-of-the-art works while maintaining real-time efficiency. LibreFace system supports cross-platform running, and the code is open-sourced in C# (model inference and checkpoints) and Python (model training, inference, and checkpoints).
<p align="center"> <img src="media/System.png" width="350px" /> </p>🚀 Getting started with Python installation
📦 Dependencies
- Python 3.9
- You should have
cmakeinstalled in your system.- For Linux users -
sudo apt-get install cmake. If you run into trouble, consider upgrading to the latest version (instructions). - For Mac users -
brew install cmake.
- For Linux users -
⚙️ Installation
You can first create a new Python 3.9 environment using conda and then install this package using pip from the PyPI hub:
conda create -n libreface_env python=3.9
conda activate libreface_env
pip install --upgrade libreface
🛠️ Usage
💻 Using commandline
You can use this package through the command line using the following command.
libreface --input_path="path/to/your_image_or_video"
Note that the above script would save results in a CSV at the default location - sample_results.csv.
If you want to specify your own output path, use the --output_path command line argument,
libreface --input_path="path/to/your_image_or_video" --output_path="path/to/save_results.csv"
To change the device used for inference, use the --device command line argument,
libreface --input_path="path/to/your_image_or_video" --device="cuda:0"
To save intermediate files, libreface uses a temporary directory that defaults to ./tmp. To change the temporary directory path,
libreface --input_path="path/to/your_image_or_video" --temp="your/temp/path"
For video inference, our code processes the frames of your video in batches. You can specify the batch size and the number of workers for data loading as follows,
libreface --input_path="path/to/your_video" --batch_size=256 --num_workers=2 --device="cuda:0"
Note that by default, the --batch_size argument is 256, and --num_workers argument is 2. You can increase or decrease these values according to your machine's capacity.
Examples
Download a sample image from our GitHub repository. To get the facial attributes for this image and save to a CSV file, simply run,
libreface --input_path="sample_disfa.png"
Download a sample video from our GitHub repository. To run the inference on this video using a GPU and save the results to my_custom_file.csv run the following command,
libreface --input_path="sample_disfa.avi" --output_path="my_custom_file.csv" --device="cuda:0"
Note that for videos, each row in the saved CSV file corresponds to individual frames in the given video.
</details>🐍 Using Python script
Here’s how to use this package in your Python scripts.
import libreface
detected_attributes = libreface.get_facial_attributes(image_or_video_path)
To save the results to a csv file, use the output_save_path parameter,
import libreface
libreface.get_facial_attributes(image_or_video_path,
output_save_path = "your_save_path.csv")
To change the device used for inference, use the device parameter,
import libreface
libreface.get_facial_attributes(image_or_video_path,
device = "cuda:0") # can be "cpu" or "cuda:0", "cuda:1", ...
To save intermediate files, libreface uses a temporary directory that defaults to ./tmp. To change the temporary directory path, use the temp_dir parameter,
import libreface
libreface.get_facial_attributes(image_or_video_path,
temp_dir = "your/temp/path")
For video inference, our code processes the frames of your video in batches. You can specify the batch size and the number of workers for data loading as follows,
import libreface
libreface.get_facial_attributes(video_path,
batch_size = 256,
num_workers = 2)
Note that by default, the batch_size is 256, and num_workers is 2. You can increase or decrease these values according to your machine's capacity.
Weights of the model are automatically downloaded at ./libreface_weights/ directory. If you want to download and save the weights to a separate directory, please specify the parent folder for weights using the weights_download_dir as follows,
import libreface
libreface.get_facial_attributes(image_or_video_path,
weights_download_dir = "your/directory/path")
import libreface
aligned_image_path, _, _ = libreface.get_aligned_image("path/to/your_image.png", temp_dir="./tmp")
gaze = libreface.estimate_gaze(aligned_image_path, device="cpu")
print(gaze) # {'gaze_yaw': <float>, 'gaze_pitch': <float>}
For videos, pass a list of aligned frame paths:
import libreface
gaze_df = libreface.estimate_gaze_video(aligned_frames_path_list,
device="cuda:0",
batch_size=256,
num_workers=2)
# gaze_df has columns "gaze_yaw" and "gaze_pitch", one row per frame.
🧩 Getting Started with Derivative Tools (New 2.0 Models Available! Recommended)
We offer several derivative tools on the .NET platform to facilitate easier integration
Related Skills
node-connect
385.5kDiagnose OpenClaw Android, iOS, or macOS node pairing, QR/setup code, route, auth, and connection failures.
blender-python-addon
40.5kBlender Python add-on rules for operators, panels, properties, registration, testing, and API-safe scripting
flutter-development-guidelines-cursorrules-prompt-file
40.5kCursor rules for Flutter development with MVVM architecture, Riverpod state management, Material widgets, and Dart style guidelines.
commit-push-pr
140.7kCommit, push, and open a PR
