Ability to manually create events through the API (blakeblackshear#3184)

* Move to events package

* Improve handling of external events

* Handle external events in the event queue

* Pass in event processor

* Check event json

* Fix json parsing and change defaults

* Fix snapshot saving

* Hide % score when not available

* Correct docs and add json example

* Save event png db

* Adjust image

* Formatting

* Add catch for failure ending event

* Add init to modules

* Fix naming

* Formatting

* Fix http creation

* fix test

* Change to PUT and include response in docs

* Add ability to set bounding box locations in snapshot

* Support multiple box annotations

* Cleanup docs example response

Co-authored-by: Blake Blackshear <[email protected]>

* Cleanup docs wording

Co-authored-by: Blake Blackshear <[email protected]>

* Store full frame for thumbnail

* Formatting

* Set thumbnail height to 175

* Formatting

---------

Co-authored-by: Blake Blackshear <[email protected]>

docs/docs/integrations/api.md

@@ -295,3 +295,41 @@ Get ffprobe output for camera feed paths.
 ### `GET /api/<camera_name>/ptz/info`
 
 Get PTZ info for the camera.
+
+### `POST /api/events/<camera_name>/<label>/create`
+
+Create a manual API with a given `label` (ex: doorbell press) to capture a specific event besides an object being detected.
+
+**Optional Body:**
+
+```json
+{
+ "subLabel": "some_string", // add sub label to event
+ "duration": 30, // predetermined length of event (default: 30 seconds) or can be to null for indeterminate length event
+ "include_recording": true, // whether the event should save recordings along with the snapshot that is taken
+ "draw": {
+ // optional annotations that will be drawn on the snapshot
+ "boxes": [
+ {
+ "box": [0.5, 0.5, 0.25, 0.25], // box consists of x, y, width, height which are on a scale between 0 - 1
+ "color": [255, 0, 0], // color of the box, default is red
+ "score": 100 // optional score associated with the box
+ }
+ ]
+ }
+}
+```
+
+**Success Response:**
+
+```json
+{
+ "event_id": "1682970645.13116-1ug7ns",
+ "message": "Successfully created event.",
+ "success": true
+}
+```
+
+### `PUT /api/events/<event_id>/end`
+
+End a specific manual event without a predetermined length.

frigate/app.py

@@ -28,7 +28,9 @@
  RECORD_DIR,
 )
 from frigate.object_detection import ObjectDetectProcess
-from frigate.events import EventCleanup, EventProcessor
+from frigate.events.cleanup import EventCleanup
+from frigate.events.external import ExternalEventProcessor
+from frigate.events.maintainer import EventProcessor
 from frigate.http import create_app
 from frigate.log import log_process, root_configurer
 from frigate.models import Event, Recordings, Timeline
@@ -204,6 +206,11 @@ def init_stats(self) -> None:
  self.config, self.camera_metrics, self.detectors, self.processes
  )
 
+ def init_external_event_processor(self) -> None:
+ self.external_event_processor = ExternalEventProcessor(
+ self.config, self.event_queue
+ )
+
  def init_web_server(self) -> None:
  self.flask_app = create_app(
  self.config,
@@ -212,6 +219,7 @@ def init_web_server(self) -> None:
  self.detected_frames_processor,
  self.storage_maintainer,
  self.onvif_controller,
+ self.external_event_processor,
  self.plus_api,
  )
 
@@ -436,6 +444,7 @@ def start(self) -> None:
  self.start_camera_capture_processes()
  self.start_storage_maintainer()
  self.init_stats()
+ self.init_external_event_processor()
  self.init_web_server()
  self.start_timeline_processor()
  self.start_event_processor()

frigate/events/cleanup.py

