vsd

Video Stream Downloader is a powerful command-line utility that enables users to download video content streamed over HTTP from websites. It supports both DASH (Dynamic Adaptive Streaming over HTTP) using .mpd manifest files and HLS (HTTP Live Streaming) using .m3u8 playlists. The tool is designed to handle adaptive bitrate streams, fetch individual video and audio segments, and optionally mux them into a single playable file, making it ideal for offline viewing, archival, or analysis of online video content.

Table of Contents

• Features
• Installation
  • Dependencies
  • Pre-built Binaries
  • Install via Cargo
  • Additional Resources
• Usage
• Help
• Running on Android
• Alternatives
• License

Features

• Captures network requests and lists playlist and subtitle files from websites.
• Compatible with both DASH and HLS playlists.
• Enables multi-threaded downloading for faster performance.
• Muxing streams to single video container using ffmpeg.
• Offers robust automation support.
• One unified progress bar tracking the entire download, with real-time file size updates.
• Supports decryption for AES-128, SAMPLE-AES, CENC, CBCS, CENS and CBC1.
• Live stream downloading (not currently planned).

See More

Installation

Dependencies

• ffmpeg (optional, recommended) required for transmuxing and transcoding streams.
• chrome / chromium (optional) needed only for the capture sub-command.

Pre-built Binaries

Visit the releases page for pre-built binaries or grab the latest CI builds. Download and extract the archive, then copy the vsd binary to a directory of your choice. Finally, add that directory to your system's PATH environment variable.

Install via Cargo

You can also install vsd using cargo.

$ cargo install vsd

Additional Resources

• Build Instructions
• Changelog

Usage

• Capture playlists and subtitles from a website.

$ vsd capture <url> --save-cookies

The saved cookies can be used as --cookies cookies.json with save sub-command later on.

• Download playlists. (test streams)

$ vsd save <url> -o video.mp4

Use -i, --interactive flag to open an interactive session.

• Download encrypted playlists. (drm test vectors)

$ vsd save https://bitmovin-a.akamaihd.net/content/art-of-motion_drm/mpds/11331.mpd \
    --keys "eb676abbcb345e96bbcf616630f1a3da:100b6c20940f779a4589152b57d2dacb" \
    -o video.mp4

• List and select specific streams from a playlist.

$ vsd save <url> --list-streams
$ vsd save <url> --select-streams "v=1,2:a=3" -o video.mp4

• Prefer some specific languages when downloading audio/subtitles.

$ vsd save <url> --select-streams "a=en,fr:s=en,fr" -o video.mp4

• Use as a playlist parser. (json schema)

$ vsd save <url> --parse > parsed-playlist.json

Help

$ vsd --help

Download video streams served over HTTP from websites, DASH (.mpd) and HLS (.m3u8) playlists.

Usage: vsd [OPTIONS] <COMMAND>

Commands:
  capture  Capture playlists and subtitles from a website
  extract  Extract subtitles from mp4 boxes
  merge    Merge multiple segments to a single file
  save     Download DASH and HLS playlists
  help     Print this message or the help of the given subcommand(s)

Options:
      --color <COLOR>  When to output colored text [default: auto] [possible values: auto, always, never]
  -h, --help           Print help
  -V, --version        Print version

$ vsd save --help

Download DASH and HLS playlists

Usage: vsd save [OPTIONS] <INPUT>

Arguments:
  <INPUT>
          http(s):// | .mpd | .xml | .m3u8

Options:
      --base-url <BASE_URL>
          Base url to be used for building absolute url to segment. This flag is usually needed for local input files. By default redirected
          playlist url is used

  -d, --directory <DIRECTORY>
          Change directory path for temporarily downloaded files. By default current working directory is used

  -o, --output <OUTPUT>
          Mux all downloaded streams to a video container (.mp4, .mkv, etc.) using ffmpeg. Note that existing files will be overwritten and
          downloaded streams will be deleted

      --parse
          Parse playlist and returns it in json format. Note that --output flag is ignored when this flag is used

      --color <COLOR>
          When to output colored text
          
          [default: auto]
          [possible values: auto, always, never]

      --subs-codec <SUBS_CODEC>
          Force some specific subtitle codec when muxing through ffmpeg. By default `mov_text` is used for .mp4 and `copy` for others
          
          [default: copy]

  -h, --help
          Print help (see a summary with '-h')

