# @warren-bank/node-hls-downloader

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

Latest version **4.0.8** (published 2023-05-28) · GPL-2.0 license · 0 weekly downloads

## Install

```sh
npm install @warren-bank/node-hls-downloader
pnpm add @warren-bank/node-hls-downloader
yarn add @warren-bank/node-hls-downloader
bun add @warren-bank/node-hls-downloader
```

Provides the command `hlsdl`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.8 |
| Published | 2023-05-28 |
| First published | 2019-06-21 |
| Weekly downloads | 0 |
| License | GPL-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 53.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 24 |
| Author | Warren R. Bank |
| Maintainers | warren-bank |

## Links

- npm: https://www.npmjs.com/package/@warren-bank/node-hls-downloader
- Repository: https://github.com/warren-bank/node-hls-downloader
- Homepage: https://github.com/warren-bank/node-hls-downloader#readme
- Issues: https://github.com/warren-bank/node-hls-downloader/issues
- npm.io page: https://npm.io/package/@warren-bank/node-hls-downloader

## Dependencies (2)

- [@warren-bank/node-request-cli](https://npm.io/package/@warren-bank/node-request-cli.md) ^3.2.0
- [@warren-bank/node-process-argv](https://npm.io/package/@warren-bank/node-process-argv.md) ^1.1.0

## Recent versions

- 4.0.8 (latest) — 2023-05-28
- 4.0.7 — 2023-05-25
- 4.0.6 — 2023-03-02
- 4.0.5 — 2021-01-02
- 4.0.4 — 2020-02-15
- 4.0.3 — 2020-02-12
- 4.0.2 — 2020-02-10
- 4.0.0 — 2019-07-03
- 3.0.1 — 2019-07-01
- 3.0.0 — 2019-07-01
- 2.0.0 — 2019-07-01
- 1.0.2 — 2019-06-21
- 1.0.1 — 2019-06-21
- 1.0.0 — 2019-06-21

## README

### [HLS Downloader](https://github.com/warren-bank/node-hls-downloader)

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

#### Installation:

```bash
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:
  ```bash
    |- 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,<br>which include a complete list of all:
  * video segments
  * audio segments
  * subtitle segments
  * encryption keys

#### Usage:

```bash
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](https://github.com/warren-bank/node-hls-downloader/blob/master/tests/run.sh) is a good introduction

- - - -

#### Requirements:

* Node.js version: v8.6.0 (and higher)
  - transitive [dependency](https://github.com/warren-bank/node-hls-downloader/blob/master/package.json#L11-L12) requirements:
    * v8.06.00+: [`@warren-bank/node-process-argv`](https://github.com/warren-bank/node-process-argv#requirements)
    * v8.06.00+: [`@warren-bank/node-request-cli`](https://github.com/warren-bank/node-request-cli#requirements)
* FFmpeg
  * only required in `PATH` when using the `--mp4` CLI option
    * successfully tested with version: 4.1.3

#### Legal:

* copyright: [Warren Bank](https://github.com/warren-bank)
* license: [GPL-2.0](https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt)

---
_Source: https://npm.io/package/@warren-bank/node-hls-downloader · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._