diff --git a/docs/core/entity/camera.md b/docs/core/entity/camera.md index 0d6bc321..7e351028 100644 --- a/docs/core/entity/camera.md +++ b/docs/core/entity/camera.md @@ -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