@@ -0,0 +1,176 @@
+"""Cleanup events based on configured retention."""
+
+import datetime
+import logging
+import os
+import threading
+
+from pathlib import Path
+
+from peewee import fn
+
+from frigate.config import FrigateConfig
+from frigate.const import CLIPS_DIR
+from frigate.models import Event
+
+from multiprocessing.synchronize import Event as MpEvent
+
+logger = logging.getLogger(__name__)
+
+
+class EventCleanup(threading.Thread):
+ def __init__(self, config: FrigateConfig, stop_event: MpEvent):
+ threading.Thread.__init__(self)
+ self.name = "event_cleanup"
+ self.config = config
+ self.stop_event = stop_event
+ self.camera_keys = list(self.config.cameras.keys())
+
+ def expire(self, media_type: str) -> None:
+ # TODO: Refactor media_type to enum
+ ## Expire events from unlisted cameras based on the global config
+ if media_type == "clips":
+ retain_config = self.config.record.events.retain
+ file_extension = "mp4"
+ update_params = {"has_clip": False}
+ else:
+ retain_config = self.config.snapshots.retain
+ file_extension = "jpg"
+ update_params = {"has_snapshot": False}
+
+ distinct_labels = (
+ Event.select(Event.label)
+ .where(Event.camera.not_in(self.camera_keys))
+ .distinct()
+ )
+
+ # loop over object types in db
+ for l in distinct_labels:
+ # get expiration time for this label
+ expire_days = retain_config.objects.get(l.label, retain_config.default)
+ expire_after = (
+ datetime.datetime.now() - datetime.timedelta(days=expire_days)
+ ).timestamp()
+ # grab all events after specific time
+ expired_events = Event.select().where(
+ Event.camera.not_in(self.camera_keys),
+ Event.start_time < expire_after,
+ Event.label == l.label,
+ Event.retain_indefinitely == False,
+ )
+ # delete the media from disk
+ for event in expired_events:
+ media_name = f"{event.camera}-{event.id}"
+ media_path = Path(
+ f"{os.path.join(CLIPS_DIR, media_name)}.{file_extension}"
+ )
+ media_path.unlink(missing_ok=True)
+ if file_extension == "jpg":
+ media_path = Path(
+ f"{os.path.join(CLIPS_DIR, media_name)}-clean.png"
+ )
+ media_path.unlink(missing_ok=True)
+
+ # update the clips attribute for the db entry
+ update_query = Event.update(update_params).where(
+ Event.camera.not_in(self.camera_keys),
+ Event.start_time < expire_after,
+ Event.label == l.label,
+ Event.retain_indefinitely == False,
+ )
+ update_query.execute()
+
+ ## Expire events from cameras based on the camera config
+ for name, camera in self.config.cameras.items():
+ if media_type == "clips":
+ retain_config = camera.record.events.retain
+ else:
+ retain_config = camera.snapshots.retain
+ # get distinct objects in database for this camera
+ distinct_labels = (
+ Event.select(Event.label).where(Event.camera == name).distinct()
+ )
+
+ # loop over object types in db
+ for l in distinct_labels:
+ # get expiration time for this label
+ expire_days = retain_config.objects.get(l.label, retain_config.default)
+ expire_after = (
+ datetime.datetime.now() - datetime.timedelta(days=expire_days)
+ ).timestamp()
+ # grab all events after specific time
+ expired_events = Event.select().where(
+ Event.camera == name,
+ Event.start_time < expire_after,
+ Event.label == l.label,
+ Event.retain_indefinitely == False,
+ )
+ # delete the grabbed clips from disk
+ for event in expired_events:
+ media_name = f"{event.camera}-{event.id}"
+ media_path = Path(
+ f"{os.path.join(CLIPS_DIR, media_name)}.{file_extension}"
+ )
+ media_path.unlink(missing_ok=True)
+ if file_extension == "jpg":
+ media_path = Path(
+ f"{os.path.join(CLIPS_DIR, media_name)}-clean.png"
+ )
+ media_path.unlink(missing_ok=True)
+ # update the clips attribute for the db entry
+ update_query = Event.update(update_params).where(
+ Event.camera == name,
+ Event.start_time < expire_after,
+ Event.label == l.label,
+ Event.retain_indefinitely == False,
+ )
+ update_query.execute()
+
+ def purge_duplicates(self) -> None:
+ duplicate_query = """with grouped_events as (
+ select id,
+ label,
+ camera,
+ has_snapshot,
+ has_clip,
+ row_number() over (
+ partition by label, camera, round(start_time/5,0)*5
+ order by end_time-start_time desc
+ ) as copy_number
+ from event
+ )
+
+ select distinct id, camera, has_snapshot, has_clip from grouped_events
+ where copy_number > 1;"""
+
+ duplicate_events = Event.raw(duplicate_query)
+ for event in duplicate_events:
+ logger.debug(f"Removing duplicate: {event.id}")
+ media_name = f"{event.camera}-{event.id}"
+ media_path = Path(f"{os.path.join(CLIPS_DIR, media_name)}.jpg")
+ media_path.unlink(missing_ok=True)
+ media_path = Path(f"{os.path.join(CLIPS_DIR, media_name)}-clean.png")
+ media_path.unlink(missing_ok=True)
+ media_path = Path(f"{os.path.join(CLIPS_DIR, media_name)}.mp4")
+ media_path.unlink(missing_ok=True)
+
+ (
+ Event.delete()
+ .where(Event.id << [event.id for event in duplicate_events])
+ .execute()
+ )
+
+ def run(self) -> None:
+ # only expire events every 5 minutes
+ while not self.stop_event.wait(300):
+ self.expire("clips")
+ self.expire("snapshots")
+ self.purge_duplicates()
+
+ # drop events from db where has_clip and has_snapshot are false
+ delete_query = Event.delete().where(
+ Event.has_clip == False, Event.has_snapshot == False
+ )
+ delete_query.execute()
+
+ logger.info(f"Exiting event cleanup...")

