Add Nest Battery Cam event clip support with a Nest MediaSource

[allenporter]

Proposed change

Add Nest Battery Cam event clip support with a Nest MediaSource

This adds an API for rendering media related to events, which includes
images as well as mp4 clip previews for Nest battery cameras. The media
source contains:

• A toplevel folder for Nest recent events
• A folder for every device that supports event media (images or video)
• Entries for recent events, such as "Person detected"

Future versions will include options for adjusting the of number of
events preserved, or media pre-fetching, as right now its just the
most recent event for each device, and fetched on demand.

Test coverage is 99% for the media_source and init.

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)
• 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 #
• This PR is related to issue:
• Link to documentation pull request: Add documentation for Nest Battery Camera Clip Previews and media source home-assistant.io#20380

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
• The code has been formatted using Black (black --fast homeassistant tests)
• 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 www.home-assistant.io

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

• The manifest file 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.
• Untested files have been added to .coveragerc.

The integration reached or maintains the following Integration Quality Scale:

• No score or internal
• 🥈 Silver
• 🥇 Gold
• 🏆 Platinum

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

[balloob]

Let's verify the user can access the device.

user = request[KEY_HASS_USER]
entity_id = ...  # Resolve device ID to camera entity ID.
user.permissions.check_entity(entity_id, POLICY_READ)

(we don't have a UI for this, but if we ever do, it is good to have these checks in place)

[allenporter]

Should the media source do this also?

[balloob]

yeah

[allenporter]

I did a quick look and this may require an architecture issue given the interface to the media player doesn't appear to provide this information. There was an arch discussion about a media source entity which could also be relevant. The way the check is currently implemented is the user needs access to all entities associated with a device, to be conservative even though.in practice there is only one nest camera today) but that could lend itself well to a media player entity permission. I'm sure though if this feature.is implemented the entire code base needs to be audited anyway, so we're just being slightly proactive here.

[balloob]

If this endpoint is only used for playing media, it would be great if we could use a 301 redirect to the actual content.

[allenporter]

We chatted about this, and the context here is that there are two steps:

• Convert an image to a URL which must be done within ~30 seconds of the event
• Fetch the bytes from the URL which also must be done within ~30 seconds
• We may also will transform the bytes in the case of media clips since they are 10 frame mp4s and we want to slow them down a bit

Right now this has a cache of a couple items. However, we also effectively need to always fetch these images directly when the event happens and persist them to really meet the user expectation of how this should work. So we'll consider a 1gb disk cache or something like this, and I think it may have a similar interface as what is already here.

[MartinHjelmare]

Is it important to return an OrderedDict and not just a dict, which is ordered by default?

[allenporter]

I did not know dict is ordered by default. I just need the events to be iterable in order, not that an OrderedDict itself is used. Thanks, I'll send a follow up.

[allenporter]

Ah! This is "new"in python 3.7 (or .6) thanks.

[MartinHjelmare]

👍