Documentation | HLSDownloader

Downloads HLS Playlist file and TS chunks. You can use it for content pre-fetching from CDN to Edge Server for your end viewers.

NPM • Documentation • GitHub

⚠️ This package is native ESM and no longer provides a CommonJS export. If your project uses CommonJS, you will have to convert to ESM. Please don't open issues for questions regarding CommonJS / ESM.

⚠️ HLSDownloader v2.x.x is no longer maintained and we will not accept any backport requests.

Features

Retryable
Promise Based
Support for HTTP/2
Overwrite protection
Support for custom HTTP Headers
Support for custom HTTP Client
Bring your own progress bar during download
Concurrent download segments with multiple http connections

Prerequisites

node >=20.x.x

Installation

It is pretty straight forward

# using npm
npm install --save hlsdownloader
# or with yarn
yarn add hlsdownloader
# or pnpm
pnpm install hlsdownloader

How to use

The destination field is optional. If a destination is not specified, the content is retrieved directly from the origin. This functionality may also be used to pre-fetch content from the CDN for end viewers. If the download of any TS or M3U8 variant fails, the process continues with the remaining downloads and provides a consolidated report upon completion.

It's simple as below with.

import HLSDownloader from 'hlsdownloader';

const options = {
  playlistURL: 'http://example.com/path/to/your/playlist.m3u8', // change it
  destination: '/tmp', // (optional: default '')
  concurrency: 10, // (optional: default = 1),
  overwrite: true, // (optional: default = false)
  // (optional: default = null)
  onData: function (data) {
    console.log(data); // {url: "<url-just-downloaded>", totalItems: "<total-items-to-download>", path: "<absolute-path-of-download-loation>"}
  },
  // (optional: default = null)
  onError: function (error) {
    console.log(error); // { url: "<URLofItem>", name: "<nameOfError>", message: "human readable message of error" }
  },
  // you can pass supported ky options (optional) (see example.js)
};
const downloader = new HLSDownloader(options);
downloader.startDownload().then(response => console.log(response));

ℹ️ Check example.js for working example

// on success
{
  total: <number>,
  playlistURL: 'your playlist url'
  message: 'Downloaded successfully',
}

// on partial download
{
  total: <number>,
  playlistURL: 'your playlist url',
  message: 'Download done with some errors',
  errors: [
    {
      name: 'InvalidPlaylist',
      message: 'Playlist parsing is not successful'
      url: 'https://cnd.hls-server.test/playlist.m3u8'
    }
  ] // items url that is skipped or could not downloaded for error
}

Advance Usage

HLSDownloader supports all Ky API except these options given below

uri
url
json
form
body
method
setHost
isStream
parseJson
prefixUrl
cookieJar
playlistURL
concurrency
allowGetBody
stringifyJson
methodRewriting

It also disable retry failed request that you can easily override

Running Tests

npm test

To run it on watch mode

npm run test:watch

Generate Documentations

npm docs:gen

Authors

👤 Nur Rony

Website: nurrony.github.io
Twitter: @nmrony
Github: @nurrony
LinkedIn: @nmrony

Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page. You can also take a look at the contributing guide.

Show your support

Give a ⭐️ if this project helped you!. I will be grateful if you all help me to improve this package by giving your suggestions, feature request and pull requests. I am all ears!!

Special Thanks to

Ky Team

HLSDownloader