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 first-class DASH, HLS, and Smooth Streaming (ISM) parsing, both Widevine and PlayReady DRM support, and a built-in HTTP server.

!!! warning "Use responsibly" unshackle is licensed under GPL-3.0. Do not use it for content you do not have the rights to. Keep the core free and open, keep service code private, and be kind.

What it does

Point unshackle at a title on a streaming service 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.
Acquire decryption keys via a Widevine or PlayReady CDM, with optional key vaults so keys are reused instead of re-licensed.
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, 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 NordVPN, ProtonVPN, Surfshark, Windscribe, ExpressVPN, Gluetun, and Hola providers
Services	Pluggable service modules, loadable from local folders or git repositories
Automation	A REST API with a job queue, live progress, history, and remote-download sessions

Installation at a glance

=== "Install as a tool"

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

=== "Run from a clone"

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

!!! note "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).

unshackle dl -q 1080 -l en NF 81234567

The dl command carries all the quality, language, and output flags; the service tag (NF above) selects which streaming service to talk to, and the value after it is passed 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 run your first download.
Downloading. The full dl command guide: quality, codecs, languages, track selection, and output.
Configuration. Every unshackle.yaml key, directories, vaults, proxies, and naming templates.
REST API. Run the serve HTTP server and drive downloads programmatically.

!!! tip "Getting help" Run unshackle --help or unshackle dl --help at any time. The community Discord is the fastest place to ask questions.

4.3 KiB Raw Blame History