# Unofficial UniFi Protect Python API and CLI
<p align="center">
<a href="https://github.com/uilibs/uiprotect/actions/workflows/ci.yml?query=branch%3Amain">
<img src="https://img.shields.io/github/actions/workflow/status/uilibs/uiprotect/ci.yml?branch=main&label=CI&logo=github&style=flat-square" alt="CI Status" >
</a>
<a href="https://uiprotect.readthedocs.io">
<img src="https://img.shields.io/readthedocs/uiprotect.svg?logo=read-the-docs&logoColor=fff&style=flat-square" alt="Documentation Status">
</a>
<a href="https://codecov.io/gh/uilibs/uiprotect">
<img src="https://img.shields.io/codecov/c/github/uilibs/uiprotect.svg?logo=codecov&logoColor=fff&style=flat-square" alt="Test coverage percentage">
</a>
</p>
<p align="center">
<a href="https://python-poetry.org/">
<img src="https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json" alt="Poetry">
</a>
<a href="https://github.com/astral-sh/ruff">
<img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff">
</a>
<a href="https://github.com/pre-commit/pre-commit">
<img src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=flat-square" alt="pre-commit">
</a>
</p>
<p align="center">
<a href="https://pypi.org/project/uiprotect/">
<img src="https://img.shields.io/pypi/v/uiprotect.svg?logo=python&logoColor=fff&style=flat-square" alt="PyPI Version">
</a>
<img src="https://img.shields.io/pypi/pyversions/uiprotect.svg?style=flat-square&logo=python&logoColor=fff" alt="Supported Python versions">
<img src="https://img.shields.io/pypi/l/uiprotect.svg?style=flat-square" alt="License">
</p>
---
**Documentation**: <a href="https://uiprotect.readthedocs.io" target="_blank">https://uiprotect.readthedocs.io </a>
**Source Code**: <a href="https://github.com/uilibs/uiprotect" target="_blank">https://github.com/uilibs/uiprotect </a>
---
Python API for UniFi Protect (Unofficial)
## Looking for maintainers
This project is looking for maintainers.
## Installation
Install this via pip (or your favorite package manager):
`pip install uiprotect`
## History
This project was split off from `pyunifiprotect` because that project changed its license to one that would not be accepted in Home Assistant. This project is committed to keeping the MIT license.
## Credits
- Bjarne Riis ([@briis](https://github.com/briis/)) for the original pyunifiprotect package
- Christopher Bailey ([@AngellusMortis](https://github.com/AngellusMortis/)) for the maintaining the pyunifiprotect package
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
<!-- prettier-ignore-start -->
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- markdownlint-disable -->
<!-- markdownlint-enable -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
<!-- prettier-ignore-end -->
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
`uiprotect` is an unofficial API for UniFi Protect. There is no affiliation with Ubiquiti.
This module communicates with UniFi Protect surveillance software installed on a UniFi OS Console such as a Ubiquiti CloudKey+ or UniFi Dream Machine Pro.
The API is not documented by Ubiquiti, so there might be misses and/or frequent changes in this module, as Ubiquiti evolves the software.
The module is primarily written for the purpose of being used in Home Assistant core [integration for UniFi Protect](https://www.home-assistant.io/integrations/unifiprotect) but might be used for other purposes also.
## Smart Detections now Require Remote Access to enable
Smart Detections (person, vehicle, animal, face), a feature that previously could be used with local only console, [now requires you to enable remote access to enable](https://community.ui.com/questions/Cannot-enable-Smart-Detections/e3d50641-5c00-4607-9723-453cda557e35#answer/1d146426-89aa-4022-a0ae-fd5000846028).
Enabling Remote Access may grant other users access to your console [due to the fact Ubiquiti can reconfigure access controls at any time](https://community.ui.com/questions/Bug-Fix-Cloud-Access-Misconfiguration/fe8d4479-e187-4471-bf95-b2799183ceb7).
If you are not okay with the feature being locked behind Remote Access, [let Ubiquiti know](https://community.ui.com/questions/Cannot-enable-Smart-Detections/e3d50641-5c00-4607-9723-453cda557e35).
## Documentation
[Full documentation for the project](https://uiprotect.readthedocs.io/).
## Requirements
If you want to install `uiprotect` natively, the below are the requirements:
- [UniFi Protect](https://ui.com/camera-security) version 1.20+
- Latest version of library is generally only tested against the two latest minor version. This is either two latest stable versions (such as 1.21.x and 2.0.x) or the latest EA version and stable version (such as 2.2.x EA and 2.1.x).
- [Python](https://www.python.org/) 3.10+
- POSIX compatible system
- Library is only tested on Linux, specifically the latest Debian version available for the official Python Docker images, but there is no reason the library should not work on any Linux distro or macOS.
- [ffmpeg](https://ffmpeg.org/)
- ffmpeg is primarily only for streaming audio to Protect cameras, this can be considered a soft requirement
Alternatively you can use the [provided Docker container](#using-docker-container), in which case the only requirement is [Docker](https://docs.docker.com/desktop/) or another OCI compatible orchestrator (such as Kubernetes or podman).
Windows is **not supported**. If you need to use `uiprotect` on Windows, use Docker Desktop and the provided docker container or [WSL](https://docs.microsoft.com/en-us/windows/wsl/install).
## Install
### From PyPi
`uiprotect` is available on PyPi:
```bash
pip install uiprotect
```
### From GitHub
```bash
pip install git+https://github.com/uilibs/uiprotect.git#egg=uiprotect
```
### Using Docker Container
A Docker container is also provided, so you do not need to install/manage Python as well. You can add the following to your `.bashrc` or similar.
```bash
function uiprotect() {
docker run --rm -it \
-e UFP_USERNAME=YOUR_USERNAME_HERE \
-e UFP_PASSWORD=YOUR_PASSWORD_HERE \
-e UFP_ADDRESS=YOUR_IP_ADDRESS \
-e UFP_PORT=443 \
-e UFP_SSL_VERIFY=True \
-e TZ=America/New_York \
-v $PWD:/data ghcr.io/uilibs/uiprotect:latest "$@"
}
```
Some notes about the Docker version since it is running inside a container:
- You can update at any time using the command `docker pull ghcr.io/uilibs/uiprotect:latest`
- Your local current working directory (`$PWD`) will automatically be mounted to `/data` inside of the container. For commands that output files, this is the _only_ path you can write to and have the file persist.
- The container supports `linux/amd64` and `linux/arm64` natively. This means it will also work well on macOS or Windows using Docker Desktop.
- `TZ` should be the [Olson timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for the timezone your UniFi Protect instance is in.
- For more details on `TZ` and other environment variables, check the [command line docs](https://uilibs.github.io/uiprotect/latest/cli/)
## Quickstart
### CLI
> [!WARNING]
> Ubiquiti SSO accounts are not supported and actively discouraged from being used. There is no option to use MFA. You are expected to use local access user. `uiprotect` is not designed to allow you to use your owner account to access the console or to be used over the public internet as both pose a security risk.
```bash
export UFP_USERNAME=YOUR_USERNAME_HERE
export UFP_PASSWORD=YOUR_PASSWORD_HERE
export UFP_ADDRESS=YOUR_IP_ADDRESS
export UFP_PORT=443
# change to false if you do not have a valid HTTPS certificate for your instance
export UFP_SSL_VERIFY=True
uiprotect --help
uiprotect nvr
```
### Python
UniFi Protect itself is 100% async, so as such this library is primarily designed to be used in an async context.
The main interface for the library is the `uiprotect.ProtectApiClient`:
```python
from uiprotect import ProtectApiClient
protect = ProtectApiClient(host, port, username, password, verify_ssl=True)
await protect.update() # this will initialize the protect .bootstrap and open a Websocket connection for updates
# get names of your cameras
for camera in protect.bootstrap.cameras.values():
print(camera.name)
# subscribe to Websocket for updates to UFP
def callback(msg: WSSubscriptionMessage):
# do stuff
unsub = protect.subscribe_websocket(callback)
# remove subscription
unsub()
```
## TODO / Planned / Not Implemented
Generally any feature missing from the library is planned to be done eventually / nice to have with the following exceptions
### UniFi OS Features
Anything that is strictly a UniFi OS feature. If it is ever done, it will be in a separate library that interacts with this one. Examples include:
- Managing RAID and disks
- Creating and managing users
### Remote Access / Ubiquiti Cloud Features
Some features that require an Ubiquiti Account or "Remote Access" to be enabled are currently not implemented. Examples include:
- Stream sharing
- Face detection
Raw data
{
"_id": null,
"home_page": "https://github.com/uilibs/uiprotect",
"name": "uiprotect",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "UI Protect Maintainers",
"author_email": "ui@koston.org",
"download_url": "https://files.pythonhosted.org/packages/5e/41/78a0515be2eabaa793643995eaf8e032f8e9276d0990c15334b687f8e468/uiprotect-7.0.2.tar.gz",
"platform": null,
"description": "# Unofficial UniFi Protect Python API and CLI\n\n<p align=\"center\">\n <a href=\"https://github.com/uilibs/uiprotect/actions/workflows/ci.yml?query=branch%3Amain\">\n <img src=\"https://img.shields.io/github/actions/workflow/status/uilibs/uiprotect/ci.yml?branch=main&label=CI&logo=github&style=flat-square\" alt=\"CI Status\" >\n </a>\n <a href=\"https://uiprotect.readthedocs.io\">\n <img src=\"https://img.shields.io/readthedocs/uiprotect.svg?logo=read-the-docs&logoColor=fff&style=flat-square\" alt=\"Documentation Status\">\n </a>\n <a href=\"https://codecov.io/gh/uilibs/uiprotect\">\n <img src=\"https://img.shields.io/codecov/c/github/uilibs/uiprotect.svg?logo=codecov&logoColor=fff&style=flat-square\" alt=\"Test coverage percentage\">\n </a>\n</p>\n<p align=\"center\">\n <a href=\"https://python-poetry.org/\">\n <img src=\"https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json\" alt=\"Poetry\">\n </a>\n <a href=\"https://github.com/astral-sh/ruff\">\n <img src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\" alt=\"Ruff\">\n </a>\n <a href=\"https://github.com/pre-commit/pre-commit\">\n <img src=\"https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=flat-square\" alt=\"pre-commit\">\n </a>\n</p>\n<p align=\"center\">\n <a href=\"https://pypi.org/project/uiprotect/\">\n <img src=\"https://img.shields.io/pypi/v/uiprotect.svg?logo=python&logoColor=fff&style=flat-square\" alt=\"PyPI Version\">\n </a>\n <img src=\"https://img.shields.io/pypi/pyversions/uiprotect.svg?style=flat-square&logo=python&logoColor=fff\" alt=\"Supported Python versions\">\n <img src=\"https://img.shields.io/pypi/l/uiprotect.svg?style=flat-square\" alt=\"License\">\n</p>\n\n---\n\n**Documentation**: <a href=\"https://uiprotect.readthedocs.io\" target=\"_blank\">https://uiprotect.readthedocs.io </a>\n\n**Source Code**: <a href=\"https://github.com/uilibs/uiprotect\" target=\"_blank\">https://github.com/uilibs/uiprotect </a>\n\n---\n\nPython API for UniFi Protect (Unofficial)\n\n## Looking for maintainers\n\nThis project is looking for maintainers.\n\n## Installation\n\nInstall this via pip (or your favorite package manager):\n\n`pip install uiprotect`\n\n## History\n\nThis project was split off from `pyunifiprotect` because that project changed its license to one that would not be accepted in Home Assistant. This project is committed to keeping the MIT license.\n\n## Credits\n\n- Bjarne Riis ([@briis](https://github.com/briis/)) for the original pyunifiprotect package\n- Christopher Bailey ([@AngellusMortis](https://github.com/AngellusMortis/)) for the maintaining the pyunifiprotect package\n\n## Contributors \u2728\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n<!-- prettier-ignore-start -->\n<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->\n<!-- markdownlint-disable -->\n<!-- markdownlint-enable -->\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n<!-- prettier-ignore-end -->\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n`uiprotect` is an unofficial API for UniFi Protect. There is no affiliation with Ubiquiti.\n\nThis module communicates with UniFi Protect surveillance software installed on a UniFi OS Console such as a Ubiquiti CloudKey+ or UniFi Dream Machine Pro.\n\nThe API is not documented by Ubiquiti, so there might be misses and/or frequent changes in this module, as Ubiquiti evolves the software.\n\nThe module is primarily written for the purpose of being used in Home Assistant core [integration for UniFi Protect](https://www.home-assistant.io/integrations/unifiprotect) but might be used for other purposes also.\n\n## Smart Detections now Require Remote Access to enable\n\nSmart Detections (person, vehicle, animal, face), a feature that previously could be used with local only console, [now requires you to enable remote access to enable](https://community.ui.com/questions/Cannot-enable-Smart-Detections/e3d50641-5c00-4607-9723-453cda557e35#answer/1d146426-89aa-4022-a0ae-fd5000846028).\n\nEnabling Remote Access may grant other users access to your console [due to the fact Ubiquiti can reconfigure access controls at any time](https://community.ui.com/questions/Bug-Fix-Cloud-Access-Misconfiguration/fe8d4479-e187-4471-bf95-b2799183ceb7).\n\nIf you are not okay with the feature being locked behind Remote Access, [let Ubiquiti know](https://community.ui.com/questions/Cannot-enable-Smart-Detections/e3d50641-5c00-4607-9723-453cda557e35).\n\n## Documentation\n\n[Full documentation for the project](https://uiprotect.readthedocs.io/).\n\n## Requirements\n\nIf you want to install `uiprotect` natively, the below are the requirements:\n\n- [UniFi Protect](https://ui.com/camera-security) version 1.20+\n - Latest version of library is generally only tested against the two latest minor version. This is either two latest stable versions (such as 1.21.x and 2.0.x) or the latest EA version and stable version (such as 2.2.x EA and 2.1.x).\n- [Python](https://www.python.org/) 3.10+\n- POSIX compatible system\n - Library is only tested on Linux, specifically the latest Debian version available for the official Python Docker images, but there is no reason the library should not work on any Linux distro or macOS.\n- [ffmpeg](https://ffmpeg.org/)\n - ffmpeg is primarily only for streaming audio to Protect cameras, this can be considered a soft requirement\n\nAlternatively you can use the [provided Docker container](#using-docker-container), in which case the only requirement is [Docker](https://docs.docker.com/desktop/) or another OCI compatible orchestrator (such as Kubernetes or podman).\n\nWindows is **not supported**. If you need to use `uiprotect` on Windows, use Docker Desktop and the provided docker container or [WSL](https://docs.microsoft.com/en-us/windows/wsl/install).\n\n## Install\n\n### From PyPi\n\n`uiprotect` is available on PyPi:\n\n```bash\npip install uiprotect\n```\n\n### From GitHub\n\n```bash\npip install git+https://github.com/uilibs/uiprotect.git#egg=uiprotect\n```\n\n### Using Docker Container\n\nA Docker container is also provided, so you do not need to install/manage Python as well. You can add the following to your `.bashrc` or similar.\n\n```bash\nfunction uiprotect() {\n docker run --rm -it \\\n -e UFP_USERNAME=YOUR_USERNAME_HERE \\\n -e UFP_PASSWORD=YOUR_PASSWORD_HERE \\\n -e UFP_ADDRESS=YOUR_IP_ADDRESS \\\n -e UFP_PORT=443 \\\n -e UFP_SSL_VERIFY=True \\\n -e TZ=America/New_York \\\n -v $PWD:/data ghcr.io/uilibs/uiprotect:latest \"$@\"\n}\n```\n\nSome notes about the Docker version since it is running inside a container:\n\n- You can update at any time using the command `docker pull ghcr.io/uilibs/uiprotect:latest`\n- Your local current working directory (`$PWD`) will automatically be mounted to `/data` inside of the container. For commands that output files, this is the _only_ path you can write to and have the file persist.\n- The container supports `linux/amd64` and `linux/arm64` natively. This means it will also work well on macOS or Windows using Docker Desktop.\n- `TZ` should be the [Olson timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for the timezone your UniFi Protect instance is in.\n- For more details on `TZ` and other environment variables, check the [command line docs](https://uilibs.github.io/uiprotect/latest/cli/)\n\n## Quickstart\n\n### CLI\n\n> [!WARNING]\n> Ubiquiti SSO accounts are not supported and actively discouraged from being used. There is no option to use MFA. You are expected to use local access user. `uiprotect` is not designed to allow you to use your owner account to access the console or to be used over the public internet as both pose a security risk.\n\n```bash\nexport UFP_USERNAME=YOUR_USERNAME_HERE\nexport UFP_PASSWORD=YOUR_PASSWORD_HERE\nexport UFP_ADDRESS=YOUR_IP_ADDRESS\nexport UFP_PORT=443\n# change to false if you do not have a valid HTTPS certificate for your instance\nexport UFP_SSL_VERIFY=True\n\nuiprotect --help\nuiprotect nvr\n```\n\n### Python\n\nUniFi Protect itself is 100% async, so as such this library is primarily designed to be used in an async context.\n\nThe main interface for the library is the `uiprotect.ProtectApiClient`:\n\n```python\nfrom uiprotect import ProtectApiClient\n\nprotect = ProtectApiClient(host, port, username, password, verify_ssl=True)\n\nawait protect.update() # this will initialize the protect .bootstrap and open a Websocket connection for updates\n\n# get names of your cameras\nfor camera in protect.bootstrap.cameras.values():\n print(camera.name)\n\n# subscribe to Websocket for updates to UFP\ndef callback(msg: WSSubscriptionMessage):\n # do stuff\n\nunsub = protect.subscribe_websocket(callback)\n\n# remove subscription\nunsub()\n\n```\n\n## TODO / Planned / Not Implemented\n\nGenerally any feature missing from the library is planned to be done eventually / nice to have with the following exceptions\n\n### UniFi OS Features\n\nAnything that is strictly a UniFi OS feature. If it is ever done, it will be in a separate library that interacts with this one. Examples include:\n\n- Managing RAID and disks\n- Creating and managing users\n\n### Remote Access / Ubiquiti Cloud Features\n\nSome features that require an Ubiquiti Account or \"Remote Access\" to be enabled are currently not implemented. Examples include:\n\n- Stream sharing\n- Face detection\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Python API for Unifi Protect (Unofficial)",
"version": "7.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/uilibs/uiprotect/issues",
"Changelog": "https://github.com/uilibs/uiprotect/blob/main/CHANGELOG.md",
"Documentation": "https://uiprotect.readthedocs.io",
"Homepage": "https://github.com/uilibs/uiprotect",
"Repository": "https://github.com/uilibs/uiprotect"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fdb745ef99e4bfbb4bd73084f446518c996c55a602b0ff650ebce70ce6f1ef95",
"md5": "764241ed1c2e89164831d5ba92482017",
"sha256": "615bd4792c94405a36709ffd4e4ddbe7bcb0e8146bbd555fa26eaf1d7319199d"
},
"downloads": -1,
"filename": "uiprotect-7.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "764241ed1c2e89164831d5ba92482017",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 122983,
"upload_time": "2024-12-11T22:37:50",
"upload_time_iso_8601": "2024-12-11T22:37:50.733247Z",
"url": "https://files.pythonhosted.org/packages/fd/b7/45ef99e4bfbb4bd73084f446518c996c55a602b0ff650ebce70ce6f1ef95/uiprotect-7.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5e4178a0515be2eabaa793643995eaf8e032f8e9276d0990c15334b687f8e468",
"md5": "bd2e3b163682712975f1dfcfc7d7f112",
"sha256": "a1a6e0a3a30912a530593ff097247215ff03a225c0397cdd74ce46d58abf3775"
},
"downloads": -1,
"filename": "uiprotect-7.0.2.tar.gz",
"has_sig": false,
"md5_digest": "bd2e3b163682712975f1dfcfc7d7f112",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 110778,
"upload_time": "2024-12-11T22:37:53",
"upload_time_iso_8601": "2024-12-11T22:37:53.797951Z",
"url": "https://files.pythonhosted.org/packages/5e/41/78a0515be2eabaa793643995eaf8e032f8e9276d0990c15334b687f8e468/uiprotect-7.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-11 22:37:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "uilibs",
"github_project": "uiprotect",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "uiprotect"
}
JSON
