No description, website, or topics provided.
Branch: master
Clone or download
Pull request Compare This branch is 7 commits behind jcheong0428:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Build Status Coverage Status

FaceSync: Open source framework for recording facial expressions with head-mounted cameras

The FaceSync toolbox provides 3D blueprints for building the head-mounted camera setup described in our paper. The toolbox also provides functions to automatically synchronize videos based on audio, manually align audio, plot facial landmark movements, and inspect synchronized videos to graph data.


To install (for osx or linux) open Terminal and type

pip install facesync


git clone then in the repository folder type python install


For full functionality, FACESYNC requires ffmpeg and the libav library.

Linux sudo apt-get install libav-tools

OS X brew install ffmpeg brew install libav

also requires following packages:

  • python 2.7.x
  • numpy
  • scipy You may also install these via pip install -r requirements.txt

Recommended Processing Steps

  1. Extract Audio from Target Video
  2. Find offset with Extracted Audio
  3. Trim Video using Offset. *If you need to resize your video, do so before trimming. Otherwise timing can be off.
from facesync.facesync import facesync
# change file name to include the full 
video_files = ['path/to/sample1.MP4']
target_audio = 'path/to/cosan_synctune.wav'
# Intialize facesync class
fs = facesync(video_files=video_files,target_audio=target_audio)
# Extracts audio from sample1.MP4
# Find offset by correlation 
# Find offset by fast fourier transform 

FaceSync provides handy utilities for working with facial expression data.

Manually align the audios with AudioAligner.

Plot facial landmarks and how they change as a result of Action Unit changes.

Use the VideoViewer widget to play both video and data at the same time (only available on Python).


Please cite the following paper if you use our head-mounted camera setup or software.

Cheong, J. H., Brooks, S., & Chang, L. J. (2017, November 1). FaceSync: Open source framework for recording facial expressions with head-mounted cameras. Retrieved from