beardedtek/fevr repository overview

# fEVR - frigate Event Video Recorder

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

# 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. <p align="center"> <img alt="Feature comparison to leading cloud event detection providers" src="docs/images/features.webp">

# 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

⁠# Documentation ## Main API Calls⁠ ## mqtt_client⁠

# 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   - Enable or disable tailscale functionality   - Sign up for tailscale⁠ prior to use. - TAILSCALE_TAGS   - Use tailscale tags   - To use tags, you must set them up⁠ first. - TAILSCALE_HOSTNAME   - Set hostname for tailscale -TAILSCALE_AUTHKEY   - You must generate an auth key⁠ first.

### 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.     - See mqtt_client docs here⁠ for an example   - 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