| Name | frigate-event-handler JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | None |
| upload_time | 2024-11-20 12:13:11 |
| maintainer | None |
| docs_url | None |
| author | Bendik R. Brenne |
| requires_python | <4.0,>=3.12 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Frigate Event Handler
[![GitHub Release][releases-shield]][releases]
[![Python Versions][py-versions-shield]][py-versions]
![Project Maintenance][maintenance-shield]
[![License][license-shield]](LICENSE)
![Made with Love in Norway][madewithlove-shield]
A tool that listens to Frigate events and generates AI-powered descriptions of detected events using vision and language models.
## Features
- Connects to Frigate via MQTT to receive real-time events
- Processes event video clips using AI vision models
- Generates natural language descriptions of events
- Supports multiple cameras with camera-specific configurations
- Configurable frame processing (resizing, similarity detection, grid layout)
- Customizable prompts for different camera contexts
## Installation
```bash
pip install frigate-event-handler
```
## Usage
```bash
frigate-event-handler -c config.yml
```
### Command Line Options
```
usage: frigate-event-handler [-h] [-V] [-v] [--debug] [-c CONFIG]
Frigate event handler.
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
-v, --verbose Logging verbosity level
--debug Enable debug mode
--debug-dir DEBUG_DIR
Directory to output debug files to.
-c CONFIG, --config CONFIG
Configuration file
```
## Configuration
The tool uses a YAML configuration file to specify connection details and behavior. Here's a minimal configuration example:
```yaml
mqtt:
host: localhost
port: 1883
topic: frigate/events
frigate:
base_url: http://localhost:5000/api
vision_agent:
api_key: your-llm-api-key
vision_prompt: |
Describe what you see in these surveillance camera frames.
refine_prompt: |
Rewrite this surveillance event description for a notification.
```
See [reference config](config.dist.yaml) for a complete configuration file with all available options and their descriptions.
### Camera-Specific Configuration
You can override global vision agent settings for specific cameras:
```yaml
vision_agent:
# Global settings here
cameras:
front_door:
prompt_context: |
This camera faces the front door entrance.
backyard:
prompt_context: |
This camera overlooks the backyard area.
```
## How It Works
1. The tool subscribes to Frigate's MQTT events
2. When an event is received, it:
- Downloads the event video clip from Frigate
- Extracts frames from the video
- Processes frames (resize, similarity detection, etc.)
- Sends frames to the vision model for analysis
- Refines the description using a language model
3. The resulting description is then posted back to frigate
## Frame Processing Options
### Frame Similarity Detection
The tool can remove similar frames before sending them to the vision model:
```yaml
vision_agent:
remove_similar_frames: true
hashing_max_frames: 200
hash_size: 12 # Lower = more aggressive similarity matching
```
### Grid Layout
Frames can be arranged in a grid:
```yaml
vision_agent:
stack_grid: true
stack_grid_size: [3, 3] # 3x3 grid
```
### Frame Resizing
Control frame dimensions sent to the vision model:
```yaml
vision_agent:
resize_video: [640, 360] # [width, height]
```
## Debug Mode
Enable debug mode to save processed frames and API responses:
```bash
frigate-event-handler --debug -c config.yml
```
Debug files will be saved to `./debug` by default, or to a custom directory specified with the `--debug-dir` option.
Debug mode and debug directory can also be set in the configuration file.
## Requirements
- Python 3.12+
- MQTT broker
- Frigate instance
- Access to an LLM API (OpenAI compatible)
[license-shield]: https://img.shields.io/github/license/bendikrb/frigate-event-handler.svg
[license]: https://github.com/bendikrb/frigate-event-handler/blob/main/LICENSE
[releases-shield]: https://img.shields.io/pypi/v/frigate-event-handler
[releases]: https://github.com/bendikrb/frigate-event-handler/releases
[maintenance-shield]: https://img.shields.io/maintenance/yes/2024.svg
[py-versions-shield]: https://img.shields.io/pypi/pyversions/frigate-event-handler
[py-versions]: https://pypi.org/project/frigate-event-handler/
[madewithlove-shield]: https://madewithlove.now.sh/no?heart=true&colorB=%233584e4
Raw data
{
"_id": null,
"home_page": null,
"name": "frigate-event-handler",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Bendik R. Brenne",
"author_email": "bendik@konstant.no",
"download_url": "https://files.pythonhosted.org/packages/0e/33/a8fa83bbce4ca5b0e479520de147b3910affa9838c7faf5b7c246170698a/frigate_event_handler-0.3.1.tar.gz",
"platform": null,
"description": "# Frigate Event Handler\n\n[![GitHub Release][releases-shield]][releases]\n[![Python Versions][py-versions-shield]][py-versions]\n![Project Maintenance][maintenance-shield]\n[![License][license-shield]](LICENSE)\n![Made with Love in Norway][madewithlove-shield]\n\n\nA tool that listens to Frigate events and generates AI-powered descriptions of detected events using vision and language models.\n\n\n## Features\n\n- Connects to Frigate via MQTT to receive real-time events\n- Processes event video clips using AI vision models\n- Generates natural language descriptions of events\n- Supports multiple cameras with camera-specific configurations\n- Configurable frame processing (resizing, similarity detection, grid layout)\n- Customizable prompts for different camera contexts\n\n## Installation\n\n```bash\npip install frigate-event-handler\n```\n\n## Usage\n\n```bash\nfrigate-event-handler -c config.yml\n```\n\n### Command Line Options\n\n```\nusage: frigate-event-handler [-h] [-V] [-v] [--debug] [-c CONFIG]\n\nFrigate event handler.\n\noptions:\n -h, --help show this help message and exit\n -V, --version show program's version number and exit\n -v, --verbose Logging verbosity level\n --debug Enable debug mode\n --debug-dir DEBUG_DIR\n Directory to output debug files to.\n -c CONFIG, --config CONFIG\n Configuration file\n```\n\n## Configuration\n\nThe tool uses a YAML configuration file to specify connection details and behavior. Here's a minimal configuration example:\n\n```yaml\nmqtt:\n host: localhost\n port: 1883\n topic: frigate/events\n\nfrigate:\n base_url: http://localhost:5000/api\n\nvision_agent:\n api_key: your-llm-api-key\n vision_prompt: |\n Describe what you see in these surveillance camera frames.\n refine_prompt: |\n Rewrite this surveillance event description for a notification.\n```\n\nSee [reference config](config.dist.yaml) for a complete configuration file with all available options and their descriptions.\n\n### Camera-Specific Configuration\n\nYou can override global vision agent settings for specific cameras:\n\n```yaml\nvision_agent:\n # Global settings here\n cameras:\n front_door:\n prompt_context: |\n This camera faces the front door entrance.\n backyard:\n prompt_context: |\n This camera overlooks the backyard area.\n```\n\n## How It Works\n\n1. The tool subscribes to Frigate's MQTT events\n2. When an event is received, it:\n - Downloads the event video clip from Frigate\n - Extracts frames from the video\n - Processes frames (resize, similarity detection, etc.)\n - Sends frames to the vision model for analysis\n - Refines the description using a language model\n3. The resulting description is then posted back to frigate\n\n## Frame Processing Options\n\n### Frame Similarity Detection\n\nThe tool can remove similar frames before sending them to the vision model:\n\n```yaml\nvision_agent:\n remove_similar_frames: true\n hashing_max_frames: 200\n hash_size: 12 # Lower = more aggressive similarity matching\n```\n\n### Grid Layout\n\nFrames can be arranged in a grid:\n\n```yaml\nvision_agent:\n stack_grid: true\n stack_grid_size: [3, 3] # 3x3 grid\n```\n\n### Frame Resizing\n\nControl frame dimensions sent to the vision model:\n\n```yaml\nvision_agent:\n resize_video: [640, 360] # [width, height]\n```\n\n## Debug Mode\n\nEnable debug mode to save processed frames and API responses:\n\n```bash\nfrigate-event-handler --debug -c config.yml\n```\n\nDebug files will be saved to `./debug` by default, or to a custom directory specified with the `--debug-dir` option.\n\nDebug mode and debug directory can also be set in the configuration file.\n\n## Requirements\n\n- Python 3.12+\n- MQTT broker\n- Frigate instance\n- Access to an LLM API (OpenAI compatible)\n\n[license-shield]: https://img.shields.io/github/license/bendikrb/frigate-event-handler.svg\n[license]: https://github.com/bendikrb/frigate-event-handler/blob/main/LICENSE\n[releases-shield]: https://img.shields.io/pypi/v/frigate-event-handler\n[releases]: https://github.com/bendikrb/frigate-event-handler/releases\n[maintenance-shield]: https://img.shields.io/maintenance/yes/2024.svg\n[py-versions-shield]: https://img.shields.io/pypi/pyversions/frigate-event-handler\n[py-versions]: https://pypi.org/project/frigate-event-handler/\n[madewithlove-shield]: https://madewithlove.now.sh/no?heart=true&colorB=%233584e4\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": null,
"version": "0.3.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5913516ab6971c705c0694e06d496b9ea503c42cea751b69da24b74dfb8c1474",
"md5": "8856c0d27679e119758f3eba42e9dfa6",
"sha256": "dfa7fd64e2941b5255bb96a8d36df93842ea11d3d3c949aa6398b4302e32fbac"
},
"downloads": -1,
"filename": "frigate_event_handler-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8856c0d27679e119758f3eba42e9dfa6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 11966,
"upload_time": "2024-11-20T12:13:10",
"upload_time_iso_8601": "2024-11-20T12:13:10.317489Z",
"url": "https://files.pythonhosted.org/packages/59/13/516ab6971c705c0694e06d496b9ea503c42cea751b69da24b74dfb8c1474/frigate_event_handler-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0e33a8fa83bbce4ca5b0e479520de147b3910affa9838c7faf5b7c246170698a",
"md5": "43902b6c9ea1ddab2453b55ab4e4bb06",
"sha256": "3e2758b0b5d0cc4697cfd1d0d726d2f6038785e1e41a4c35f3d4cfbd0ab7f5c5"
},
"downloads": -1,
"filename": "frigate_event_handler-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "43902b6c9ea1ddab2453b55ab4e4bb06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 11071,
"upload_time": "2024-11-20T12:13:11",
"upload_time_iso_8601": "2024-11-20T12:13:11.208282Z",
"url": "https://files.pythonhosted.org/packages/0e/33/a8fa83bbce4ca5b0e479520de147b3910affa9838c7faf5b7c246170698a/frigate_event_handler-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-20 12:13:11",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "frigate-event-handler"
}
