How-to guides

• 1: Pre-rolls
• 2: HLS Target Duration

1 - Pre-rolls

The specific query-string trigger is a general escape query part ewm=1 which will make nginx forward the request to the ew-manip server. Pre-rolls assets are then added in VoD with the query parameter pre=<URL>. The <URL> must be the absolute public URL that the client uses to fetch the preroll video, since this URL will be inserted in the combined manifest delivered to the client.

A complete request, to combine preroll-bumper with program could look like this:

http://repack-host/__cl/s:vod/__c/program/__op/default/__f/index.m3u8?ewm=1&pre=https://public-repack-host/__cl/s:vod/__c/preroll-bumper/__op/default/__f/index.m3u8

Multiple pre= query parts can be added to combine more than two manifests. The service will then fetch all the manifests from the repackager and combine them into the appropriate manifest with multiple periods for DASH or multiple parts separated by discontinuities for HLS.

DASH manifest URLs look similar but must have the file extension .mpd. HLS playlist must have the file extension .m3u8.

Limitations

DASH and HLS URLs cannot be combined with each other. For DASH, any assets can be combined, but for the best user experience it is reasonable to apply similar critera as for HLS. For HLS the following criteria must be met:

HLS Playlist Matching Criteria

In brief, the main and all the pre-roll master playlist(s) must match each other.

In detail, this means that:

• For Renditions identified by #EXT-X-MEDIA: For each rendition in the main playlist, there must be exactly one corresponding rendition in each pre-roll playlist, and the following attributes (when present) must match exactly: TYPE, and LANGUAGE. Unmatched renditions in the pre-rolls will be discarded.

  • When matching renditions, in addition to the criteria mentioned above, ew-manip will match a rendition in the main playlist with the closest bitrate (without duplicate matching)

• For Variant streams identified by #EXT-X-STREAM-INF: For each variant stream in the main playlist, there must be exactly one corresponding variant stream in each pre-roll playlist, and the following attributes (when present) must match exactly: RESOLUTION, FRAME-RATE, CODECS, AUDIO, VIDEO and SUBTITLES. Unmatched variant streams in the pre-rolls will be discarded.

• For I-frame playlists identified by #EXT-X-I-FRAME-STREAM-INF: For each I-frame playlist in the main master playlist, there must be exactly one corresponding I-frame playlist in each pre-roll master playlist, and the following attributes (when present) must match exactly: RESOLUTION and CODECS. Unmatched I-frame playlists in the pre-rolls will be discarded.

Playlist requests where the main and pre-roll master playlists do not meet all of the above criteria, will fail with an HTTP 400 error.

HLS Stream and Playlist Matching by Bandwidth

Typically there will be several variant streams that meet these criteria and only differ in BANDWIDTH. Within such matching groups (for example streams with the same resolution) the main and pre-roll streams are paired together by being sorted by bandwidth in decreasing order. The same pairing method is used for I-frame playlists.

2 - HLS Target Duration

A common issue when playing live HLS is the value of target duration (EXT-X-TARGETDURATION). The target duration is an integral number of seconds that correspond to the longest segment in the stream. Depending on HLS version, this value must either be higher than the longest duration, or can be rounded to the closest integer, but many players desire a lower value in order to work best. This is due to that the target-duration value influences how often the client can ask for a playlist update.

Because live ingest node (ESB3003) generates segments with a precise average segment duration, adjusted segmentation boundaries due to SCTE-35 ad markers number may result in a single segment duration being 1.5 times the average duration. These singular values then effect the target-duration to become high.

To be able to fine-tune the target duration, the ew-manip service has an option to change the #EXT-X-TARGET-DURATON value by using the special query-string trigger target-duration= once ew-manip has been triggered with the general ewm=1 trigger.

An example of a request that includes the target-duration=5 query parameter to set #EXT-X-TARGET-DURATON to 5seconds could look like this:

http://repack-host/__cl/cg:live/__c/program/__op/default/__f/index.m3u8?ewm=1&target-duration=5

This will only apply to “live-like” playlists from the repackager. With “live-like” playlists, we mean playlists which come from a live channel including an interval in the past. Such playlists can be detected by searching for the part __cl/cg: in the URL that indicates that the URL is part of a live channel group. Media playlists with the stopTime in the past are technically VoD playlists, but since there is a transition from EVENT to VOD type of playlist as the stopTime is passed, they should be treated as live playlists.

For pure VoD assets, the target-duration can simply be calculated from the longest segment in the playlist, and there is in general no limit on how fast the segments can be requested, so there is no need for target duration modifications.