Skip to content

unshackle

unshackle is a modular archival tool for movies, TV, and music. It fetches media from streaming manifests, handles the DRM, and muxes everything into clean, well-tagged files, all driven from a single command-line tool, or served over a REST API for automation.

It is a fork of Devine with DASH, HLS, and Smooth Streaming (ISM) parsing, both Widevine and PlayReady DRM, and a built-in HTTP server.

Use responsibly

The GPL-3.0 licence covers unshackle. Do not use it for content you do not have the rights to. Keep the core free and open, keep your own services private, and be kind.

What it does

unshackle does everything except talk to the streaming platform. You write that part as a service module (Creating a Service). Point unshackle at a title and it will:

  • Fetch the title metadata (movies, full series, seasons, episodes, albums, tracks).
  • Parse the streaming manifest: DASH, HLS, or Smooth Streaming (ISM).
  • Select the tracks you asked for by resolution, codec, bitrate, range, language, and channel layout.
  • Get the content keys through a Widevine or PlayReady CDM, with optional key vaults that let unshackle reuse a content key instead of licensing it again.
  • Decrypt, extract closed captions, repack, and mux the result into a Matroska (.mkv) file with correct language, forced, and default flags.
  • Tag and name the output using configurable filename templates.

Feature highlights

Area What you get
Media types Movies, TV series/seasons/episodes, and music albums/tracks
Manifests DASH, HLS, and Smooth Streaming (ISM)
DRM Widevine and PlayReady, with ClearKey support
Video AVC, HEVC, VC-1, VP8, VP9, AV1; SDR, HLG, HDR10, HDR10+, Dolby Vision, and Dolby Vision hybrid merging
Audio AAC, AC-3, E-AC-3, AC-4, Opus, Vorbis, DTS, DTS-X, ALAC, FLAC; Dolby Atmos handling; per-channel-layout selection
Subtitles SRT, WebVTT, ASS/SSA, TTML and more, with optional SDH stripping and format conversion
Key vaults SQLite, MySQL, and HTTP/API vaults to store and share content keys
Proxies Basic proxies plus Control D, NordVPN, ProtonVPN, Surfshark, Windscribe, ExpressVPN, Gluetun, and Hola providers
Services A plugin API for the service modules you write. unshackle includes none
Automation A REST API with a job queue, live progress, history, and remote-download sessions

Installation at a glance

uv tool install git+https://github.com/unshackle-dl/unshackle.git
unshackle --help

git clone https://github.com/unshackle-dl/unshackle.git
cd unshackle
uv run unshackle --help

External tools

unshackle shells out to FFmpeg, MKVToolNix, shaka-packager, Bento4, and dovi_tool for decryption, repacking, muxing, and Dolby Vision work. See Installation for the full list and recommended versions.

A first download

Every download is three parts: the dl command, a service tag, and the service's title argument (a URL, ID, or slug).

Download a 1080p title with English audio
unshackle dl -q 1080 -l en EXAMPLE 81234567

The dl command carries all the quality, language, and output flags. The service tag (EXAMPLE above) selects which streaming service to talk to, and unshackle passes the value after it to that service. See the Quickstart to go from a fresh install to your first file.

Where to go next

  • Installation. Install unshackle and the external tools it depends on.
  • Quickstart. Configure unshackle.yaml and do your first download.
  • Downloading. The full dl command guide: quality, codecs, languages, track selection, and output.
  • Configuration. Where unshackle.yaml lives, the directory layout, and how to edit values. Full config key list in the Configuration Reference.
  • REST API. Operate the serve HTTP server and drive downloads programmatically.

Getting help

Operate unshackle --help or unshackle dl --help at any time. The community Discord is the fastest place to ask questions.