From dd0514c3d4dad48f7dfe44b5ed8f7d53d33c4387 Mon Sep 17 00:00:00 2001
From: Jason Hunter <hunterjm@gmail.com>
Date: Sat, 30 Mar 2019 04:25:52 -0400
Subject: [PATCH] add record services (#9062)

---
 source/_components/camera.markdown | 29 ++++++++++++++++++++++++++++-
 source/_components/stream.markdown | 29 +++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/source/_components/camera.markdown b/source/_components/camera.markdown
index 0aee4c4e8dc..8a0f52d2577 100644
--- a/source/_components/camera.markdown
+++ b/source/_components/camera.markdown
@@ -57,7 +57,7 @@ Take a snapshot from a camera.
 | Service 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 }}`{% endraw %}. |
+| `filename`             |      no  | Template of a file name. Variable is `entity_id`, e.g., {% raw %}`/tmp/snapshot_{{ entity_id }}`{% endraw %}. |
 
 The path part of `filename` must be an entry in the `whitelist_external_dirs` in your [`homeassistant:`](/docs/configuration/basic/) section of your `configuration.yaml` file.
 
@@ -73,6 +73,33 @@ action:
 ```
 {% endraw %}
 
+#### {% linkable_title Service `record` %}
+
+Make a `.mp4` recording from a camera stream. Requires `stream` component 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.
+
+| Service 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 }}.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 `whitelist_external_dirs` in your [`homeassistant:`](/docs/configuration/basic/) section of your `configuration.yaml` file.
+
+For example, the following action in an automation would take a recording from "yourcamera" and save it to /tmp with a timestamped filename.
+
+{% raw %}
+```yaml
+action:
+  service: camera.record
+  data:
+    entity_id: camera.yourcamera
+    filename: '/tmp/{{ entity_id }}_{{ now().strftime("%Y%m%d-%H%M%S") }}.mp4'
+```
+{% endraw %}
+
 #### {% linkable_title Service `play_stream` %}
 
 Play a live stream from a camera to selected media player(s). Requires `stream` component to be set up.
diff --git a/source/_components/stream.markdown b/source/_components/stream.markdown
index aa31666b926..1e67b3322e3 100644
--- a/source/_components/stream.markdown
+++ b/source/_components/stream.markdown
@@ -26,6 +26,35 @@ To enable this component, add the following lines to your `configuration.yaml` f
 stream:
 ```
 
+### {% linkable_title Services %}
+
+Once loaded, the `stream` platform will expose services that can be called to perform various actions.
+
+#### {% linkable_title Service `record` %}
+
+Make a `.mp4` recording from a provided stream.  While this service can be called directly, it is used internally by the [`camera.record`](/components/camera#service-record) service.
+
+Both `duration` and `lookback` options are suggestions, but should be consistent per stream.  The actual length of the recording may vary. It is suggested that you tweak these settings to fit your needs.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `stream_source`        |      no  | The input source for the stream, e.g., `rtsp://my.stream.feed:554`. |
+| `filename`             |      no  | The file name string. Variable is `entity_id`, e.g., `/tmp/my_stream.mp4`. |
+| `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 for `stream_source`. Default: 0 |
+
+The path part of `filename` must be an entry in the `whitelist_external_dirs` in your [`homeassistant:`](/docs/configuration/basic/) section of your `configuration.yaml` file.
+
+For example, the following action in an automation would take a recording from `rtsp://my.stream.feed:554` and save it to `/tmp`.
+
+```yaml
+action:
+  service: camera.record
+  data:
+    stream_source: rtsp://my.stream.feed:554
+    filename: '/tmp/my_stream.mp4'
+```
+
 ## {% linkable_title Troubleshooting %}
 
 Some users on manual installs may see the following error in their logs after restarting: