Preview and Programme DVR Intervals

Overview

These two workflows can be built leveraging two configuration options both available as of version 1.195.0 of our API:

  1. Segment naming obfuscation pattern (for preview)
  2. The API endpoint RestLiveManifestTimeshift (for preview and Programme intervals)

Segment name obfuscation

This feature can be enabled by configuring the segmentNamingTemplate property of a given Muxing in our API.
Example Java code:

muxing.setSegmentNamingTemplate("segment_%number%_{segment_rand_chars:4}.ts");
  • %number% is required for the sequence number of the segment
  • {segment_rand_chars:4} is the placeholder for the random characters in the segment name. Each segment will have different random characters. 4 is the number of random characters inserted for the placeholder (the maximum and default is 32).

📘

Useful to know

The placeholder {rand_chars:4} is also possible, but it will assign the same random characters for all segments. This is useful to prevent overwritten segments when the same output folder is used.

Reset Live Manifest Timeshift

When issued, this option will remove older segments from live manifests. This resets or reduces the time-shift (DVR) window. This action helps you control how much content remains accessible during a live event.

You can configure this behavior using two parameters:

  • residualPeriodInSeconds:
    This defines how many seconds of content will remain in the manifest after segments are removed. If not set, all but one segment will be removed.
  • offsetInSeconds:
    This is an offset from the start of the live event, indicating the point from which all previous segments (within that duration) will be removed.
    • Example: If your segment length is 2 seconds and you set a timeshift window of 120 seconds (i.e., 60 segments), and you set offsetInSeconds to 120, all segments before segment 60 will be removed. The manifest will then only contain segment_60.ts to segment_80.ts (assuming segment_80.ts is the latest).

Note:
Only one of these parameters—residualPeriodInSeconds or offsetInSeconds—can be set.

The original time-shift window does not change. Newer segments will be added and not removed from the
manifest until the original time-shift duration is reached again.

Special cases when using Reset Live Manifest Timeshift

When using the parameter offsetInSeconds, there are two scenarios that can occur:

Reset in a future position

If you set offsetInSeconds to a value greater than the current duration of the manifest (i.e., a point in the future that hasn't yet been reached by the live stream), the reset action will take effect immediately. This is the case for HLS manifests and Dash Timeline.

For Dash Template manifests, instead, the reset action will be done at the specified period in the future. The player plays out its own video buffer, then stalls until the reset position is reached, and then continues normally.

Reset in a past position.

If you set offsetInSeconds to a value older than the segments currently present in the manifest (i.e., a point in the past that has already rolled out of the manifest window), the reset action will not have any effect. Since all segments prior to that offset have already been removed from the manifest, issuing the reset command does not change the manifest’s contents.

For Dash Template manifests, instead, the reset action will be done at the specified past period.


Preview workflow

To implement a “Preview Feature” for the Live Encoder, you will need to use both options described above. This workflow allows the first section of a live event stream to be published to a small subset of an audience, this could be to perform a signal line up and ensure all video and audio signals are levelled correctly and free of error. In this workflow customers would not want the main audience to have access to the preview content.

Single Manifest Concept

With this approach it is possible to use the same manifest for both the preview and live event phases. To go live there is a new ResetLiveManifestTimeShift API call, that removes all the media segments from the manifest so that after sharing the manifest with viewers after the API call, the segments that are part of the preview phase are not present anymore.

Usually, segments are numbered and people can easily guess the URLs of segments in the preview phase (e.g.: segment_0.ts, segment_1.ts, .., segment_100.ts). To prevent this “guessing” of preview phase segments we added the segment namining obfuscation feature. Using this feature adds a random text as part of each segment name and it’s almost impossible to guess the segment URLs give a certain segment number. (e.g. seg_e466d03bce_0.ts, seg_bd5558d871_1.ts, .. seg_55d32aaec7_25.ts).

How to set-up the Live Encoding

First, make sure the Segment Naming Obfuscation template is used in the Live Encoding configuration.

The following sequence diagram illustrates the whole “Preview” workflow:


  1. The Streamer starts ingesting RTMP, SRT, or Zixi into the Live Encoder
  2. The “Preview Phase” starts and the Encoder starts uploading the manifest files and media segments
  3. To “Go Live” the Streamer calls the ResetLiveManifestTimeShift endpoint
  4. The Encoder removes all old segments from the HLS manifest files
  5. The Streamer can share the manifest URL with the Viewers
  6. The Viewers can start watching the manifest and don’t have access to the media segments that were part of the “Preview Phase”. Thanks to the segment naming obfuscation, the URLs cannot be guessed by looking at the segment sequence numbers.

Programme DVR Intervals

For a 24/7 live linear channel, you may wish to use the ResetLiveManifestTimeShift endpoint to ensure that viewers are only able to view a DVR that relates to the current live programme, with previous programmes perhaps not available for Catch Up or only available as VOD at a certain later moment in time.