Add video event proxy endpoint for unifiprotect

[lutzvahl]

Proposed change

As of now, unifi protect comes with 2x API endpoints to be used within HA to get
A) a thumbnail for an event: /api/unifiprotect/thumbnail/{nvr_id}/{event_id}:
B) a part of a video from a camera: /api/unifiprotect/video/{nvr_id}/{camera_id}/{start}/{end}:

This CL adds a new proxy endpoint to receive the full video for an event: /api/unifiprotect/video/{nvr_id}/{event_id}. This is needed as the last_changed timestamp of the sensor in HA is not the same as the unifi protect event start date, hence it's impossible in HA to calc the correct start & end timestamps to see the full event video e.g. as part of a notification.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New integration (thank you!)
• New feature (which adds functionality to an existing integration)
• Deprecation (breaking change to happen in the future)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes Unifi protect events start and end time not in sync with HA sensor last_changed #129979
• This PR is related to issue:
• Link to documentation pull request: Doc update for new endpoint in unifi protect home-assistant.io#35629

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the [development checklist][dev-checklist]
• I have followed the [perfect PR recommendations][perfect-pr]
• The code has been formatted using Ruff (ruff format homeassistant tests)
• [ X Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for Doc update for new endpoint in unifi protect home-assistant.io#35629
  In case the new API proxy endpoint will be accepted, I'll update the docs prior to landing this CL.

If the code communicates with devices, web services, or third-party tools:

• The [manifest file][manifest-docs] has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• New or updated dependencies have been added to requirements_all.txt.
  Updated by running python3 -m script.gen_requirements_all.
• For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

[home-assistant]

Hi @lutzvahl

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[lutzvahl]

Codecov is failing with error: Report creating failed: {"message":"Token required because branch is protected"}
Please advise..

Stale

[lutzvahl]

added link to the doc PR home-assistant/home-assistant.io#35629

[lutzvahl]

Can someone please review?

[RaHehl]

As mentioned in the other comment, I'm not sure if I'm doing this correctly—I keep getting a 404 error.

It seems that not all changes are being captured by the tests yet.

[RaHehl]

@lutzvahl
I think overall this looks pretty good so far. However, I'm having a bit of trouble testing it manually on my end since I haven't used notifications before. How are you testing this? Do you maybe have an example?

I’ve already seen videos briefly appear in the notifications, but unfortunately, I’ve also encountered some 400 errors. Do I need to configure something, like a delay until the event is over?

[lutzvahl]

@lutzvahl I think overall this looks pretty good so far. However, I'm having a bit of trouble testing it manually on my end since I haven't used notifications before. How are you testing this? Do you maybe have an example?

Sure, this is a notification action I'm using. I've connected my local DEV_ENV to the unifi console for testing.

alias: "Security: Kamera xx Motion an yyy"
description: ""
triggers:
  - entity_id:
      - binary_sensor.g5_bullet_motion_2
    to: "on"
    trigger: state
actions:
  - data:
      message: "Bewegung an der xxx "
      data:
        tag: Motion
        channel: Motion
        ttl: 0
        priority: high
        time-sensitive: 1
        image: >-
          /api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id)
          }}/{{ state_attr(trigger.entity_id, 'event_id') }}
        video: >-
          /api/unifiprotect/video/{{ config_entry_id(trigger.entity_id)
          }}/{{ state_attr(trigger.entity_id, 'event_id') }}        
    action: notify.mobile_app_xxxyyyzzz
  - delay:
      hours: 0
      minutes: 2
      seconds: 0
      milliseconds: 0
mode: single
max_exceeded: silent

for the old video API use this video tag
video: >- /api/unifiprotect/video/{{ config_entry_id(trigger.entity_id) }}/{{ trigger.entity_id }}/{{ (as_timestamp(states[trigger.entity_id].last_changed) - 3)|timestamp_custom("%Y-%m-%dT%H:%M:%S+00:00", False) }}/{{ (as_timestamp(states[trigger.entity_id].last_changed) + 5)|timestamp_custom("%Y-%m-%dT%H:%M:%S+00:00", False) }}

I’ve already seen videos briefly appear in the notifications, but unfortunately, I’ve also encountered some 400 errors. Do I need to configure something, like a delay until the event is over?

Yes, the event needs to be over to get the video feed, see line 262 in the views file

[RaHehl]

That didn't work reliably for me—in fact, it was more reliably not working. However, what worked well was this:

sending the notification when motion transitions from "on" to "off," ensuring that the event is truly over.

alias: "Security: Kamera xx Motion an yyy"
description: ""
triggers:
  - entity_id:
      - binary_sensor.g5_bullet_motion
    trigger: state
    from: "on"
    to: "off"
actions:
  - data:
      message: "Bewegung an der xxx "
      data:
        image: >-
          /api/unifiprotect/thumbnail/{{ config_entry_id(trigger.entity_id)
          }}/{{ trigger.from_state.attributes.event_id }}
        video: >-
          /api/unifiprotect/video/{{ config_entry_id(trigger.entity_id) }}/{{
          trigger.from_state.attributes.event_id }}        
    action: notify.mobile_app_iphone
mode: single
max_exceeded: silent

[lutzvahl]

Thanks @RaHehl for your review and testing.

Unfortunately I can't merge it: Review required At least 1 approving review is required by reviewers with write access.

Anything to be done on my end to get another reviewer added?

[RaHehl]

@lutzvahl I think, essentially, you can only wait. For me, it’s fine, but I also don’t know all the rules here yet, and I haven’t worked much with Python so far. My area of expertise is actually Java. What might help is the example you can use to test everything. With a bit of luck, maybe @bdraco will have time to take a look at it.

[bdraco]

Please add test coverage for the missing lines