frigate/events/external.py

@@ -0,0 +1,132 @@
+"""Handle external events created by the user."""
+
+import base64
+import cv2
+import datetime
+import glob
+import logging
+import os
+import random
+import string
+
+from typing import Optional
+
+from multiprocessing.queues import Queue
+
+from frigate.config import CameraConfig, FrigateConfig
+from frigate.const import CLIPS_DIR
+from frigate.events.maintainer import EventTypeEnum
+from frigate.util import draw_box_with_label
+
+logger = logging.getLogger(__name__)
+
+
+class ExternalEventProcessor:
+ def __init__(self, config: FrigateConfig, queue: Queue) -> None:
+ self.config = config
+ self.queue = queue
+ self.default_thumbnail = None
+
+ def create_manual_event(
+ self,
+ camera: str,
+ label: str,
+ sub_label: Optional[str],
+ duration: Optional[int],
+ include_recording: bool,
+ draw: dict[str, any],
+ snapshot_frame: any,
+ ) -> str:
+ now = datetime.datetime.now().timestamp()
+ camera_config = self.config.cameras.get(camera)
+
+ # create event id and start frame time
+ rand_id = "".join(random.choices(string.ascii_lowercase + string.digits, k=6))
+ event_id = f"{now}-{rand_id}"
+
+ thumbnail = self._write_images(
+ camera_config, label, event_id, draw, snapshot_frame
+ )
+
+ self.queue.put(
+ (
+ EventTypeEnum.api,
+ "new",
+ camera_config,
+ {
+ "id": event_id,
+ "label": label,
+ "sub_label": sub_label,
+ "camera": camera,
+ "start_time": now,
+ "end_time": now + duration if duration is not None else None,
+ "thumbnail": thumbnail,
+ "has_clip": camera_config.record.enabled and include_recording,
+ "has_snapshot": True,
+ },
+ )
+ )
+
+ return event_id
+
+ def finish_manual_event(self, event_id: str) -> None:
+ """Finish external event with indeterminate duration."""
+ now = datetime.datetime.now().timestamp()
+ self.queue.put(
+ (EventTypeEnum.api, "end", None, {"id": event_id, "end_time": now})
+ )
+
+ def _write_images(
+ self,
+ camera_config: CameraConfig,
+ label: str,
+ event_id: str,
+ draw: dict[str, any],
+ img_frame: any,
+ ) -> str:
+ # write clean snapshot if enabled
+ if camera_config.snapshots.clean_copy:
+ ret, png = cv2.imencode(".png", img_frame)
+
+ if ret:
+ with open(
+ os.path.join(
+ CLIPS_DIR,
+ f"{camera_config.name}-{event_id}-clean.png",
+ ),
+ "wb",
+ ) as p:
+ p.write(png.tobytes())
+
+ # write jpg snapshot with optional annotations
+ if draw.get("boxes") and isinstance(draw.get("boxes"), list):
+ for box in draw.get("boxes"):
+ x = box["box"][0] * camera_config.detect.width
+ y = box["box"][1] * camera_config.detect.height
+ width = box["box"][2] * camera_config.detect.width
+ height = box["box"][3] * camera_config.detect.height
+
+ draw_box_with_label(
+ img_frame,
+ x,
+ y,
+ x + width,
+ y + height,
+ label,
+ f"{box.get('score', '-')}% {int(width * height)}",
+ thickness=2,
+ color=box.get("color", (255, 0, 0)),
+ )
+
+ ret, jpg = cv2.imencode(".jpg", img_frame)
+ with open(
+ os.path.join(CLIPS_DIR, f"{camera_config.name}-{event_id}.jpg"),
+ "wb",
+ ) as j:
+ j.write(jpg.tobytes())
+
+ # create thumbnail with max height of 175 and save
+ width = int(175 * img_frame.shape[1] / img_frame.shape[0])
+ thumb = cv2.resize(img_frame, dsize=(width, 175), interpolation=cv2.INTER_AREA)
+ ret, jpg = cv2.imencode(".jpg", thumb)
+ return base64.b64encode(jpg.tobytes()).decode("utf-8")