Add documentation for media browser image proxy (#699)

Co-authored-by: Paulus Schoutsen <paulus@home-assistant.io>
This commit is contained in:
rajlaud 2020-11-11 13:56:14 -06:00 committed by GitHub
parent 944089caf1
commit d1af30730a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -118,3 +118,29 @@ Optional. What type of media device is this. It will possibly map to google devi
| tv | Device is a television type device. | tv | Device is a television type device.
| speaker | Device is speakers or stereo type device. | speaker | Device is speakers or stereo type device.
| receiver | Device is audio video receiver type device taking audio and outputting to speakers and video to some display. | receiver | Device is audio video receiver type device taking audio and outputting to speakers and video to some display.
### Proxy album art for media browser
Optional. If your media player is only accessible from the internal network, it will need to proxy the album art via Home Assistant to be able to work while away from home or through a mobile app.
To proxy an image via Home Assistant, set the `thumbnail` property of a `BrowseMedia` item to a url generated by the `self.get_browse_image_url(media_content_type, media_content_id, media_image_id=None)` method. The browser will then fetch this url, which will result in a call to `async_get_browse_image(media_content_type, media_content_id, media_image_id=None)`.
:::info
Only use a proxy for the thumbnail if the web request originated from outside the network. You can test this with `is_local_request(hass)` imported from `homeassistant.helpers.network`.
:::
In `async_get_browse_image`, use `self._async_fetch_image(url)` to fetch the image from the local network. Do not use `self._async_fetch_image_from_cache(url)` which should only be used to for the currently playing artwork.
:::info
Do not pass an url as `media_image_id`. This can allow an attacker to fetch any data from the local network.
:::
```python
class MyMediaPlayer(MediaPlayerEntity):
# Implement the following method.
async def async_get_browse_image(self, media_content_type, media_content_id, media_image_id=None):
"""Serve album art. Returns (content, content_type)."""
image_url = ...
return await self._async_fetch_image(image_url)
```