FaceCue

FaceCue is an intelligent video analysis tool that detects individuals in video footage, estimates their age and gender, and identifies their facial expressions—specifically detecting smiles. Built with Python, it is optimized for real-time inference and precision, returning timestamps where smiles are detected.

Table of Contents

• Features
• System Requirements
• Installation
• Usage
• Configuration Parameters
• Performance Recommendations
• Sample Output

Features

• Face detection in video frames
• Age estimation
• Gender classification
• Smile detection through facial expression recognition
• Timestamp-based reporting of detected smiles and expressions

System Requirements

• Python: 3.12 (recommended)
• Poetry: ≥ 2.1.2
• Git LFS: Required for model file management

Installation

Clone the repository:

git clone https://github.com/barakahworks-enterprise/uwfm-facecue
cd uwfm-facecue

Install Git LFS and pull required model files:

git lfs install
git lfs pull

Install dependencies using Poetry:

poetry install

Usage

Run FaceCue on a sample video:

poetry run python src/main.py samples/10.mp4

Replace samples/1.mp4 with the path to your own video file.

Configuration Parameters

Initialization parameters:

def __init__(self, face_detector_threshold=0.5, person_similarity_threshold=0.5):

• face_detector_threshold: Adjusts face detection sensitivity.
• person_similarity_threshold: Controls tracking consistency of individuals across frames.

Processing parameters:

def process(self, video_file_path, sampling_fps=10):

• video_file_path: Path to the input video.
• sampling_fps: Frames per second to sample. Lower values improve speed.

Performance Recommendations

• High-definition (HD or 4K) videos do not improve analysis quality.
• The model automatically rescales inputs to medium resolution internally.
• To save processing time and resources, use mid-range resolution videos (e.g., 720p or less).

Sample Output

FaceCue returns a dictionary where each key is a timestamp (HH:MM:SS) and the value is a list of detected individuals with their properties:

{
    "00:00:00": [
        { "age": 2, "ageGroup": "0-12", "gender": "M", "isSmiling": true, "expression": "HAP" },
        { "age": 29, "ageGroup": "18-34", "gender": "F", "isSmiling": true, "expression": "HAP" }
    ],
    "00:00:06": [{ "age": 28, "ageGroup": "18-34", "gender": "F", "isSmiling": true, "expression": "HAP" }],
    "00:00:10": [{ "age": 29, "ageGroup": "18-34", "gender": "F", "isSmiling": true, "expression": "NEU" }]
}

Each detection contains:

• age: Estimated age
• ageGroup: Age group classification
• gender: Estimated gender ('M' or 'F')
• isSmiling: Indicates if the individual is smiling
• expression: Detected dominant facial expression