hls.js with LCEVC

The page outlines the steps needed to integrate the LCEVC decoder modifications to a player based on hls.js. V-Nova provides a reference integration with hls.js which can be referred to as you update your own hls.js player deployment.

Reference integration package

The reference integration packages contains a zip file with the following :

1. js/libs : These are all the files related to the player (hls.js).

2. js/VNova-LCEVC : All DIL.js Libraries need for LCEVC Enhancements. (dil.min.js, liblcevc_dpi.wasm) and patch file based on player to bridge the api calls to the player library(lcevc_dil_patch_hls.js).

3. js/app.js : This is the UI based operations with the demo UI that comes with the package.

4. index.html : Default demo page that showcases the decoding capabilities with LCEVC manifests in HLS and DASH based on the player, and provides a field to specify different stream manifest links for testing.

5. simple.html : The bare minimum integration that handles everything inside the patch.

6. integration.html : This explains a basic integration with a video, canvas and config passed to the dil libraries.

How to integrate LCEVC into an existing hls.js player

Step 1: To integrate LCEVC into an existing hls.js player, you need to include all the scripts under the "demo/js/VNova-LCEVC" folder.

Your HTML page should include the following scripts in the header:

<!-- a version of hls.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.0.4/hls.js"></script>

<!-- vnova lcevc -->
<script type="text/javascript" src="js/VNova-LCEVC/lcevc_dil.min.js"></script>
<script type="text/javascript" src="js/VNova-LCEVC/lcevc_dil_patch_hls.js"></script>

Notes:

• A version of "hls.js" will need to be included. Currently, version 1.0.4 is supported.

• The file "lcevc_dil_patch_hls.js" should be included last, as this needs the other scripts to be loaded first.

• All the VNova-LCEVC scripts must be present in the same folder, including "liblcevc_dpi.wasm".

Or it is also possible to reference these sources hosted in the AWS cloud by V-Nova. These are updated periodically to the latest versions:

<script type="text/javascript" src="https://d3mfda3gpj3dw1.cloudfront.net/LCEVC_HTML/dil.js/lcevc_dil.min.js"></script>
<script type="text/javascript" src="https://d3mfda3gpj3dw1.cloudfront.net/LCEVC_HTML/dil.js/lcevC_dil_patch_hls.js"></script>

Step 2: In the HTML, the code used to load the hls.js player must be modified slightly from its normal usage, to integrate the LCEVC enhancement decoding capabilities, as follows:

Code Changes

To check if hls.js is supported or not:

if (Hls.isSupported()) {
	if (hls) {
		hls.destroy();
		hls = null;
	}
} else {
	console.log('Playback is not supported');
}

To create a new instantiation of hls.js:

hls = new Hls({
	debug:             false,
	enableWorker:      true,
	defaultAudioCodec: null
});

To initialise LCEVC within the hls player:

var canvas = document.createElement('canvas');
var lcevcDilConfig = {
    // optional settings here
};

hls.attachLcevc(canvas, lcevcDilConfig);

The parameters are defined as follows:

canvas

This is an HTMLCanvasElement object and is used to display the rendered frames / output of the video after V-Nova LCEVC has been applied.

Its visibility, and pixel size are both controlled automatically by the player. Please note that the dimensions (in pixels) are set based on the size of the initial video and of the LCEVC-enhanced content being rendered. It is not guaranteed to always be a fixed size and may change dynamically.

The canvas element should mimic the screen size and page position of the video element, via the user’s CSS pixel size, however, this should not be forced, as it is controlled by the player.

The canvas element will be a WebGL canvas, and therefore it is not possible to use any of the HTML5 2D drawing context methods.

lcevcDilConfig

This is an object block containing settings with which V-Nova LCEVC is initialised. It is automatically configured with optimal settings.

Then just attach the video element as normal:

var video = document.getElementById('video');
hls.attachMedia(video);

The video variable is an HTMLVideoElement object and contains the video, exactly as it would for the regular use of hls.js. Once V-Nova LCEVC has been loaded from the header data, this video element is automatically made invisible, using dynamic CSS. A canvas element is then used to display the rendered frames.

Autoplay when loaded:

hls.on(Hls.Events.BUFFER_CREATED, function(event, data) {
	window.setTimeout(function() {
		video.play();
	}, 500);
});

// Integration lines of code.
if(
  lcevcDil &&
  (segment.type === 'video' || segment.type === 'audiovideo')
) {
  lcevcDil.appendBuffer(
    segment.data.buffer,
    segment.type,
    loadLevel,
    timestampOffset,  // Optional
  );
}

LcevcDil.appendBuffer(data, type, level, timestampOffset)

• data: The video buffer data.

• type: The type of the data, can be 'video', 'audio' or 'audiovideo'.

• level: The current ABR profile/rendition/level ID of the data.

• timestampOffset (optional): The offset that needs to be applied to all timestamps in the buffer.