Automation Options:
  -i, --interactive
          Prompt for custom streams selection with modern style input prompts. By default proceed with defaults

      --interactive-raw
          Prompt for custom streams selection with raw style input prompts. By default proceed with defaults

  -l, --list-streams
          List all the streams present inside the playlist

  -s, --select-streams <SELECT_STREAMS>
          Filters to be applied for automatic stream selection.
          
          SYNTAX: `v={}:a={}:s={}` where `{}` (in priority order) can contain
          |> all: select all streams.
          |> skip: skip all streams or select inverter.
          |> 1,2: ids obtained by --list-streams flag.
          |> 1080p,1280x720: stream resolution.
          |> en,fr: stream language.
          
          EXAMPLES:
          |> v=skip:a=skip:s=all (download all sub streams)
          |> a:en:s=en (prefer en lang)
          |> v=1080p:a=all:s=skip (1080p with all audio streams)
          
          [default: v=best:s=en]

Client Options:
      --cookies <COOKIES>
          Fill request client with some existing cookies value. Cookies value can be same as document.cookie or in json format same as puppeteer

      --header <KEY> <VALUE>
          Custom headers for requests. This option can be used multiple times

      --no-certificate-checks
          Skip checking and validation of site certificates

      --proxy <PROXY>
          Set http(s) / socks proxy address for requests

      --query <QUERY>
          Set query parameters for requests

      --set-cookie <SET_COOKIE> <URL>
          Fill request client with some existing cookies per domain. First value for this option is set-cookie header and second value is url
          which was requested to send this set-cookie header. EXAMPLE: --set-cookie "foo=bar; Domain=yolo.local" https://yolo.local. This option
          can be used multiple times

      --user-agent <USER_AGENT>
          Update and set user agent header for requests
          
          [default: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36"]

Decrypt Options:
      --keys <KID:KEY;...>
          Keys for decrypting encrypted streams. KID:KEY should be specified in hex format

      --no-decrypt
          Download encrypted streams without decrypting them. Note that --output flag is ignored if this flag is used

Download Options:
      --retries <RETRIES>
          Maximum number of retries to download an individual segment
          
          [default: 15]

      --no-merge
          Download streams without merging them. Note that --output flag is ignored if this flag is used

  -t, --threads <THREADS>
          Total number of threads for parllel downloading of segments. Number of threads should be in range 1-16 (inclusive)
          
          [default: 5]

Running on Android

1. Install the Termux app on your device, then enable storage permissions manually from its settings page. After that, run the following commands in the terminal.

$ pkg update
$ pkg upgrade
$ pkg install ffmpeg
$ ln -s /storage/emulated/0/Download Download

2. Install vsd on termux. Currently, only arm64-v8a binaries pre-builts are available which can be installed using the following command.

curl -L https://github.com/clitic/vsd/releases/download/vsd-0.4.3/vsd-0.4.3-aarch64-linux-android.tar.xz | tar xJC $PREFIX/bin

3. Use third party browsers like Kiwi Browser (developer tools) paired with Get cookies.txt LOCALLY extension or Via Browser (tools > resource sniffer) to find playlists within websites.

4. Now you can run vsd as usual. The streams would be directly downloaded in your android downloads folder.

$ cd Download
$ vsd save <url> -o video.mp4

Alternatives

List of alternatives to vsd:

1. N_m3u8DL-RE is the best alternative to vsd. It also supports live playlists, which vsd does not. However, it lacks features like capture functionality.
2. yt-dlp is excellent for downloading various playlists, but its main drawback is limited support for decryption.
3. dash-mpd-cli is a highly effective tool for downloading DASH playlists. In fact, much of vsd’s internal logic for parsing and downloading DASH content is based on this tool.
4. ffmpeg supports direct encoding of playlists.
5. Both streamlink and vlc allow direct streaming of playlists.

License

Dual Licensed

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)