double-take

Double Take

Unified UI and API for processing and training images for facial recognition.

Why?

There's a lot of great open source software to perform facial recognition, but each of them behave differently. Double Take was created to abstract the complexities of the detection services and combine them into an easy to use UI and API.

Features

• Responsive UI and API bundled into single Docker image
• Ability to password protect UI and API
• Support for multiple detectors
• Train and untrain images for subjects
• Process images from NVRs
• Publish results to MQTT topics
• REST API can be invoked by other applications
• Disable detection based on a schedule
• Home Assistant Add-ons
• Preprocess images with OpenCV

Supported Architecture

• amd64
• arm64
• arm/v7

Supported Detectors

• CompreFace
• Amazon Rekognition
• DeepStack
• Facebox

Supported NVRs

• Frigate

Integrations

Frigate

Subscribe to Frigate's MQTT topics and process images for analysis.

mqtt:
  host: localhost

frigate:
  url: http://localhost:5000

When the frigate/events topic is updated the API begins to process the snapshot.jpg and latest.jpg images from Frigate's API. These images are passed from the API to the configured detector(s) until a match is found that meets the configured requirements. To improve the chances of finding a match, the processing of the images will repeat until the amount of retries is exhausted or a match is found.

When the frigate/+/person/snapshot topic is updated the API will process that image with the configured detector(s). It is recommended to increase the MQTT snapshot size in the Frigate camera config.

cameras:
  front-door:
    mqtt:
      timestamp: False
      bounding_box: False
      crop: True
      quality: 100
      height: 500

If a match is found the image is saved to /.storage/matches/<filename>.

Home Assistant

Trigger automations / notifications when images are processed.

If the MQTT integration is configured within Home Assistant, then sensors will automatically be created.

Notification Automation

This notification will work for both matches and unknown results. The message can be customized with any of the attributes from the entity.

…

MQTT

Publish results to double-take/matches/<name> and double-take/cameras/<camera>. The number of results will also be published to double-take/cameras/<camera>/person and will reset back to 0 after 30 seconds.

Errors from the API will be published to double-take/errors.

mqtt:
  host: localhost

double-take/matches/david

{
  "id": "1623906078.684285-5l9hw6",
  "duration": 1.26,
  "timestamp": "2021-06-17T05:01:36.030Z",
  "attempts": 3,
  "camera": "living-room",
  "zones": [],
  "match": {
    "name": "david",
    "confidence": 66.07,
    "match": true,
    "box": { "top": 308, "left": 1018, "width": 164, "height": 177 },
    "type": "latest",
    "duration": 0.28,
    "detector": "compreface",
    "filename": "2f07d1ad-9252-43fd-9233-2786a36a15a9.jpg",
    "base64": null
  }
}

double-take/cameras/back-door

…

Notify Services

Gotify

notify:
  gotify:
    url: http://localhost:8080
    token:

API Images

Match images are saved to /.storage/matches and can be accessed via http://localhost:3000/api/storage/matches/<filename>.

Training images are saved to /.storage/train and can be accessed via http://localhost:3000/api/storage/train/<name>/<filename>.

Latest images are saved to /.storage/latest and can be accessed via http://localhost:3000/api/storage/latest/<name|camera>.jpg.

UI

The UI is accessible via http://localhost:3000.

• Matches: /
• Train: /train
• Config: /config
• Access Tokens: /tokens (if authentication is enabled)

Authentication

Enable authentication to password protect the UI. This is recommended if running Double Take behind a reverse proxy which is exposed to the internet.

auth: true

API

Documentation can be viewed on Postman.

Usage

Docker Compose

version: '3.7'

volumes:
  double-take:

services:
  double-take:
    container_name: double-take
    image: jakowenko/double-take
    restart: unless-stopped
    volumes:
      - double-take:/.storage
    ports:
      - 3000:3000

Configuration

Configurable options are saved to /.storage/config/config.yml and are editable via the UI at http://localhost:3000/config. Default values do not need to be specified in configuration unless they need to be overwritten.

auth

# enable authentication for ui and api (default: shown below)
auth: false

token

# if authentication is enabled
# age of access token in api response and mqtt topics (default: shown below)
# expressed in seconds or a string describing a time span zeit/ms
# https://github.com/vercel/ms
token:
  image: 24h

mqtt

…

detect

…

frigate

…

cameras

…

detectors

…

opencv

# opencv settings (default: shown below)
# docs: https://docs.opencv.org/4.6.0/d1/de5/classcv_1_1CascadeClassifier.html
opencv:
  scale_factor: 1.05
  min_neighbors: 4.5
  min_size_width: 30
  min_size_height: 30

schedule

# schedule settings (default: shown below)
schedule:
  # disable recognition if conditions are met
  disable:
    # - days:
    #     - monday
    #     - tuesday
    #   times:
    #     - 20:00-23:59
    #   cameras:
    #     - office
    # - days:
    #     - tuesday
    #     - wednesday
    #   times:
    #     - 13:00-15:00
    #     - 18:00-20:00
    #   cameras:
    #     - living-room

notify

# notify settings (default: shown below)
notify:
  gotify:
    url:
    token:
    priority: 5

    # only notify from specific cameras
    # cameras:
    #   - front-door
    #   - garage

    # only notify from specific zones
    # zones:
    #   - camera: garage
    #     zone: driveway

time

# time settings (default: shown below)
time:
  # defaults to iso 8601 format with support for token-based formatting
  # https://github.com/moment/luxon/blob/master/docs/formatting.md#table-of-tokens
  format:
  # time zone used in logs
  timezone: UTC

logs

# log settings (default: shown below)
# options: silent, error, warn, info, http, verbose, debug, silly
logs:
  level: info

ui

# ui settings (default: shown below)
ui:
  # base path of ui
  path:

  pagination:
    # number of results per page
    limit: 50

  thumbnails:
    # value between 0-100
    quality: 95
    # value in pixels
    width: 500

  logs:
    # number of lines displayed
    lines: 500

telemetry

# telemetry settings (default: shown below)
# self hosted version of plausible.io
# 100% anonymous, used to help improve project
# no cookies and fully compliant with GDPR, CCPA and PECR
telemetry: true

Storing Secrets

Note: If using one of the Home Assistant Add-ons then the default Home Assistant /config/secrets.yaml file is used.

mqtt:
  host: localhost
  username: mqtt
  password: !secret mqtt_password

detectors:
  compreface:
    url: localhost:8000
    key: !secret compreface_key

The secrets.yml file contains the corresponding value assigned to the identifier.

mqtt_password: <password>
compreface_key: <api-key>

Development

Run Local Containers

# start development containers
./.develop/docker up

# remove development containers
./.develop/docker down

Build Local Image

./.develop/build

Donations

If you would like to make a donation to support development, please use GitHub Sponsors.