README

fEVR - frigate Event Video Recorder

license telegram Discussions commits since last release Build Status Image Size Twitter URL twitter-follow

fEVR works along side of frigate to collect video and snapshots of objects detected using your existing camera systems.

fEVR v0.6 Screenshots

fEVR v0.6 Screenshots

Own Your Home's Security

fEVR allows you to own your home's camera system. Instead of paying multiple cloud providers varying rates to perform object detection and recording, bring them all into fEVR in your very own open source self-hosted solution! Google, Wyze, Ring, and varying Tuya based cameras all use your data AND want to charge you to store it in the cloud.

Feature comparison to leading cloud event detection providers

Feature comparison to leading cloud event detection providers


Requirements:

  • Frigate fully setup and working
  • MQTT Broker (if you have frigate running, you have this) listening to 0.0.0.0
    • This caused me many headaches, hopefully it saves you some hair pulling.
      It allows mqtt clients on different subnets to access the broker.
      If setup within your local lan this does not alone open up external access, only to other subnets which already have access.
    • Example mosquitto.conf listener section if using port 1883
      listener 1883 0.0.0.0
      

Optional but nice:

  • Tailscale Account (for secure remote access)

Support

Please note, I will generally answer questions within 24 hours, and most times even faster unless I'm on vacation or going on adventures with the family.
Any abuse, harassment, bullying, or just being mean about a free project that I do in my spare time will get you blocked and reported. I have no tolerance for this.

  • Submit an Issue

    • This is the preferred method if you find an error in the code or something that crashes fEVR.
  • Start a discussion

    • For discussing configuration issues or things that bug you (UI tweaks or process improvements)
  • Telegram Support Channel

    • For troubleshooting, a quick question, or you just want to say hi!
  • Sponsors get priority support

    • Any tier of monthly sponsorship will get you priority support and a mention in the README

Installation

Docker Compose:

docker-compose is the preferred installation method

Environment Variables

The following environment variables can be used to configure fEVR:
If not set, configuration can be done via the Web UI.

  • FEVR_TRANSPORT
    • http or https
  • FEVR_URL
    • defaults to 'fevr'
  • FEVR_PORT
    • defaults to 5090
  • FEVR_DEVELOPMENT
    • If set to true, it will use the builtin flask server in development/debug mode
    • If set to false or unset, it will use uwsgi server.
  • TAILSCALE_ENABLE
  • TAILSCALE_TAGS
    • Use tailscale tags
    • To use tags, you must set them up first.
  • TAILSCALE_HOSTNAME

Edit .env file

Copy template.env to .env and adjust as necessary:
NOTE: The IP addresses in the .env file are for internal bridge networking and SHOULD NOT be on the same subnet as your home network.
The default values should serve you well.

### fEVR Setup ######################################################

# Set fevr in development mode using built in flask server (true/false)
FEVR_DEVELOPMENT=false

# Changes the port fEVR runs on DEFAULT: 5090
FEVR_PORT=5090

# Should be set to image name to use local transport, or an accessible url to feed an external instance of fEVR 
FEVR_URL=fevr

# Set to http or https depending on use.  For internal docker network, use http.
FEVR_TRANSPORT=http

### MQTT Client Setup ###############################################

MQTT_BROKER=mqtt
MQTT_BROKER_PORT=1883

# If there is no user/password, leave unset
MQTT_BROKER_USER=
MQTT_BROKER_PASSWORD=

# Comma seperated string of MQTT topics to subscribe to.  LIMIT 5!!!
MQTT_TOPICS="frigate/+"

MQTT_VERBOSE_LOGGING=false

# Obtain this key from http(s)://<fevr_url:port>/profile or leave unset to use web ui setup values
MQTT_APIAUTH_KEY=


### Tailscale #######################################################

# Set to false to disable tailscale
TAILSCALE_ENABLE=true

TAILSCALE_TAGS=tag:fevr
TAILSCALE_HOSTNAME=fevr


# Obtain Auth Key from https://login.tailscale.com/admin/authkeys
TAILSCALE_AUTHKEY=tskey-XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXX
version: '2.4'
services:
  fevr:
    image: ghcr.io/beardedtek-com/fevr:0.6
    container_name: fevr
    restart: unless-stopped
    privileged: true
    ports:
      - 5090:${FEVR_PORT:-5090}
    volumes:
      - /export/fevr:/fevr/app/static/events
      - /export/fevr/data:/fevr/app/data
      - ./fevr/varlib:/var/lib
    depends_on:
      - mqtt
      - frigate
    environment:
      FEVR_DEVELOPMENT: ${FEVR_DEVELOPMENT:-false}
      FEVR_URL: ${FEVR_URL}
      FEVR_PORT: ${FEVR_PORT}
      TAILSCALE_ENABLE: ${TAILSCALE_ENABLE:-true}
      TAILSCALE_AUTHKEY: ${TAILSCALE_AUTHKEY}
      TAILSCALE_HOSTNAME: ${TAILSCALE_HOSTNAME:-fevr}
      TAILSCALE_TAGS: ${TAILSCALE_TAGS}
      MQTT_BROKER: ${MQTT_BROKER:-mqtt}
      MQTT_BROKER_PORT: ${MQTT_BROKER_PORT}
      MQTT_BROKER_USER: ${MQTT_BROKER_USER}
      MQTT_BROKER_PASSWORD: ${MQTT_BROKER_PASSWORD}
      MQTT_TOPICS: ${MQTT_TOPICS:-frigate/+}
      MQTT_VERBOSE_LOGGING: ${MQTT_VERBOSE_LOGGING:-true}
      MQTT_APIAUTH_KEY: ${MQTT_APIAUTH_KEY}

