Javascript Libraries for HLS Manifest Manipulation

This developer blog was written by an Eyevinn Special Video-Dev Team

The concept to put a manifest proxy between the origin and video player to manipulate the HLS manifest can solve a number of use cases. Use cases ranging from server side ad insertion, deterministic stream corruptions to in-stream CDN switching. We have developed a couple of Javascript (NodeJS) libraries that can be used when doing HLS manifest manipulations that we also have open sourced and are available at our Open Source Software Center on GitHub.

Insert an HLS VOD in another VOD

The Javascript library hls-splice can be used to insert an HLS VOD into another VOD. One use case is to insert a jingle in the beginning of a VOD or ads in the middle of a VOD. The library only manipulates the HLS manifests and does not touch the video segments which means that are limitations on how exact the VOD can be inserted. It is constrained to segment boundaries. To illustrate what this library does, consider the following HLS VOD:

#EXTM3U
#EXT-X-TARGETDURATION:3
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:1
#EXTINF:3.000,
segment1_0_av.ts
#EXTINF:3.000,
segment2_0_av.ts
#EXTINF:3.000,
segment3_0_av.ts
#EXTINF:3.000,
segment4_0_av.ts
#EXT-X-ENDLIST

And then we can insert the following HLS VOD

#EXTM3U
#EXT-X-TARGETDURATION:3
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:1
#EXTINF:3.000,
ad1_0_av.ts
#EXTINF:3.000,
ad2_0_av.ts
#EXT-X-ENDLIST

At a position 6 seconds from the start and get the following result:

#EXTM3U
#EXT-X-TARGETDURATION:3
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:1
#EXTINF:3.000,
segment1_0_av.ts
#EXTINF:3.000,
segment2_0_av.ts
#EXT-X-DISCONTINUITY
#EXT-X-CUE-OUT:DURATION=6
#EXTINF:3.000,
http://mock.com/ad/ad1_0_av.ts
#EXTINF:3.000,
http://mock.com/ad/ad2_0_av.ts
#EXT-X-DISCONTINUITY
#EXT-X-CUE-IN
#EXTINF:3.000,
segment3_0_av.ts
#EXTINF:3.000,
segment4_0_av.ts
#EXT-X-ENDLIST

The library is published to NPM and to include it in your project add it with yarn or npm:

yarn add @eyevinn/hls-splice

or

npm install — save @eyevinn/hls-splice

More information and example code is available on https://www.npmjs.com/package/@eyevinn/hls-splice

Create a looping HLS VOD from another HLS VOD

Another Javascript library that can modify HLS manifests is the library hls-repeat that can be used to create a slate from an HLS VOD by looping the content. Let’s say you have an HLS VOD with a 3 second slate with moving picture and audio and you want to dynamically create 3, 6 or 9 seconds slates from this. For this use case we developed this library, and what it does can be illustrated by the example below:

#EXTM3U
#EXT-X-TARGETDURATION:3
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:1
#EXTINF:3.000,
segment1_0_av.ts
#EXT-X-ENDLIST

and using this library we repeat this VOD above three times to produce a new VOD that is 9 seconds long.

#EXTM3U
#EXT-X-TARGETDURATION:3
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:1
#EXT-X-DISCONTINUITY
#EXTINF:3.000,
segment1_0_av.ts
#EXT-X-DISCONTINUITY
#EXTINF:3.000,
segment1_0_av.ts
#EXT-X-DISCONTINUITY
#EXTINF:3.000,
segment1_0_av.ts
#EXT-X-ENDLIST

The library is also published to NPM and to include it in your project add it with yarn or npm:

yarn add @eyevinn/hls-repeat

or

npm install — save @eyevinn/hls-repeat

More information and example code is available here: https://www.npmjs.com/package/@eyevinn/hls-repeat

Emulate a Live HLS from VODs

Back in 2018 we developed a proof of concept of a serverless playout and how some of us at Eyevinn envisions that linear TV for OTT services will be produced in a more cloud scalable friendly way. The concept was to just-in-time and dynamically stitch together already transcoded VOD files into a linear (live) TV stream without requiring any additional transcoding. Part of that project we open sourced a reference implementation of this stitcher (engine) and the Javascript library vod-to-live.js which enabled this. A lot of things has happened in this library since then and we recently decided to rebrand it to be called hls-vodtolive to be more in line with the over HLS manifest manipulation libraries we have.

This library loads and parses HLS VOD manifests and slice it up into a set of HLS Live media sequences. By building a service that responds with a new media sequence from this set the video player believes it is a live stream produced by a live encoder / transcoder.

For example:

#EXTINF:9
seg1.ts
#EXTINF:9
seg2.ts
#EXTINF:9
seg3.ts
#EXTINF:9
seg4.ts
#EXT-X-ENDLIST

Will get the following set of media sequences:

#EXT-X-MEDIA-SEQUENCE:1
#EXTINF:9
seg1.ts
#EXTINF:9
seg2.ts
#EXTINF:9
seg3.ts

and

#EXT-X-MEDIA-SEQUENCE:2
#EXTINF:9
seg2.ts
#EXTINF:9
seg3.ts
#EXTINF:9
seg4.ts

And if we would append another HLS VOD

#EXTINF:9
segB1.ts
#EXTINF:9
segB2.ts
#EXTINF:9
segB3.ts
#EXTINF:9
segB4.ts
#EXT-X-ENDLIST

we would get

#EXT-X-MEDIA-SEQUENCE:3
#EXT-X-DISCONTINUITY-SEQUENCE:0
#EXTINF:9
seg2.ts
#EXTINF:9
seg3.ts
#EXTINF:9
seg4.ts
#EXT-X-DISCONTINUITY
#EXTINF:9
segB1.ts

and

#EXT-X-MEDIA-SEQUENCE:4
#EXT-X-DISCONTINUITY-SEQUENCE:0
#EXTINF:9
seg3.ts
#EXTINF:9
seg4.ts
#EXT-X-DISCONTINUITY
#EXTINF:9
segB1.ts
#EXTINF:9
segB2.ts

and finally

#EXT-X-MEDIA-SEQUENCE:6
#EXT-X-DISCONTINUITY-SEQUENCE:1
#EXTINF:9
segB2.ts
#EXTINF:9
segB3.ts
#EXTINF:9
segB4.ts

The library is published to NPM and to include it in your project add it with yarn or npm:

yarn add @eyevinn/hls-vodtolive

or

npm install — save @eyevinn/hls-vodtolive

We would to give a special attribution to OTTera who funded some of the bugfixes and provided help to triage issues. OTTera is a US based company that powers OTT and Linear Video services with over 45 million users worldwide.

More information and example code is available here: https://www.npmjs.com/package/@eyevinn/hls-vodtolive

About Us

This blog was written by an Eyevinn Special Video-Dev Team. Bring in an Eyevinn Special Video-Dev Team when you need a unique combined skillset with the experience from the entire video development domain, to add a feature to your software but lacks the right competence in-house or don’t have enough resources available to do it.

Eyevinn Technology is an independent consultant firm specialized in video and streaming. Independent in a way that we are not commercially tied to any platform or technology vendor.