The facebox image processing platform allows you to detect and recognize faces in a camera image using Facebox. The state of the entity is the number of faces detected, and recognized faces are listed in the matched_faces attribute. An image_processing.detect_face event is fired for each recognized face, and the event data provides the confidence of recognition, the name of the person, the image_id of the image associated with the match, the bounding_box that contains the face in the image, and the entity_id that processing was performed on.


Facebox runs in a Docker container and it is recommended that you run this container on a machine with a minimum of 2 GB RAM. On your machine with Docker, run the Facebox container with:


sudo docker run --name=facebox --restart=always -p 8080:8080 -e "MB_KEY=$MB_KEY"  machinebox/facebox

If you only require face detection (number of faces) you can disable face recognition by adding -e "MB_FACEBOX_DISABLE_RECOGNITION=true" to the docker run command.


To enable this platform in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
  - platform: facebox
    port: 8080
      - entity_id: camera.local_file
        name: my_custom_name

Configuration Variables


(string)(Required)The IP address of your machine hosting Facebox.


(string)(Required)The port which Facebox is exposed on.


(map)(Required)The list of image sources.


(string)(Required)A camera entity id to get picture from.


(string)(Optional)This parameter allows you to override the name of your image_processing entity.


Use the image_processing.detect_face events to trigger automations, and breakout the trigger.event.data using a data_template. The following example automation sends a notification when Ringo Star is recognized:

- id: '12345'
  alias: Ringo Starr recognised
    platform: event
    event_type: image_processing.detect_face
      name: 'Ringo_Starr'
    service: notify.platform
      message: Ringo_Starr recognised with probability {{ trigger.event.data.confidence }}
      title: Door-cam notification

Service facebox_teach_face

The service facebox_teach_face can be used to teach Facebox faces.

Service data attribute Optional Description
entity_id no Entity ID of Facebox entity.
name no The name to associate with a face.
file_path no The path to the image file.

A valid service data example:

  "entity_id": "image_processing.facebox_local_file",
  "name": "superman",
  "file_path": "/images/superman_1.jpeg"

An image_processing.teach_classifier event is fired for each service call, providing feedback on whether teaching has been successful or unsuccessful. In the unsuccessful case, the message field of the event_data will contain information on the cause of failure, and a warning is also published in the logs. An automation can be used to receive alerts on teaching, for example, the following automation will send a notification with the teaching image and a message describing the status of the teaching:

- id: '11200961111'
  alias: Send facebox teaching result
    platform: event
    event_type: image_processing.teach_classifier
      classifier: facebox
    service: notify.platform
      title: Facebox teaching
      message: Name  teaching was successful? 
        file: '  '

Optimising resources

Image processing components process the image from a camera at a fixed period given by the scan_interval. This leads to excessive processing if the image on the camera hasn’t changed, as the default scan_interval is 10 seconds. You can override this by adding to your config scan_interval: 10000 (setting the interval to 10,000 seconds), and then call the image_processing.scan service when you actually want to perform processing.