How to build a seamless transition between HLS streams with videoJS

18 May 20

By Cristiano Almeida in CookiesHQ, Development, Projects

We have recently released Stornaway into the world, a tool that enables filmmakers and creators to plan, produce and publish interactive films with non-linear narratives.

Streaming non-linear stories on the web comes with its own challenges when providing a good experience to the user. One key challenge is keeping the video playing without delays as the viewer interacts with it.

Generally, a video is comprised of one single clip and it loads as it plays (mostly) without interruptions from beginning to end, excluding scenarios where the connection is slow or intermittent.

Looking for expert guidance or developers to work on your project? We love working on existing codebases – let’s chat.

However, in Stornaway, the whole story is broken down into small clips as users interact with the storyline. This design means that clips that match the viewer’s decisions play as the story progresses. There is a danger that when switching from one clip to the other the video will briefly fall into a loading state which breaks the immersion for the viewer.

In order to remove this loading time, two players were introduced. One plays the current clip and another is hidden underneath. When the next clip to play is known (either a user has made a choice or a default is going to play), the hidden player is set with the next clip ahead of time before the current one finishes.

When the current playing clip ends, the player visibility is tagged. The one that was visible is hidden and the one that was hidden is revealed and plays immediately, creating the illusion of a seamless transition.

In the early stages of the player, we looked at other approaches such as manipulating the HLS stream to include new chunks. However, we found the overlapping players approach easier to implement and maintain.

How to implement a seamless transition

Now we’ll walk through the implementation on achieving a seamless transition between two clips, using two players. In this guide we will:

Instantiate two videoJS players (overlapped)
Add logic to toggle them
Run logic on an event, in this case, a click

In the end, a seamless transition between the two clips will be possible, the result is demonstrated in this CodePen:

<br /> See the Pen <a href="https://codepen.io/csalmeida/pen/ZEbxzeq">VideoJS HLS Transition</a> by Cristiano<br /> (<a href="https://codepen.io/csalmeida">@csalmeida</a>) on <a href="https://codepen.io">CodePen</a>.<br />

The first step is to setup videoJS. I recommend following the getting started guide but I’ll add a few steps here such as importing its style sheet and library, the styles link tag is added to the head of the document:

<link href="https://vjs.zencdn.net/7.7.6/video-js.css" rel="stylesheet" />

Importing the script depends on the project and how dependencies are being managed, in a lot of cases adding this script tag before the ending body tag will work:

<script src="https://vjs.zencdn.net/7.7.6/video.js"></script>
<!-- Our script goes under the videoJS tag. -->
<script src="script.js"></script>
</body>

Next, we’ll add two players and place them on top of one another. The template language used here is HAML:

%div.player
  %video#js-video-horsa.js-video.js-video.video-js.vjs-big-play-centered{ width: 1024, height: 720, controls: '', playsinline: true}
  %video#js-video-hengest.js-video-hidden.js-video.js-video.video-js.vjs-big-play-centered{ width: 1024, height: 720, playsinline: true, controls: '' }
%div.content
  %button#transition-toggle transition to another video

For convenience, here’s the markup in HTML:

<div class="player">
  <video id="js-video-horsa" class="js-video js-video video-js vjs-big-play-centered" width="1024px" height="720px" controls playsinline></video>
  <video id="js-video-hengest" class="js-video js-video video-js vjs-big-play-centered" width="1024px" height="720px" controls playsinline></video>
</div>

In the markup, a few videoJS specific classes were added, as well a unique id for each player, #js-video-horsa, #js-video-hengest and a .js-video-hidden class on one of them. These IDs and class are going to be used later to control the players programmatically.

At this point, two players should show on the page with a play button in the middle. Here’s how the button should look like, the styles are taken from the videoJS base stylesheet imported earlier:

Next, we’ll add styles to make sure one player is hidden under the other:

.player {
  // Used to center the players on the page but not essential.
  display: flex;
  justify-content: center;
  
  // Allows players to be absolute positioned.  
  position: relative;
}

.video-js {
  // Causes players to overlap.
  position: absolute;
}

// Keeps hidden player at the back.
.js-video-hidden {
  z-index: -1;
}

At this point only one player can be seen on the page:

Now that the players are ready, we’ll add a button element to trigger the transition to another video, again snippets are provided in HAML and HTML:

%div.content
  %button#transition-toggle transition to another video

<div class="content">
  <button id="transition-toggle">transition to another video</button>
</div>

A few styles can be added to the button container to make sure the content section is not hidden under the player:

.content {
  display: flex;
  justify-content: center;
  position: relative;
}

Next, we’ll instantiate the players and add HLS streams to them in a script. Create a script.js file (make sure the path on the script tag is the same as where this file is located in your project). In the file we’ll add the following:

// Player options on instantiation.
const options = {
  autoSetup: false,
  muted: true,
  preload: 'metadata',
  autoplay: false,
  loadingSpinner: true,
  html5: {
    nativeControlsForTouch: false,
    nativeAudioTracks: false,
    nativeVideoTracks: false,
    hls: {
      limitRenditionByPlayerDimensions: false,
      smoothQualityChange: true,
      bandwidth: 6194304,
      overrideNative: true
    }
  }
}

// Instantiating two players.
const horsa = videojs('#js-video-horsa', options)
const hengest = videojs('#js-video-hengest', options)

// HLS Streams, one for each player.
const stream_one = "https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8"
const stream_two = "https://bitdash-a.akamaihd.net/content/MI201109210084_1/m3u8s/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.m3u8"

