hlx-file-reader

A readable stream that reads an HLS stream and populates hls-parser objects

Features

• Provides a readable stream that can be used for extracting particular variants/renditions from a running live/VOD HLS stream
  • Downloads and parses HLS playlists based on the spec.
  • Provides a hook for the client to choose which variant(s) and rendition(s) to be downloaded.
  • Populates playlists and segments as structured JS objects ( hls-parser objects) that can be read via event listeners

Install

Usage

const {createReadStream} = require('hlx-file-reader');
// Create a readable stream from a URL
const stream = createReadStream('https://foo.com/bar.m3u8');
// a hook for filtering variants (optional)
stream.on('variants', (variants, cb) => {
  // Choose variants to download (default: all)
  const variantsToLoad = [];
  for (let [index, variant] of variants.entries()) {
    if (variant.bandwidth >= MIN_BITRATE) {
      variantsToLoad.push(index);
    }
  }
  return cb(variantsToLoad);
})
// a hook for filtering renditions (optional)
.on('renditions', (renditions, cb) => {
  // Choose renditions to download (default: all)
  const renditionsToLoad = [];
  for (let [index, rendition] of renditions.entries()) {
    if (rendition.type === 'AUDIO') {
      renditionsToLoad.push(index);
    }
  }
  return cb(renditionsToLoad);
})
.on('data', data => {
  // `data` is an hls-parser object
  // For the details of the object structure, see the hls-parser's document
  if (data.type === 'playlist') {
    console.log(`${data.isMasterPlaylist ? 'Master' : 'Media'} playlist`);
  } else if (data.type === 'segment') {
    console.log(`#${data.mediaSequenceNumber}: duration = ${data.duration}, byte length = ${data.data.length}`);
  }
})
.on('end', () => {
  // For VOD streams, the stream ends after all data is consumed.
  // For Live streams, the stream continues until the ENDLIST tag.
  console.log('Done');
})
.on('error', err => {
  console.error(err.stack);
});
 
// To emit 'variants' and 'renditions' events again
stream.updateVariant();

API

The features are built on top of the Node's readable streams.

createReadStream(location[, options])

Creates a new ReadStream object.

params

Name	Type	Required	Default	Description
location	string	Yes	N/A	A url of the playlist
options	object	No	{}	See below

options

Name	Type	Default	Description
concurrency	number	6	Max number of requests concurrently processed
rootPath	string	"/"	Required if the location is a file url and any root relative URLs (starting with '/') are contained in the playlist
rawResponse	boolean	false	If true, the segment file (Segment.data) is read as a readable stream, default is as a Buffer
playlistOnly	boolean	false	If true, the segment file are not loaded and only playlists are loaded

return value

An instance of ReadStream.

ReadStream

A subclass of stream.Readable with additional events and methods as follows.

events

'variants'

variants event is emitted to let clients choose which variants to be passed to the subsequent streams. Listen for this event if you want to perform any filtering otherwise every variants will be passed to the subsequent streams. The event listener is called synchronously with the following arguments:

Name	Type	Description
variants	[Variant]	A list of available variants
cb	function	A callback function used by clients to choose which variants to be loaded. cb takes a single argument of type [number], an array contains the indices of variants to be loaded. The filtering won't happen unless you call this function.

'renditions'

renditions event is emitted to let clients choose which renditions to be passed to the subsequent streams. Listen for this event if you want to perform any filtering otherwise every renditions will be passed to the subsequent streams. The event listener is called synchronously with the following arguments:

Name	Type	Description
renditions	[Rendition]	A list of available renditions
cb	function	A callback function used by clients to choose which renditions to be loaded. cb takes a single argument of type [number], an array contains the indices of renditions to be loaded. The filtering won't happen unless you call this function.

'data'

data event is emitted for each playlist and segment. The event listener is called with the following arguments:

Name	Type	Description
data	Data	An hls-parser data object (An instance of Segment/MasterPlaylist/MediaPlaylist)

methods

updateVariant()

Emits variants/renditions events again so that the client can choose another set of variants/renditions, which in turn emits data events. The method takes no params and returns no value.