HLS Downloader

Command-line utility for downloading an offline copy of an HLS video stream.

Installation:

npm install --global @warren-bank/node-hls-downloader

Features:

• interactive command-line interface (CLI)
  • prompts for URL of the master manifest
    • when not given as a CLI option
  • prompts for video resolution
    • when multiple video streams are available in the master manifest
    • when not filtered by a CLI option
  • prompts for audio stream
    • when multiple are available in the group ID associated with the chosen video stream
    • when not filtered by a CLI option
  • prompts for subtitles stream
    • when multiple are available in the group ID associated with the chosen video stream
    • when not filtered by a CLI option
• resulting file structure:

    |- video/
    |  |- *.ts
    |- audio/
    |  |- {language}/
    |  |  |- *.ts
    |  |- {language}.m3u8
    |- subtitles/
    |  |- {language}/
    |  |  |- *.vtt
    |  |- {language}.m3u8
    |- video.m3u8
    |- master.m3u8

Limitations:

• only works with static (ie: not live stream) playlists,which include a complete list of all:
  • video segments
  • audio segments
  • subtitle segments
  • encryption keys

Usage:

hlsdl <options>

options:
========
"-h"
"--help"
    Print a help message describing all command-line options.

"-V"
"--version"
    Display the version.

"-u" <URL>
"--url" <URL>
    Specify the URL of master manifest.

"-ncc"
"--no-check-certificate"
    Do not check HTTPS TLS/SSL certificates.

"-nc"
"--no-clobber"
    Do not allow output to overwrite existing data.
    Run an initial check before any downloading occurs, and exit with a warning if a collision is detected.

"-c"
"--continue"
   Do not reinitialize output directories (ie: recursively delete).
   Rather, reuse the existing directories and leave file contents unaltered.
   Run a check before each download, and skip if the data file already exists in the output directory.

"-mc" <integer>
"--max-concurrency" <integer>
"--threads" <integer>
    Specify the maximum number of URLs to download in parallel.
    The default is 1, which processes the download queue sequentially.

"-P" <dirpath>
"--directory-prefix" <dirpath>
    Specifies the directory where the resulting file structure will be saved to.
    The default is "." (the current directory).

"-sv"
"--skip-video"
    Skip processing of the video manifest.
    Do not download video data segments, or save a local video manifest.

"-sa"
"--skip-audio"
    Skip processing of all matching audio manifests.
    Do not download audio data segments, or save local audio manifest(s).

"-ss"
"--skip-subtitles"
    Skip processing of all matching subtitles manifests.
    Do not download subtitles data segments, or save local subtitles manifest(s).

"-minb" <integer>
"--min-bandwidth" <integer>
    Exclude video streams having a bandwidth less than this value.

"-maxb" <integer>
"--max-bandwidth" <integer>
    Exclude video streams having a bandwidth greater than this value.

"-hq"
"--highest-quality"
    Download the highest quality video stream without any user interaction.
    Does not include video streams filtered by min/max bandwidth restrictions.

"-lq"
"--lowest-quality"
    Download the lowest quality video stream without any user interaction.
    Does not include video streams filtered by min/max bandwidth restrictions.

"-aa"
"--all-audio"
    Download all audio streams in the group ID associated with the chosen video stream.

"-as"
"--all-subtitles"
    Download all subtitle streams in the group ID associated with the chosen video stream.

"-fa" <regex>
"--filter-audio" <regex>
    Download all audio streams in the group ID associated with the chosen video stream,
    having a name that matches this case-insensitive regular expression pattern.

"-fs" <regex>
"--filter-subtitles" <regex>
    Download all subtitle streams in the group ID associated with the chosen video stream,
    having a name that matches this case-insensitive regular expression pattern.

"--mp4" <filepath>
    Indicates that "ffmpeg" should be used to bundle the downloaded video stream into an .mp4 file container.
    Specifies where the resulting .mp4 file will be saved.
    Does not modify audio/video encoding.
    Each subtitles stream is converted to an .srt file, and saved in the same directory as the .mp4 file.

"--mp4-ffmpeg-options" <options>
    Any additional options that should be passed to "ffmpeg" when used to bundle an .mp4 file container.

Example:

• this test script is a good introduction

Requirements:

• Node.js version: v8.6.0 (and higher)
  • transitive dependency requirements:
    • v8.06.00+: @warren-bank/node-process-argv
    • v8.06.00+: @warren-bank/node-request-cli
• FFmpeg
  • only required in PATH when using the --mp4 CLI option
    • successfully tested with version: 4.1.3

Legal:

• copyright: Warren Bank
• license: GPL-2.0