Camera entity

A camera entity can display images, and optionally a video stream. Derive a platform entity from homeassistant.components.camera.Camera.

Properties

tip

Properties should always only return information from memory and not do I/O (like network requests). Implement update() or async_update() to fetch data.

Name	Type	Default	Description
brand	str | None	None	The brand (manufacturer) of the camera.
frame_interval	float	0.5	The interval between frames of the stream.
is_on	bool	True	Indication of whether the camera is on.
is_recording	bool	False	Indication of whether the camera is recording. Used to determine state.
is_streaming	bool	False	Indication of whether the camera is streaming. Used to determine state.
model	str | None	None	The model of the camera.
motion_detection_enabled	bool	False	Indication of whether the camera has motion detection enabled.
use_stream_for_stills	bool	False	Determines whether or not to use the Stream integration to generate still images

States

The state is defined by setting the properties above. The resulting state uses the CameraState enum to return one of the below members.

Value	Description
RECORDING	The camera is currently recording.
STREAMING	The camera is currently streaming.
IDLE	The camera is currently idle.

Supported features

Supported features are defined by using values in the CameraEntityFeature enum and are combined using the bitwise or (|) operator.

Value	Description
ON_OFF	The device supports turn_on and turn_off
STREAM	The device supports streaming

Methods

Camera image

When the width and height are passed, scaling should be done on a best-effort basis. The UI will fall back to scaling at the display layer if scaling cannot be done by the camera.

• Return the smallest image that meets the minimum width and minimum height.

• When scaling the image, aspect ratio must be preserved. If the aspect ratio is not the same as the requsted height or width, it is expected that the width and/or height of the returned image will be larger than requested.

• Pass on the width and height if the underlying camera is capable of scaling the image.

• If the integration cannot scale the image and returns a jpeg image, it will automatically be scaled by the camera integration when requested.

class MyCamera(Camera):
    # Implement one of these methods.

    def camera_image(
        self, width: int | None = None, height: int | None = None
    ) -> bytes | None:
        """Return bytes of camera image."""
        raise NotImplementedError()

    async def async_camera_image(
        self, width: int | None = None, height: int | None = None
    ) -> bytes | None:
        """Return bytes of camera image."""

Stream source

The stream source should return a url that is usable by ffmpeg (e.g. an RTSP url). Requires CameraEntityFeature.STREAM.

A camera entity with a stream source by default uses StreamType.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.

class MyCamera(Camera):

    async def stream_source(self) -> str | None:
        """Return the source of the stream."""

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

WebRTC enabled cameras can be used by facilitating a direct connection with the home assistant frontend. This usage requires CameraEntityFeature.STREAM and 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. By implementing the WebRTC methods, the frontend assumes that the camera supports only WebRTC and therefore will not fallbac to HLS.

class MyCamera(Camera):

    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
        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

An integration may provide a WebRTC stream from an existing camera's stream source using the libraries in homeassistant.components.camera.webrtc. An integration may implement CameraWebRTCProvider and register it with async_register_webrtc_provider.

Turn on

class MyCamera(Camera):
    # Implement one of these methods.

    def turn_on(self) -> None:
        """Turn on camera."""

    async def async_turn_on(self) -> None:
        """Turn on camera."""

Turn off

class MyCamera(Camera):
    # Implement one of these methods.

    def turn_off(self) -> None:
        """Turn off camera."""

    async def async_turn_off(self) -> None:
        """Turn off camera."""

Enable motion detection

class MyCamera(Camera):
    # Implement one of these methods.

    def enable_motion_detection(self) -> None:
        """Enable motion detection in the camera."""

    async def async_enable_motion_detection(self) -> None:
        """Enable motion detection in the camera."""

Disable motion detection

class MyCamera(Camera):
    # Implement one of these methods.

    def disable_motion_detection(self) -> None:
        """Disable motion detection in camera."""

    async def async_disable_motion_detection(self) -> None:
        """Disable motion detection in camera."""