From d91a531108292c7bca74d68588f423c01f9298ee Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Sun, 17 Oct 2021 11:44:50 -0700 Subject: [PATCH 1/8] Update camera documentation for WebRTC Add camera documentation for WebRTC support, and improve documentation for streams generally. --- docs/core/entity/camera.md | 43 +++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/docs/core/entity/camera.md b/docs/core/entity/camera.md index 2930ae4b..60fe8b2c 100644 --- a/docs/core/entity/camera.md +++ b/docs/core/entity/camera.md @@ -14,11 +14,22 @@ Properties should always only return information from memory and not do I/O (lik | Name | Type | Default | Description | ---- | ---- | ------- | ----------- | is_recording | bool | None | Indication of whether the camera is recording. Used to determine `state`. +| is_streaming | bool | None | Indication of whether the camera is streaming. Used to determine `state`. | motion_detection_enabled | bool | False | Indication of whether the camera has motion detection enabled. | is_on | bool | True | Indication camera is on. | brand | str | None | The brand (manufacturer) of the camera. | model | str | None | The model of the camera. | frame_interval | float | 0.5 | The interval between frames of the stream. +| frontend_stream_type | str | None | Tells the frontend which type of stream to use either `STREAM_TYPE_HLS` or `STREAM_TYPE_WEBRTC`. Used with `SUPPORT_STREAM`i. + +### Supported features + +Supported features constants are combined using the bitwise or (`|`) operator. + +| Name | Bit value | Description | +| ---------------------------------- | --- | ------------------------------------------------------------------------------------------- | +| `SUPPORT_ON_OFF` | 1 | The device supports `turn_on` and `turn_off` | +| `SUPPORT_STREAM` | 2 | The device supports streaming | ## Methods @@ -53,7 +64,7 @@ class MyCamera(Camera): ### Stream Source -The stream source should return a url that is usable by ffmpeg. +The stream source should return an RTSP URL that is usable by ffmpeg and the `stream` component for rendering and recording. ```python class MyCamera(Camera): @@ -63,6 +74,36 @@ class MyCamera(Camera): ``` +The default `frontend_stream_type` is `STREAM_TYPE_HLS` which will use this stream source and the `stream` component to serve the RTSP stream with HLS. + +A camera entity may also use the `stream_source` to render the preview image. + +```python +from haffmpeg.tools import IMAGE_JPEG +from homeassistant.components.ffmpeg import async_get_image + +class MyCamera(Camera): + + async def async_camera_image( + self, width: int | None = None, height: int | None = None + ) -> bytes | None: + """Return bytes of camera image.""" + stream_url = await self.stream_source() + return await async_get_image(self.hass, stream_url, output_format=IMAGE_JPEG) +``` + +### WebRTC Streams + +Cameras that natively support Web RTC streams can set `frontend_stream_type` as `STREAM_TYPE_WEB_RTC` and implement the signal path to pass an offer to the device, and return an answer back to the frontend. The stream is initiated from the +frontend directly to the camera device. WebRTC streams do not use the `stream` component and do not support recording. + +```python +class MyCamera(Camera): + + async def async_handle_web_rtc_offer(self, offer_sdp: str) -> str | None: + """Handle the WebRTC offer and return an answer.""" +``` + ### Turn on ```python From bb090688ea0b49c816ae5d24b9aa996790dbabd0 Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Sun, 17 Oct 2021 11:52:22 -0700 Subject: [PATCH 2/8] Simplify documentaiton wording --- docs/core/entity/camera.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/core/entity/camera.md b/docs/core/entity/camera.md index 60fe8b2c..04e3915f 100644 --- a/docs/core/entity/camera.md +++ b/docs/core/entity/camera.md @@ -20,7 +20,8 @@ Properties should always only return information from memory and not do I/O (lik | brand | str | None | The brand (manufacturer) of the camera. | model | str | None | The model of the camera. | frame_interval | float | 0.5 | The interval between frames of the stream. -| frontend_stream_type | str | None | Tells the frontend which type of stream to use either `STREAM_TYPE_HLS` or `STREAM_TYPE_WEBRTC`. Used with `SUPPORT_STREAM`i. +| frontend_stream_type | str | None | Used with `SUPPORT_STREAM` to tell the frontend which type of stream to use +(`STREAM_TYPE_HLS` or `STREAM_TYPE_WEBRTC`) ### Supported features @@ -64,7 +65,7 @@ class MyCamera(Camera): ### Stream Source -The stream source should return an RTSP URL that is usable by ffmpeg and the `stream` component for rendering and recording. +The stream source should return an RTSP URL that is usable by ffmpeg and the `stream` component for rendering and recording. Requires `SUPPORT_STREAM`. ```python class MyCamera(Camera): @@ -94,8 +95,10 @@ class MyCamera(Camera): ### WebRTC Streams -Cameras that natively support Web RTC streams can set `frontend_stream_type` as `STREAM_TYPE_WEB_RTC` and implement the signal path to pass an offer to the device, and return an answer back to the frontend. The stream is initiated from the -frontend directly to the camera device. WebRTC streams do not use the `stream` component and do not support recording. +WebRTC enabled cameras can be used with the home assistant frontend. Requires `SUPPORT_STREAM`. A camera entity may set `frontend_stream_type` to `STREAM_TYPE_WEB_RTC` and implement the signal path to pass the frontends SDP offer to the +device, and return back the answer. The stream is initiated from the frontend which talks directly to the device. + +WebRTC streams do not use the `stream` component and do not support recording. ```python class MyCamera(Camera): From 64ecbc2bc8cfb9a378d0994ef5d8e94d60dc3e6d Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Sun, 17 Oct 2021 11:56:59 -0700 Subject: [PATCH 3/8] Fix image example to use width and height --- docs/core/entity/camera.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/entity/camera.md b/docs/core/entity/camera.md index 04e3915f..a867e518 100644 --- a/docs/core/entity/camera.md +++ b/docs/core/entity/camera.md @@ -77,7 +77,7 @@ class MyCamera(Camera): The default `frontend_stream_type` is `STREAM_TYPE_HLS` which will use this stream source and the `stream` component to serve the RTSP stream with HLS. -A camera entity may also use the `stream_source` to render the preview image. +A camera entity may also use the `stream_source` to render a still camera image with `ffmpeg`. ```python from haffmpeg.tools import IMAGE_JPEG @@ -90,7 +90,7 @@ class MyCamera(Camera): ) -> bytes | None: """Return bytes of camera image.""" stream_url = await self.stream_source() - return await async_get_image(self.hass, stream_url, output_format=IMAGE_JPEG) + return await async_get_image(self.hass, stream_url, output_format=IMAGE_JPEG, width=width, height=height) ``` ### WebRTC Streams From ed5389cbf332f5f74074169e1fc28d3c0fe78181 Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Sun, 17 Oct 2021 12:03:33 -0700 Subject: [PATCH 4/8] Improve stream source documentation --- docs/core/entity/camera.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/core/entity/camera.md b/docs/core/entity/camera.md index a867e518..e07c1723 100644 --- a/docs/core/entity/camera.md +++ b/docs/core/entity/camera.md @@ -65,7 +65,9 @@ class MyCamera(Camera): ### Stream Source -The stream source should return an RTSP URL that is usable by ffmpeg and the `stream` component for rendering and recording. Requires `SUPPORT_STREAM`. +The stream source should return an RTSP URL that is usable by ffmpeg. Requires `SUPPORT_STREAM`. + +A camera entity with a stream source by default use `STREAM_TYPE_HLS` to tell the frontend to use an HLS feed with the `stream` component. This stream source is also be used with `stream` for recording. ```python class MyCamera(Camera): @@ -75,9 +77,7 @@ class MyCamera(Camera): ``` -The default `frontend_stream_type` is `STREAM_TYPE_HLS` which will use this stream source and the `stream` component to serve the RTSP stream with HLS. - -A camera entity may also use the `stream_source` to render a still camera image with `ffmpeg`. +A camera entity may also use the stream source to render a still camera image with `ffmpeg`. ```python from haffmpeg.tools import IMAGE_JPEG From cad34a639302f0fb436a9993fe5b2a2475e4282e Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Mon, 18 Oct 2021 19:01:22 -0700 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Martin Hjelmare --- docs/core/entity/camera.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/entity/camera.md b/docs/core/entity/camera.md index e07c1723..d0234a0d 100644 --- a/docs/core/entity/camera.md +++ b/docs/core/entity/camera.md @@ -67,7 +67,7 @@ class MyCamera(Camera): The stream source should return an RTSP URL that is usable by ffmpeg. Requires `SUPPORT_STREAM`. -A camera entity with a stream source by default use `STREAM_TYPE_HLS` to tell the frontend to use an HLS feed with the `stream` component. This stream source is also be used with `stream` for recording. +A camera entity with a stream source by default uses `STREAM_TYPE_HLS` to tell the frontend to use an HLS feed with the `stream` component. This stream source will also be used with `stream` for recording. ```python class MyCamera(Camera): @@ -95,7 +95,7 @@ class MyCamera(Camera): ### WebRTC Streams -WebRTC enabled cameras can be used with the home assistant frontend. Requires `SUPPORT_STREAM`. A camera entity may set `frontend_stream_type` to `STREAM_TYPE_WEB_RTC` and implement the signal path to pass the frontends SDP offer to the +WebRTC enabled cameras can be used with the home assistant frontend. Requires `SUPPORT_STREAM`. A camera entity may set `frontend_stream_type` to `STREAM_TYPE_WEB_RTC` and implement the signal path to pass the frontend's SDP offer to the device, and return back the answer. The stream is initiated from the frontend which talks directly to the device. WebRTC streams do not use the `stream` component and do not support recording. From ff1849f983c85a4a0ce1b92233a63faa8f70c9f2 Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Tue, 19 Oct 2021 20:36:20 -0700 Subject: [PATCH 6/8] Update docs/core/entity/camera.md Co-authored-by: uvjustin <46082645+uvjustin@users.noreply.github.com> --- docs/core/entity/camera.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/entity/camera.md b/docs/core/entity/camera.md index d0234a0d..28770810 100644 --- a/docs/core/entity/camera.md +++ b/docs/core/entity/camera.md @@ -95,7 +95,7 @@ class MyCamera(Camera): ### WebRTC Streams -WebRTC enabled cameras can be used with the home assistant frontend. Requires `SUPPORT_STREAM`. A camera entity may set `frontend_stream_type` to `STREAM_TYPE_WEB_RTC` and implement the signal path to pass the frontend's SDP offer to the +WebRTC enabled cameras can be used by facilitating a direct connection with the home assistant frontend. This usage requires `SUPPORT_STREAM` with `frontend_stream_type` set to `STREAM_TYPE_WEB_RTC`. The integration should implement `async_handle_web_rtc_offer` which passes the frontend's SDP offer to the device and returns back the answer. device, and return back the answer. The stream is initiated from the frontend which talks directly to the device. WebRTC streams do not use the `stream` component and do not support recording. From e0705c604ddfb2105b9c741b00e525f93020b2dc Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Thu, 21 Oct 2021 20:08:18 -0700 Subject: [PATCH 7/8] Address pr review feedback --- docs/core/entity/camera.md | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/docs/core/entity/camera.md b/docs/core/entity/camera.md index e07c1723..9029000c 100644 --- a/docs/core/entity/camera.md +++ b/docs/core/entity/camera.md @@ -65,7 +65,7 @@ class MyCamera(Camera): ### Stream Source -The stream source should return an RTSP URL that is usable by ffmpeg. Requires `SUPPORT_STREAM`. +The stream source should return a url that is usable by ffmpeg (e.g. an RTSP url). Requires `SUPPORT_STREAM`. A camera entity with a stream source by default use `STREAM_TYPE_HLS` to tell the frontend to use an HLS feed with the `stream` component. This stream source is also be used with `stream` for recording. @@ -77,21 +77,7 @@ class MyCamera(Camera): ``` -A camera entity may also use the stream source to render a still camera image with `ffmpeg`. - -```python -from haffmpeg.tools import IMAGE_JPEG -from homeassistant.components.ffmpeg import async_get_image - -class MyCamera(Camera): - - async def async_camera_image( - self, width: int | None = None, height: int | None = None - ) -> bytes | None: - """Return bytes of camera image.""" - stream_url = await self.stream_source() - return await async_get_image(self.hass, stream_url, output_format=IMAGE_JPEG, width=width, height=height) -``` +A common way for a camera entity to render a camera still image is to pass the stream source to `async_get_image` in the `ffmpeg` component. ### WebRTC Streams From 49adcc3db5d13d905f9bc0a016bcd3f6922b93c3 Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Fri, 22 Oct 2021 10:09:06 -0700 Subject: [PATCH 8/8] Remove unnecessary and duplicate text --- docs/core/entity/camera.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/core/entity/camera.md b/docs/core/entity/camera.md index 5ff442f5..f128f854 100644 --- a/docs/core/entity/camera.md +++ b/docs/core/entity/camera.md @@ -82,7 +82,6 @@ A common way for a camera entity to render a camera still image is to pass the s ### WebRTC Streams WebRTC enabled cameras can be used by facilitating a direct connection with the home assistant frontend. This usage requires `SUPPORT_STREAM` with `frontend_stream_type` set to `STREAM_TYPE_WEB_RTC`. The integration should implement `async_handle_web_rtc_offer` which passes the frontend's SDP offer to the device and returns back the answer. -device, and return back the answer. The stream is initiated from the frontend which talks directly to the device. WebRTC streams do not use the `stream` component and do not support recording.