Update WebRTC methods for async approach (#2409)

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
Robert Resch 2024-11-04 12:18:55 +01:00 committed by GitHub
parent 1bed08de7e
commit 610a095506
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -93,15 +93,38 @@ 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 `CameraEntityFeature.STREAM` with `frontend_stream_type` set to `StreamType.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.
WebRTC enabled cameras can be used by facilitating a direct connection with the home assistant frontend. This usage requires `CameraEntityFeature.STREAM` with `frontend_stream_type` set to `StreamType.WEB_RTC`.
The integration must implement the two following methods to support native WebRTC:
- `async_handle_async_webrtc_offer`: To initialize a WebRTC stream. Any messages/errors coming in async should be forwared to the frontend with the `send_message` callback.
- `async_on_webrtc_candidate`: The frontend will call it with any candidate coming in after the offer is sent.
The following method can optionally be implemented:
- `close_webrtc_session` (Optional): The frontend will call it when the stream is closed. Can be used to clean up things.
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."""
async def async_handle_async_webrtc_offer(
self, offer_sdp: str, session_id: str, send_message: WebRTCSendMessage
) -> None:
"""Handle the async WebRTC offer.
Async means that it could take some time to process the offer and responses/message
will be sent with the send_message callback.
This method is used by cameras with CameraEntityFeature.STREAM and StreamType.WEB_RTC.
An integration overriding this method must also implement async_on_webrtc_candidate.
Integrations can override with a native WebRTC implementation.
"""
async def async_on_webrtc_candidate(self, session_id: str, candidate: RTCIceCandidate) -> None:
"""Handle a WebRTC candidate."""
@callback
def close_webrtc_session(self, session_id: str) -> None:
"""Close a WebRTC session."""
```
### WebRTC Providers