From e8a47136d4617e792516a53e86e3ce134c01c1b2 Mon Sep 17 00:00:00 2001 From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Date: Wed, 11 Sep 2024 13:44:52 +0200 Subject: [PATCH] Camera: add state (#34683) --- source/_integrations/camera.markdown | 66 ++++++++++++++++------------ 1 file changed, 37 insertions(+), 29 deletions(-) diff --git a/source/_integrations/camera.markdown b/source/_integrations/camera.markdown index 066a87ff6b0..c0dd3c950ec 100644 --- a/source/_integrations/camera.markdown +++ b/source/_integrations/camera.markdown @@ -18,7 +18,7 @@ The camera integration allows you to use IP cameras with Home Assistant. {% include integrations/building_block_integration.md %} -### Streaming video +## Streaming video If your camera supports it, and the [`stream`](/integrations/stream) integration is setup, you will be able to stream your cameras in the frontend and on supported media players. @@ -29,37 +29,45 @@ The `Preload stream` option will start the camera feed on Home Assistant startup Example showing the Preload Stream option in the camera dialog.

-### Actions +## The state of a camera + +A camera can have the following states. Not all camera integrations support all states. + +- **Streaming**: The camera transmits a live play-back of the video data it is recording. +- **Recording**: The camera is currently capturing video content. +- **Idle**: The camera is not currently capturing video content. + +## Actions Once loaded, the `camera` platform will expose actions that can be called to perform various actions. Available actions: `enable_motion_detection`, `disable_motion_detection`, `play_stream`, `record`, `snapshot`, `turn_off` and `turn_on`. -#### Action `enable_motion_detection` +### Action `enable_motion_detection` Enable the motion detection in a camera. | Data attribute | Optional | Description | -| ---------------------- | -------- | ---------------------------------------------------------------------------------- | -| `entity_id` | yes | Name(s) of entities to enable motion detection, e.g., `camera.living_room_camera`. | +| -------------- | -------- | ---------------------------------------------------------------------------------- | +| `entity_id` | yes | Name(s) of entities to enable motion detection, e.g., `camera.living_room_camera`. | -#### Action `disable_motion_detection` +### Action `disable_motion_detection` Disable the motion detection in a camera. | Data attribute | Optional | Description | -| ---------------------- | -------- | ----------------------------------------------------------------------------------- | -| `entity_id` | yes | Name(s) of entities to disable motion detection, e.g., `camera.living_room_camera`. | +| -------------- | -------- | ----------------------------------------------------------------------------------- | +| `entity_id` | yes | Name(s) of entities to disable motion detection, e.g., `camera.living_room_camera`. | -#### Action `play_stream` +### Action `play_stream` Play a live stream from a camera to selected media player(s). Requires [`stream`](/integrations/stream) integration to be set up. | Data attribute | Optional | Description | -| ---------------------- | -------- | ------------------------------------------------------------------------------------------- | -| `entity_id` | no | Name of entity to fetch stream from, e.g., `camera.living_room_camera`. | -| `media_player` | no | Name of media player to play stream on, e.g., `media_player.living_room_tv`. | -| `format` | yes | Stream format supported by `stream` integration and selected `media_player`. Default: `hls` | +| -------------- | -------- | ------------------------------------------------------------------------------------------- | +| `entity_id` | no | Name of entity to fetch stream from, e.g., `camera.living_room_camera`. | +| `media_player` | no | Name of media player to play stream on, e.g., `media_player.living_room_tv`. | +| `format` | yes | Stream format supported by `stream` integration and selected `media_player`. Default: `hls` | For example, the following action in an automation would send an `hls` live stream to your chromecast. @@ -72,18 +80,18 @@ action: media_player: media_player.chromecast ``` -#### Action `record` +### Action `record` Make a `.mp4` recording from a camera stream. Requires `stream` integration to be set up. Both `duration` and `lookback` options are suggestions, but should be consistent per camera. The actual length of the recording may vary. It is suggested that you tweak these settings to fit your needs. | Data attribute | Optional | Description | -| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `entity_id` | no | Name(s) of entities to create a snapshot from, e.g., `camera.living_room_camera`. | -| `filename` | no | Template of a file name. Variable is `entity_id`, e.g., {% raw %}`/tmp/{{ entity_id.name }}.mp4`{% endraw %}. | -| `duration` | yes | Target recording length (in seconds). Default: 30 | -| `lookback` | yes | Target lookback period (in seconds) to include in addition to duration. Only available if there is currently an active HLS stream. Default: 0 | +| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `entity_id` | no | Name(s) of entities to create a snapshot from, e.g., `camera.living_room_camera`. | +| `filename` | no | Template of a file name. Variable is `entity_id`, e.g., {% raw %}`/tmp/{{ entity_id.name }}.mp4`{% endraw %}. | +| `duration` | yes | Target recording length (in seconds). Default: 30 | +| `lookback` | yes | Target lookback period (in seconds) to include in addition to duration. Only available if there is currently an active HLS stream. Default: 0 | The path part of `filename` must be an entry in the `allowlist_external_dirs` in your [`homeassistant:`](/integrations/homeassistant/#allowlist_external_dirs) section of your {% term "`configuration.yaml`" %} file. @@ -102,14 +110,14 @@ action: {% endraw %} -#### Action `snapshot` +### Action `snapshot` Take a snapshot from a camera. | Data attribute | Optional | Description | -| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `entity_id` | no | Name(s) of entities to create a snapshot from, e.g., `camera.living_room_camera`. | -| `filename` | no | Template of a file name. Variable is `entity_id`, e.g., {% raw %}`/tmp/snapshot_{{ entity_id.name }}`{% endraw %}. | +| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | +| `entity_id` | no | Name(s) of entities to create a snapshot from, e.g., `camera.living_room_camera`. | +| `filename` | no | Template of a file name. Variable is `entity_id`, e.g., {% raw %}`/tmp/snapshot_{{ entity_id.name }}`{% endraw %}. | The path part of `filename` must be an entry in the `allowlist_external_dirs` in your [`homeassistant:`](/integrations/homeassistant/) section of your {% term "`configuration.yaml`" %} file. @@ -128,21 +136,21 @@ action: {% endraw %} -#### Action `turn_off` +### Action `turn_off` Turn off camera. Not all camera models support this action, please consult individual camera page. | Data attribute | Optional | Description | -| ---------------------- | -------- | ------------------------------------------------------------------- | -| `entity_id` | yes | Name(s) of entities to turn off, e.g., `camera.living_room_camera`. | +| -------------- | -------- | ------------------------------------------------------------------- | +| `entity_id` | yes | Name(s) of entities to turn off, e.g., `camera.living_room_camera`. | -#### Action `turn_on` +### Action `turn_on` Turn on camera. Not all camera models support this action, please consult individual camera page. | Data attribute | Optional | Description | -| ---------------------- | -------- | ------------------------------------------------------------------ | -| `entity_id` | yes | Name(s) of entities to turn on, e.g., `camera.living_room_camera`. | +| -------------- | -------- | ------------------------------------------------------------------ | +| `entity_id` | yes | Name(s) of entities to turn on, e.g., `camera.living_room_camera`. | ### Test if it works