Bring the system up:

docker-compose up -d

Setup

Procedure:

  • Visit http(s)://<fevr_url>/setup
  • Create admin account
  • Login to new admin account
  • Add all of your cameras.
    • It asks for both HLS and RTSP feeds. Technically you don't need to enter anything but the camera name, but in a future release live view and frigate config will be enabled and will require these values
    • Click Next
  • Configure Frigate
    • make one entry called 'frigate' (without the quotes) with your internally accessible frigate URL
    • make another entry called 'external' (without the quotes) with your externally accessible frigate URL
      • This is 100% Optional. It does, however, enable live view outside your network.
      • If you don't have an externally accessible frigate URL, you can skip this step.
    • Click Next
  • Other is not populated yet, There are future plans for this page, just click Next again and you'll be brought to the main interface.
  • Generate API Key for mqtt_client
    • mqtt_client authenticates with fEVR using a 128 character API Key.
    • You can generate an API Key from /profile or click on the beard icon to drop down the menu, and click Profile.
    • Here you can view any API keys you have generated in the past and generate a new one.
    • There are 3 fields to fill out:
      • Name: A unique name to identify this key (no duplicates allowed)
      • IPv4 Address: Not used as of now but required to be a valid IP or network (without cidr notation)
        • Enter 0.0.0.0 to future proof.
      • Login Count: this can be used to limit the amount of times this API Key can be used. While not used at the moment, it will function as the base of a limited login solution (say one time passwords for law enforcement and the like)
        • Enter 0 for unlimited usage
  • Configure mqtt_client
    • Once you have your API Key you can generate your config file for the mqtt_client.
    • This should be automated further in 0.6.1

Home Assistant Notifications

As of right now it's a bit complicated. For each notification type you want for each camera, a helper entity must be added.
For example, I have notifications setup for my driveway camera for person, animal, and vehicle, so I have the following helpers:

  • fevrDrivewayAnimal
  • fevrDrivewayCar
  • fevrDrivewayPerson

The automation uses this helper entity for 2 purposes.

  • As a motion sensor
    • If the helper is on, that means a notification is active
  • As a pause for notifications
    • If the helper is on, it does not allow further notifications until it is turned off.
    • In the automation, this time can be adjusted to your liking

Here is the automation I'm currently using:
As displayed when:

  • editing the automation via the UI
  • click on overflow menu (3 dots)
  • click Edit in YAML

NOTES:

  • CAMERA is the camera name
  • HELPER ENTITY is the entity you created for this notification
  • YOUR FEVR URL is the url to your fevr instance
alias: fEVR <<CAMERA>> Person Alert
description: fEVR Object Detection Alerts
trigger:
  - platform: mqtt
    topic: frigate/events
condition:
  - condition: template
    value_template: '{{ trigger.payload_json["type"] == "end" }}'
  - condition: template
    value_template: |-
      {{
      trigger.payload_json["after"]["label"] == "person"
      }}
  - condition: template
    value_template: |-
      {{
      trigger.payload_json["after"]["top_score"] > 0.76
      }}
  - condition: template
    value_template: |-
      {{
      trigger.payload_json["after"]["camera"] == "<<CAMERA>>"
      }}
action:
  - choose:
      - conditions:
          - condition: state
            state: 'off'
            entity_id: input_boolean.fevrbackyardperson
        sequence:
          - service: notify.mobile_app_sg20plus
            data:
              message: '{{ trigger.payload_json["after"]["label"] | title }} Detected'
              data:
                notification_icon: mdi:cctv
                ttl: 0
                priority: high
                sticky: true
                actions:
                  - action: URI
                    title: Clip
                    uri: >-
                      <<YOUR FEVR URL>>/event/{{trigger.payload_json['after']['id']}}/snap
                  - action: URI
                    title: Snapshot
                    uri: >-
                      <<YOUR FEVR URL>>/event/{{trigger.payload_json['after']['id']}}/snap
                image: >-
                  <<YOUR FEVR URL>>/static/events/{{trigger.payload_json['after']['id']}}/snapshot.jpg
                tag: '{{trigger.payload_json["after"]["id"]}}'
                alert_once: true
          - service: input_boolean.turn_on
            data: {}
            target:
              entity_id: input_boolean.<<HELPER ENTITY>>
          - delay:
              hours: 0
              minutes: 1
              seconds: 0
              milliseconds: 0
          - service: input_boolean.turn_off
            data: {}
            target:
              entity_id: input_boolean.<<HELPER ENTITY>>
    default: []
mode: single