diff --git a/src/content/changelog/stream/2025-02-14-introducing-dvr-for-stream-live.mdx b/src/content/changelog/stream/2025-02-14-introducing-dvr-for-stream-live.mdx new file mode 100644 index 000000000000000..a41678d4b72de64 --- /dev/null +++ b/src/content/changelog/stream/2025-02-14-introducing-dvr-for-stream-live.mdx @@ -0,0 +1,23 @@ +--- +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. +date: 2025-02-14T12: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. + +When building a player embed code or manifest URL, just add `dvrEnabled=true` as +a query parameter. There are some things to be aware of when using this option. +For more information, refer to [DVR for Live](/stream/stream-live/dvr-for-live/). diff --git a/src/content/docs/stream/stream-live/dvr-for-live.mdx b/src/content/docs/stream/stream-live/dvr-for-live.mdx new file mode 100644 index 000000000000000..f1e1b930757c851 --- /dev/null +++ b/src/content/docs/stream/stream-live/dvr-for-live.mdx @@ -0,0 +1,80 @@ +--- +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, add the +`dvrEnabled=true` query parameter to the Stream Player embed source or the HLS +manifest URL. + +## Stream Player + +``` html title="Stream Player embed format" +
+ +
+``` + +When DVR mode is enabled the Stream Player will: + +- Show a timeline the viewer can scrub/seek, similar to watching an on-demand + video. The timeline will automatically scale to show the growing duration of + the broadcast while it is live. +- 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 + forward 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. + +## HLS manifest for custom players + +``` text title="HLS manifest URL format" +https://customer-.cloudflarestream.com//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. Refer to [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:** Use DVR Mode on a Video ID URL: + +- When the player loads, it will start playing the active broadcast if it is + still live or play the recording if the broadcast has concluded. + +DVR Mode on a Live Input ID URL: + +- When the player loads, it will start playing the currently live broadcast if + there is one (refer to [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, the + player may stall when trying to switch quality levels if a viewer is still + watching after a broadcast has concluded. +- Performance may be degraded for DVR-enabled broadcasts longer than three hours. + Manifests are limited to a maxiumum of 7,200 segments. Segment length is + determined by the keyframe interval, also called GOP size. +- DVR Mode relies on Version 8 of the HLS manifest specification. Stream usesW + HLS Version 6 in all other contexts. HLS v8 offers extremely broad compatibility + but may not work with certain old player libraries or older devices. +- DVR Mode is not available for DASH manifests. diff --git a/src/content/docs/stream/stream-live/live-instant-clipping.mdx b/src/content/docs/stream/stream-live/live-instant-clipping.mdx index dd112807dc542c1..c39e974caf498fe 100644 --- a/src/content/docs/stream/stream-live/live-instant-clipping.mdx +++ b/src/content/docs/stream/stream-live/live-instant-clipping.mdx @@ -1,10 +1,6 @@ --- pcx_content_type: how-to title: Live Instant Clipping -sidebar: - badge: - text: Beta - --- Stream supports generating clips of live streams and recordings so creators and viewers alike can highlight short, engaging pieces of a longer broadcast or recording. Live instant clips can be created by end users and do not result in additional storage fees or new entries in the video library. diff --git a/src/content/docs/stream/stream-live/watch-live-stream.mdx b/src/content/docs/stream/stream-live/watch-live-stream.mdx index a6112f19e8f4f25..afc26f0e32d6f50 100644 --- a/src/content/docs/stream/stream-live/watch-live-stream.mdx +++ b/src/content/docs/stream/stream-live/watch-live-stream.mdx @@ -10,15 +10,68 @@ 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. -## 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 main 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. This option is best for cases where a page is dedicated to a creator, channel, or +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 concluded. This option is 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._ -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. +Using DVR mode, explained below, there are additional considerations. + +Stream's URLs are all templatized for easy generation: + +**Stream built-in Player URL format:** + +``` +https://customer-.cloudflarestream.com//iframe +``` -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. +A full embed code can be generated in Dash or with the API. + +**HLS Manifest URL format:** + +``` +https://customer-.cloudflarestream.com//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. Select **Stream** > **Live Inputs**. +3. Select 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 select **Click to copy** beneath your choice. + +The embed code or manifest URL retrieved in Dash will reference the Live Input ID. + +## Use the API + +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 \ @@ -26,7 +79,21 @@ curl -X GET \ https://api.cloudflare.com/client/v4/accounts//stream/live_inputs//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,19 @@ The response contains the HLS/DASH URL that can be used to play the current live } ``` -## Use the dashboard - -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. +These will reference the Video ID. -## View by live input ID +## Live input status -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 " \ -https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/lifecycle +https://customer-.cloudflarestream.com//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 +195,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. - diff --git a/src/content/release-notes/stream.yaml b/src/content/release-notes/stream.yaml index 64f678afa86850c..4fd47e880355a6b 100644 --- a/src/content/release-notes/stream.yaml +++ b/src/content/release-notes/stream.yaml @@ -5,6 +5,14 @@ productLink: "/stream/" productArea: Developer platform productAreaLink: /workers/platform/changelog/platform/ entries: + - publish_date: "2025-02-10" + title: Stream Player ad support adjustments for Google Ad Exchange Verification + description: |- + Adjustments have been made to the Stream player UI when playing advertisements called by a customer-provided VAST or VMAP `ad-url` argument: + + A small progress bar has been added along the bottom of the player, and the shadow behind player controls has been reduced. These changes have been approved for use with Google Ad Exchange. + + This only impacts customers using the built-in Stream player and calling their own advertisements; Stream never shows ads by default. For more information, refer to [Using the Stream Player](https://developers.cloudflare.com/stream/viewing-videos/using-the-stream-player/#basic-options). - publish_date: "2025-01-30" title: Expanded Language Support for Generated Captions description: |-