// Assigning a stream to each one of them.
horsa.src({ src: stream_one, type: 'application/x-mpegURL' })
hengest.src({ src: stream_two, type: 'application/x-mpegURL' })

In the snippet above, a videoJS options object defined this is an optional step, but in this case, it is used to configure a few aspects of both players.

Next, two players are instantiated. This is where the IDs set on each video tag are used, the options object can also be passed in at this point.

On subsequent lines, two HLS streams are set as the source of the player, one for each so we can see the transition clearly. The codec for the stream is application/x-mpegURL but it will differ if another type of media is being used.

Next, we’ll add the functionality to trigger a transition, wrapping it in a function:

// Toggle both players visibility to apply a transition, revealing the hidden one and removing the current visible one from view.
const applyTransition = () => {
  // Gets all instances of players.
  const allPlayers = videojs.getAllPlayers()

  // For each player:
  // 1. Reveals if hidden, hides if visible.
  // 2. Plays if revealed, pauses if hidden.
  allPlayers.map((player) => {
    player.el().classList.toggle('js-video-hidden')
    const isHidden = player.el().classList.contains('js-video-hidden')
    
    if (player.paused() && !isHidden) {
      player.play()
    } else {
      player.pause()
    }
  })
}

In this function, we use the videoJS API to get all player instances which will allow us to iterate through them and perform a couple of actions in each one of them.

For each player, the hidden class is toggled. When the function runs the visible player will be hidden and the hidden one will be revealed:

player.el().classList.toggle('js-video-hidden')

Next, we’ll get a reference on whether the player in the current iteration is hidden or visible to understand to pause it when hidden:

const isHidden = player.el().classList.contains('js-video-hidden')

The last step on the iteration is to play the video for the revealed player and pause it on the hidden one:

if (player.paused() && !isHidden) {
  player.play()
} else {
  player.pause()
}

As a final step, the function will be run when the #transition-toggle button is clicked, which will trigger a transition. This is not a requirement and it could run on other conditions or events (for example when the video ends or when the current visible player video progresses to a certain point) but in this case, we’ll implement a click:

// Getting a reference of the transition button.
const transitionButton = document.querySelector('#transition-toggle')

// Each time the button is clicked the transition is applied.
transitionButton.addEventListener('click', () => {
  applyTransition();
})

In the snippet above we get a reference of the button defined earlier in the HAML/HTML markup add an event listener that will trigger a transition each time the button is clicked.

To recap here’s the complete snippets:

<!-- HAML -->
%div.player
  %video#js-video-horsa.js-video.js-video.video-js.vjs-big-play-centered.col-12{ width: 1024, height: 720, controls: '', playsinline: true}
  %video#js-video-hengest.js-video-hidden.js-video.js-video.video-js.vjs-big-play-centered.col-12{ width: 1024, height: 720, playsinline: true, controls: '' }
%div.content
  %button#transition-toggle transition to another video

<!-- Same markup in HTML -->
<div class="player">
  <video id="js-video-horsa" class="js-video js-video video-js vjs-big-play-centered" width="1024px" height="720px" controls playsinline></video>
  <video id="js-video-hengest" class="js-video js-video video-js vjs-big-play-centered" width="1024px" height="720px" controls playsinline></video>
</div>
<div class="content">
  <button id="transition-toggle">transition to another video</button>
</div>

/* CSS */
.player {
  display: flex;
  justify-content: center;
  position: relative;
}

.content {
  display: flex;
  justify-content: center;
  position: relative;
}

.video-js {
  position: absolute;
}

.js-video-hidden {
  z-index: -1;
}

// JavaScript

// Player options on instantiation.
const options = {
  autoSetup: false,
  muted: true,
  preload: 'metadata',
  autoplay: false,
  loadingSpinner: true,
  html5: {
    nativeControlsForTouch: false,
    nativeAudioTracks: false,
    nativeVideoTracks: false,
    hls: {
      limitRenditionByPlayerDimensions: false,
      smoothQualityChange: true,
      bandwidth: 6194304,
      overrideNative: true
    }
  }
}

// HLS Streams, one for each player.
const stream_one = "https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8"
const stream_two = "https://bitdash-a.akamaihd.net/content/MI201109210084_1/m3u8s/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.m3u8"

// Instantiating two players.
const horsa = videojs('#js-video-horsa', options)
const hengest = videojs('#js-video-hengest', options)

// Assigning a stream to each one of them.
horsa.src({ src: stream_one, type: 'application/x-mpegURL' })
hengest.src({ src: stream_two, type: 'application/x-mpegURL' })

// Toggle both players visibility to apply a transition, revealing the hidden one and removing the current visible one from view.
const applyTransition = () => {
  // Gets all instances of players.
  const allPlayers = videojs.getAllPlayers()

  // For each player:
  // 1. Reveals if hidden, hides if visible.
  // 2. Plays if revealed, pauses if hidden.
  allPlayers.map((player) => {
    player.el().classList.toggle('js-video-hidden')
    const isHidden = player.el().classList.contains('js-video-hidden')
    
    if (player.paused() && !isHidden) {
      player.play()
    } else {
      player.pause()
    }
  })
}

// Getting a reference of the transition button.
const transitionButton = document.querySelector('#transition-toggle')

// Each time the button is clicked the transition is applied.
transitionButton.addEventListener('click', () => {
  applyTransition();
})

All put together it results in the following prototype:

Discover more about Stornaway by seeing the interactive film the CookiesHQ team made here.

Cristiano Almeida

Web Developer

Capoeirista, inspired by tech and design. Guitar and bass player.

How to implement a seamless transition

Cristiano Almeida

It all starts with a chat