[Stream] Initial pass on DVR documentation

tsmith512 · tsmith512 · commit 227e56592735 · 2025-02-13T13:08:15.000-06:00
diff --git a/src/content/changelogs-next/2025-02-12-introducing-dvr-for-stream-live.mdx b/src/content/changelogs-next/2025-02-12-introducing-dvr-for-stream-live.mdx
@@ -0,0 +1,29 @@
+---
+title: "Rewind, Replay, Resume: Introducing DVR for Stream Live"
+description: >
+  Stream has added support for DVR for Live broadcasts. In other words, for those
+  who didn’t witness the magic of TiVo, you can now allow your viewers to rewind
+  and replay Live content during broadcasts.
+products:
+  - stream
+date: 2025-02-12T12:00:00Z
+---
+
+
+Previously, all viewers watched "the live edge," or the latest content of the
+broadcast, synchronously. If a viewer paused for more than a few seconds,
+the player would automatically "catch up" when playback started again. Seeking
+through the broadcast was only available once the recording was available after
+it conluded.
+
+Starting today, customers can make a small adjustment to the player
+embed or manifest URL to enable the DVR experience for their viewers. By
+offering this feature as an opt-in adjustment, our customers are empowered to
+pick the best experiences for their applications.
+
+## How to get started
+
+This feature is already available to all customers. When building a player embed
+code or manifest URL, add `dvrEnabled=true` as a query parameter. There are some
+things to be aware of when using this option. For more information, refer to
+[@TODO PLACEHOLDER](/)
diff --git a/src/content/docs/stream/stream-live/dvr-for-live.mdx b/src/content/docs/stream/stream-live/dvr-for-live.mdx
@@ -0,0 +1,74 @@
+---
+pcx_content_type: how-to
+title: DVR for Live
+sidebar:
+  badge:
+    text: Beta
+---
+
+Stream Live supports "DVR mode" on an opt-in basis to allow viewers to rewind,
+resume, and fast-forward a live broadcast. To enable DVR mode, simply add the
+`dvrEnabled=true` query parameter to the Stream Player embed source or the HLS
+manigest URL. For example:
+
+``` html title="Embed Code"
+<div style="position: relative; padding-top: 56.25%;">
+  <iframe
+    src="https://customer-<CODE>.cloudflarestream.com/<INPUT_ID|VIDEO_ID>/iframe?dvrEnabled=true"
+    style="border: none; position: absolute; top: 0; left: 0; height: 100%; width: 100%;"
+    allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
+    allowfullscreen="true"
+  ></iframe>
+</div>
+```
+
+When DVR mode is enabled the Stream Player will:
+
+- Show a timeline the viwer can scrub/seek, like when watching an on-demand video
+  the timeline will automatically scale to show the growing duration of the broadcast.
+- The "LIVE" indicator will show grey if the viewer is behind the live edge or
+  red if they are watching the latest content. Clicking that indicator will jump
+  back to the live edge.
+- If the viewer pauses the player, it will resume playback from that time instead
+  of jumping forward to the live edge.
+
+``` text title="HLS Manifest"
+https://customer-<CODE>.cloudflarestream.com/<INPUT_ID|VIDEO_ID>/manifest/video.m3u8?dvrEnabled=true
+```
+
+Custom players using a DVR-capable HLS manifest may need additional
+configuration to surface helpful controls or information. Refer to your player
+library for additional information.
+
+## Video ID or Input ID
+
+Stream Live allows loading the Player or HLS manifest by Video ID or Live Input
+ID. See [Watch a live stream](/stream/stream-live/watch-live-stream/) for how to
+retrieve these URLs and compare these options. There are additional
+considerations when using DVR mode:
+
+**Recommended:** When using DVR Mode on a Video ID URL:
+
+- When the player loads, it will start playing the active broadcast if it is
+  still live, or its recording if the broadcast has concluded.
+
+When using DVR Mode on a Live Input ID URL:
+
+- When the player loads, it will start playing the currently live broadcast if
+  there is one (see [Live Input Status](/stream/stream-live/watch-live-stream/#live-input-status)).
+- If the viewer is still watching _after the broadcast ends,_ they can continue
+  to watch. However, if the player or manifest is then reloaded, it will show the
+  latest broadcast or "Stream has not yet started" (`HTTP 204`). Past broadcasts
+  are not available by Live Input ID.
+
+## Known Limitations
+
+- When using DVR Mode and a player/manifest created using a Live Input ID, if a
+  viewer is still watching after a broadcast has concluded, the player may stall
+  when trying to switch quality levels.
+- There is no enforced limit to the maximum duration of a DVR manifest, however
+  performance may be degraded for DVR manifests longer than 3 hours.
+- DVR Mode relies on Version 8 of the HLS manifest specification, which is newer
+  than Version 6, which Stream Live and On-Demand currently use. HLS v8 offers
+  extremely broad compatibility but may not work with certain old player libraries
+  or older devices.
diff --git a/src/content/docs/stream/stream-live/watch-live-stream.mdx b/src/content/docs/stream/stream-live/watch-live-stream.mdx
@@ -10,23 +10,90 @@ sidebar:
 
 import { Render } from "~/components"
 
-When an input begins receiving the live stream, a new video with HLS and DASH URLs is automatically created as long as the mode property for the input is set to `automatic`.
+When a [Live Input](/stream/stream-live/start-stream-live/) begins receiving a
+broadcast, a new video is automatically created if the input's `mode` property
+is set to `automatic`.
+
+To watch, Stream offers a built-in Player or you use a custom player with the
+HLS and DASH manifests.
 
 <Render file="chromecast_limitations" />
 
-## Use the API
+## View by Live Input ID or Video ID
+
+Whether you use the Stream Player or a custom player with a manifest, you can
+reference the Live Input ID or a specific Video ID. The difference is what
+happens when a broadcast concludes.
+
+Use a Live Input ID in instances where a player should always show the active
+broadcast, if there is one, or a "Stream has not started" message if the input
+is idle. Best for cases where a page is dedicated to a creator, channel,
+recurring program. The Live Input ID is provisioned for you when you create the
+input; it will not change.
+
+Use a Video ID in instances where a player should be used to display a single
+broadcast or its recording once the broadcast has conluded. Best for cases where
+a page is dedicated to a one-time event, specific episode/occurance, or date.
+There is a _new_ Video ID generated for each broadcast when it starts.
+
+Using DVR mode, explaind below, there are additional considerations.
+
+Stream's URLs are all templatized for easy generation:
+
+**Stream built-in Player URL format:**
+
+```
+https://customer-<CODE>.cloudflarestream.com/<INPUT_ID|VIDEO_ID>/iframe
+```
+
+A full embed code can be generated in Dash or with the API.
+
+**HLS Manifest URL format:**
+
+```
+https://customer-<CODE>.cloudflarestream.com/<INPUT_ID|VIDEO_ID>/manifest/video.m3u8
+```
+
+You can also retrieve the embed code or manifest URLs from Dash or the API.
+
+## Use the dashboard
+
+To get the Stream built-in player embed code or HLS Manifest URL for a custom player:
+
+1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
+2. Click **Stream** > **Live Inputs**.
+3. Click a live input from the list.
+4. Locate the **Embed** and **HLS Manifest URL** beneath the video.
+5. Determine which option to use and then click **Click to copy** beneath your choice.
+
+These will reference the Live Input ID.
 
-A live input can have multiple video UIDs associated with it. To get the video UID representing the current live stream for a given input, make a `GET` request to the `/stream` endpoint.
+## Use the API
 
-To play the video in your browser, use the URL from the `preview` field. To use your own player, use the `hls` or `dash` URLs.
+To retrieve the player code or manifest URLs via the API, fetch the Live Input's
+list of videos:
 
 ```bash title="Request"
 curl -X GET \
 -H "Authorization: Bearer <API_TOKEN>" \
 https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/live_inputs/<LIVE_INPUT_UID>/videos
 ```
 
-The response contains the HLS/DASH URL that can be used to play the current live video as well as any previously recorded live videos. In the example below, the state of the live video is `live-inprogress` and the state for previously recorded video is `ready`.
+A live input will have multiple videos associated with it, one for each broadcast.
+If there is an active broadcast, the first video in the response will have a
+`live-inprogress` status. Other videos in the response represent recordings
+which can be played on-demand.
+
+Each video in the response, including the active broadcast if there is one,
+contains the HLS and DASH URLs and a link to the Stream player. Noteworthy
+properties include:
+
+- `preview` -- Link to the Stream player to watch
+- `playback`.`hls` -- HLS Manifest
+- `playback`.`dash` -- DASH Manifest
+
+In the example below, the state of the live video is `live-inprogress` and the
+state for previously recorded video is `ready`.
 
 ```json title="Response" {4,7,21,28,32,46}
 {
@@ -83,32 +150,17 @@ The response contains the HLS/DASH URL that can be used to play the current live
 }
 ```
 
-## Use the dashboard
+## Live input status
 
-To get the embed code or HLS Manifest URL for your video:
-
-1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
-2. Click **Stream** > **Live Inputs**.
-3. Click a live input from the list to select it. The page for your live input displays.
-4. Locate the **Embed** and **HLS Manifest URL** beneath the video.
-5. Determine which option to use and then click **Click to copy** beneath your choice.
-
-## View by live input ID
-
-You can use one of the options below to view a live video by input ID:
-
-* Replace the video ID with the input ID.
-* Use the Embed code.
-* Use the Manifest URL.
-
-## Live input ID status
-
-You can check whether a live input ID is currently streaming a video or not by making a request to the `lifecycle` endpoint. The Stream player supports using input IDs to check a live stream status, but third party players may require additional support.
+You can check whether a live input is currently streaming and what its active
+video ID is by making a request to its `lifecycle` endpoint. The Stream player
+does this automatically to show a note when the input is idle. Custom players
+may require additional support.
 
 ```bash
 curl -X GET \
 -H "Authorization: Bearer <API_TOKEN>" \
-https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/lifecycle
+https://customer-<CODE>.cloudflarestream.com/<INPUT_ID>/lifecycle
 ```
 
 In the example below, the response indicates the `ID` is for an input with an active `videoUID`. The `live` status value indicates the input is actively streaming.
@@ -141,4 +193,3 @@ After a live stream ends, a recording is automatically generated and available w
 While the recording of the live stream is generating, the video may report as `not-found` or `not-started`.
 
 If you are not using the Stream player for live stream recordings, refer to [Record and replay live streams](/stream/stream-live/replay-recordings/) for more information on how to replay a live stream recording.
-
