example-config.yaml

# FaceID configuration — copy to config.yaml and adjust.
# config.yaml is gitignored: it contains your MQTT credentials.

frigate:
  enabled: true                         # false when folder input is used without Frigate
  # Either Frigate's open API (port 5000) or its authenticated one (8971, https).
  # For 8971 add user/password below; see README "Connecting to Frigate".
  url: http://192.168.1.10:5000        # your Frigate base URL
  # user: faceid            # optional — only for the authenticated port 8971
  # password: secret        # a viewer account can read; sub_label write-back needs admin
  # verify_tls: false       # Frigate ships a self-signed certificate by default

mqtt:
  enabled: true                         # false keeps the UI working without an MQTT broker
  host: 192.168.1.2                    # your MQTT broker (same one Frigate uses)
  port: 1883
  user: mqtt-user
  password: "mqtt-password"

# Optional alternative input: watch completed recordings instead of Frigate events.
# Files are never changed or deleted. Size and mtime must remain stable across two scans,
# and successful fingerprints are remembered in data/folder_ingest.json across restarts.
folder:
  enabled: false
  path: /recordings
  camera: front_door
  recursive: true
  process_existing: true                # false starts with files created after first launch
  # Videos by default. Still images work too — the same face pipeline runs on them —
  # but only if their extension is in this list. To add them, REPLACE the line below
  # (do not add a second `extensions:` key — YAML keeps only the last one):
  #   extensions: [.mp4, .mkv, .mov, .avi, .webm, .m4v, .jpg, .jpeg, .png, .webp]
  extensions: [.mp4, .mkv, .mov, .avi, .webm, .m4v]
  poll_interval: 10                     # seconds between directory scans
  settle_seconds: 10                    # final filename must also be this old
  max_frames: 24                        # evenly sampled across each recording
  min_detection_score: 0.65
  same_person_similarity: 0.55          # collapse repeated views within one recording
  max_people_per_file: 6
  max_retries: 3
  retry_seconds: 60
  # Obergrenze fuer den Fingerabdruck-Index (data/folder_ingest.json). Er merkt sich jede
  # verarbeitete Datei, damit ein Neustart nicht den ganzen Ordner neu einliest, und wird
  # bei jeder Datei neu geschrieben — ohne Grenze waechst die Schreibzeit mit der Historie.
  # 0 = unbegrenzt. Aelteste fliegen zuerst raus; gelernte Gesichter sind nicht betroffen.
  # Auskommentiert lassen, wenn die Grenze im Einstellungen-Tab gesetzt werden soll: ein
  # Wert HIER hat Vorrang und wuerde die dort gesetzte bei jedem Neustart ueberschreiben.
  # max_indexed_files: 5000

faceid:
  port: 8600                           # web UI / API port
  # MQTT topic prefix + client id — change only when running multiple instances
  mqtt_prefix: faceid
  # Cosine-similarity thresholds (ArcFace embeddings):
  #   >= match_threshold  -> recognized (published + Frigate sub_label)
  #   <  unknown_threshold -> definitely a stranger
  #   in between           -> uncertain; goes to the review queue only
  match_threshold: 0.50
  unknown_threshold: 0.35
  # A match score is the mean of the top-k most similar reference photos of a person.
  # Higher resists a single lucky photo, but drags down people whose references cover
  # many angles — their own less similar photos pull the mean. Measure before changing:
  # scripts/measure-recognition.py --top-k N. On one real gallery, 1 nearly doubled
  # correct recognitions over 3 with no misassignments.
  match_top_k: 3
  max_faces_per_person: 40             # soft cap; the most redundant photo is set aside
  trimmed_keep: 10                     # how many set-aside photos to keep per person (0 = delete)
  dedupe_threshold: 0.65               # default sensitivity of the "remove duplicates" action
  hires_enroll: true                   # fetch review-queue faces from the recording instead of
                                       # the detect snapshot — typically twice the face size
  clip_fallback: true                  # when the snapshot holds no face AT ALL, scan the
                                       # recording. Frigate picks its snapshot by highest
                                       # PERSON score, which is often the moment someone
                                       # turns away — measured here, only ~21% of snapshots
                                       # had a usable face. Runs once per event, only for
                                       # events that produced nothing, on its own thread.
  clip_fallback_cameras: []            # [] = every camera. Restrict it once you know
                                       # which ones benefit: the gain depends almost
                                       # entirely on the viewing angle. A camera at head
                                       # height rescues nearly every failed event; a
                                       # high-mounted one rescues none, because nobody
                                       # looks up at it — the clip holds no face either
                                       # and the scan costs seconds per event for nothing.
                                       # scripts/why-no-face.py --clip tells you which.
  live_hires_fallback: false           # for automations that must react WHILE someone is
                                       # at the door. clip_fallback only runs once an event
                                       # has ended, and a recorded moment is not retrievable
                                       # for ~45s — too late to greet anyone. go2rtc serves
                                       # the main stream in about a second instead. Needs
                                       # go2rtc on port 1984 (ships with Frigate, but is not
                                       # always exposed); the startup log says whether it
                                       # answers. Runs once per event, snapshot path first.
  live_hires_fallback_cameras: []      # [] = every camera
  live_hires_mode: fallback            # fallback = only when the snapshot found nothing.
                                       # always = scan the full frame on every event, with
                                       # Frigate acting only as the trigger. Catches people
                                       # Frigate never tracked as their own object (someone
                                       # partly hidden). Measure first: over 7 days here,
                                       # 0 of 15 groups held more faces than Frigate
                                       # reported events, so it only added cost.
  live_hires_cooldown: 2               # seconds; collapses the burst of events one group
                                       # produces into a single full-frame scan
  clip_fallback_frames: 12             # frames sampled across the clip
  clip_fallback_min_det: 0.65          # stricter than the snapshot path (0.55): with twelve
                                       # frames to choose from you can afford to be picky
  clip_fallback_retries: 3             # Frigate finalises the clip a moment after the event
                                       # ends; without a retry the event is discarded because
                                       # of a file that exists seconds later (~1 scan in 4)
  clip_fallback_retry_seconds: 10      # wait between those retries
  ignore_threshold: 0.50               # similarity at which a face counts as ignored
                                       # (defaults to match_threshold when unset)
  max_ignore_anchors: 0                # cap on AUTO-learned ignore anchors per group
                                       # (0 = unlimited). Drops the most redundant one,
                                       # never a manually added anchor — deleting by age
                                       # would let ignored people resurface.
  ignore_learning: true                # learn new looks of ignored people as extra anchors
  min_face_px: 48                      # minimum face size in the snapshot (pixels)
  det_size: 640                        # detection input size (higher = better far faces, slower)
  max_attempts: 6                      # recognition attempts per Frigate event
  frigate_topic_prefix: frigate        # must match `mqtt.topic_prefix` in Frigate's config
  poll_interval: 0                     # seconds; >0 also polls Frigate's event API.
                                       # Catches events MQTT never announces — notably
                                       # ones created through Frigate's API (e.g. a
                                       # camera's own person detection used as a
                                       # reliability bridge). 30 is a sensible value.
  retry_seconds: 2.5                   # min. seconds between attempts on the same event
  cluster_eps: 0.55                    # DBSCAN cosine distance for grouping unknowns in the UI
  # review UI: unknown faces with a best-match score >= this get grouped into a
  # "Looks like <person>" suggestion with the dropdown pre-selected. Keep below
  # match_threshold so borderline faces are pre-sorted without weak-match noise.
  suggest_threshold: 0.40
  set_sub_label: true                  # write recognized names back to Frigate events
  presence_window: 120                 # camera sensor shows everyone seen within this window (s)
  # process events only from these cameras (empty = all cameras)
  cameras: []
  # cameras that get a Home Assistant discovery sensor (sensor.faceid_<camera>)
  discovery_cameras: [front_door, garden]
  # optional HTTP Basic Auth for the web UI + API (recommended for standalone
  # installs; leave empty to disable — the HA add-on is protected by ingress)
  auth:
    user: ""
    password: ""