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

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

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 and subtitles
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 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.

Getting help

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