# Face Tracker

## What is FaceTracker?

`FaceTracker` builds on `FaceRecognizer` capabilities for **production video surveillance applications**. While `FaceRecognizer` processes individual images independently, `FaceTracker` adds persistent face tracking, automated alerting, video clip recording, and live streaming capabilities for continuous video monitoring.

## Key Differences from FaceRecognizer

| Capability                | FaceRecognizer                  | FaceTracker                               |
| ------------------------- | ------------------------------- | ----------------------------------------- |
| **Identity persistence**  | Each frame processed separately | Stable track IDs across frames            |
| **Embedding extraction**  | Every frame (redundant)         | Adaptive backoff (10-20x reduction)       |
| **Alerting**              | Manual implementation required  | Built-in modes with configurable triggers |
| **Video evidence**        | Not supported                   | Automatic clip recording to S3/local      |
| **Notifications**         | Not supported                   | Integrated Apprise (email, Slack, SMS)    |
| **Live streaming**        | Not supported                   | Local display or RTSP web streaming       |
| **Video post-processing** | Not supported                   | Extract and enroll faces from clips       |

## When to Use FaceTracker

| Use Case                        | Recommended Class | Why                                        |
| ------------------------------- | ----------------- | ------------------------------------------ |
| Real-time video streams         | `FaceTracker`     | Persistent track IDs, reduced re-embedding |
| Alerting on unknown faces       | `FaceTracker`     | Built-in alert modes and notifications     |
| Clip recording                  | `FaceTracker`     | Automatic video clip saving                |
| Video with temporal consistency | `FaceTracker`     | Maintains face identity across frames      |
| Single images                   | `FaceRecognizer`  | Simple, direct recognition                 |
| Batch of images                 | `FaceRecognizer`  | Pipeline parallelism for throughput        |

## Core Concepts

### FaceTrackerConfig

`FaceTrackerConfig` extends `FaceRecognizerConfig` and configures all aspects of video tracking. It inherits base settings (model specs, database path, similarity threshold, face filters) and adds tracking-specific parameters:

* **Video source** - Webcam, file, or RTSP stream
* **Credence count** - Frames required to confirm a face
* **Alert mode and notifications** - When and how to alert
* **Clip storage** - Save video clips to S3 or local storage
* **Live streaming** - Display output locally or via RTSP

See [Configuration Guide](https://docs.degirum.com/face-recognition/guides/overview-1/configuration) for complete parameter reference and examples.

### Track IDs

Unlike `FaceRecognizer` which processes each frame independently, `FaceTracker` assigns persistent track IDs to faces as they move across frames. This enables:

* Reduced computational cost (avoid re-extracting embeddings for same person)
* Consistent identity throughout video
* Alert once per person (not per frame)

### Credence Count

Number of consecutive frames a face must appear before being confirmed as a valid track. Higher values reduce false positives from momentary detections or camera noise.

### Alert Modes

* `AlertMode.NONE` - No alerts
* `AlertMode.ON_UNKNOWNS` - Alert when unrecognized faces appear
* `AlertMode.ON_KNOWNS` - Alert when enrolled faces appear
* `AlertMode.ON_ALL` - Alert for all faces

### Adaptive Re-identification

When the ReID expiration filter is enabled in face filters configuration, `FaceTracker` uses exponential backoff to reduce embedding extraction frequency for stable tracks. Instead of extracting embeddings every frame, the interval increases exponentially (1 → 2 → 4 → 8 → 16 → ...) up to the configured maximum `reid_expiration_frames`, improving performance 10-20x while maintaining accurate tracking. See [ReID Expiration Filter](https://docs.degirum.com/face-recognition/guides/configuration#reid-expiration-filter) for configuration details.

## Methods

`FaceTracker` provides specialized methods for different video processing workflows:

* [**start\_face\_tracking\_pipeline()**](https://docs.degirum.com/face-recognition/guides/methods#start_face_tracking_pipeline) - Real-time monitoring with automated alerts and clip recording
* [**predict\_batch()**](https://docs.degirum.com/face-recognition/guides/methods#predict_batch) - Stream processing with programmatic access to results
* [**find\_faces\_in\_file()**](https://docs.degirum.com/face-recognition/guides/methods#find_faces_in_file) - Analyze local video files
* [**find\_faces\_in\_clip()**](https://docs.degirum.com/face-recognition/guides/methods#find_faces_in_clip) - Analyze cloud storage clips
* [**enroll()**](https://docs.degirum.com/face-recognition/guides/methods#enroll) - Add faces from video to database