mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-10-29 02:02:13 +01:00
imSp4rky
235839abc8
Route titles with a dtsx/dtsy sample entry to MP4 via MP4Box, since Matroska has no CodecID for DTS-UHD. Add per-rendition HLS audio codec selection, fix merge_segments progress and its cleanup path.
207 lines
8.4 KiB
Markdown
207 lines
8.4 KiB
Markdown
# Installation
|
|
|
|
unshackle is a modular archival tool for movies, TV, and music. It ships as a
|
|
single Python package named `unshackle` that installs one console command, also
|
|
called `unshackle`. This page covers installing that command, the Python
|
|
version it needs, and the external command-line tools it expects to find on your
|
|
`PATH`.
|
|
|
|
!!! note "What you get"
|
|
Installing the package registers a single entry point, the `unshackle`
|
|
command. It covers everything: downloading, key-vault management, device
|
|
provisioning, the REST server, and the helper utilities.
|
|
|
|
## Requirements at a glance
|
|
|
|
| Requirement | Recommended version | Needed for |
|
|
| --- | --- | --- |
|
|
| [Python](https://www.python.org/) | 3.11 to 3.14 | Running unshackle itself |
|
|
| [uv](https://docs.astral.sh/uv/) | ≥ 0.5 | Installing and running unshackle |
|
|
| [FFmpeg](https://ffmpeg.org/) | ≥ 6.0 | Media processing and analysis |
|
|
| [MKVToolNix](https://mkvtoolnix.download/) | ≥ 80 | MKV muxing and metadata editing |
|
|
| [shaka-packager](https://github.com/shaka-project/shaka-packager) | 2.6.1, or ≥ 3.10.0 | DRM decryption |
|
|
| [Bento4](https://github.com/axiomatic-systems/Bento4) | ≥ 1.6.0-639 | Alternate DRM decryption (`mp4decrypt`) |
|
|
| [dovi_tool](https://github.com/quietvoid/dovi_tool) | ≥ 2.1 | Dolby Vision handling |
|
|
| [SubtitleEdit](https://github.com/SubtitleEdit/subtitleedit/releases) | ≥ 5.0 | Subtitle conversion (optional) |
|
|
|
|
The sections below tell you about each of these, and how to make sure that your
|
|
setup is complete.
|
|
|
|
## Python versions
|
|
|
|
unshackle requires **Python 3.11 or newer, up to and including 3.14**
|
|
(`requires-python = ">=3.11,<3.15"`). Anything older than 3.11 or 3.15 and
|
|
later is unsupported, and the installer refuses to assemble the environment.
|
|
|
|
You do not usually need to install a matching Python interpreter by hand, since
|
|
`uv` can download and manage one for you. If you work inside an existing
|
|
virtual environment, make sure that it is on a supported version.
|
|
|
|
## Installing with uv
|
|
|
|
The recommended way to install unshackle is as a `uv` tool. This creates an
|
|
isolated environment for the package and puts the `unshackle` command on your
|
|
`PATH` without touching your system Python.
|
|
|
|
```shell title="Install as a uv tool"
|
|
uv tool install git+https://github.com/unshackle-dl/unshackle.git
|
|
```
|
|
|
|
Once it finishes, the `unshackle` command is available globally:
|
|
|
|
```shell
|
|
unshackle --help
|
|
```
|
|
|
|
!!! tip "Upgrading and removing"
|
|
Because you installed it from a git URL, re-run the same
|
|
`uv tool install` command (uv will update in place) to get a newer version,
|
|
and use `uv tool uninstall unshackle` to remove it.
|
|
|
|
### Running from a clone
|
|
|
|
If you would rather work from a checkout of the repository (for example to try
|
|
an in-development branch or to keep your own local services alongside unshackle), use
|
|
`uv run` inside the clone. This keeps the project's virtual environment active
|
|
for the duration of the command, so you do not have to activate it yourself.
|
|
|
|
```shell title="Run from a git clone"
|
|
git clone https://github.com/unshackle-dl/unshackle.git
|
|
cd unshackle
|
|
uv run unshackle --help
|
|
```
|
|
|
|
Every command shown elsewhere in these docs works the same way from a clone.
|
|
Prefix it with `uv run`:
|
|
|
|
```shell
|
|
uv run unshackle env check
|
|
```
|
|
|
|
!!! note "Developer note"
|
|
Contributors will also want the development and test dependency groups. The
|
|
project defines `dev` (linters, type checkers) and `test` (pytest and
|
|
friends) groups in `pyproject.toml`. Install them with
|
|
`uv sync --group dev --group test` inside the clone. End users can ignore
|
|
these entirely.
|
|
|
|
## External tools on your PATH
|
|
|
|
unshackle shells out to a number of external command-line programs for media
|
|
processing and DRM work. It looks for each one first in the `binaries/` folder
|
|
inside the installed package, and then falls back to your system `PATH`, so
|
|
installing these tools system-wide (or dropping them into that folder) both
|
|
work.
|
|
|
|
### Required tools
|
|
|
|
These must be present for core downloading, decryption, and muxing to work:
|
|
|
|
| Tool | Binary looked up | Why it is needed |
|
|
| --- | --- | --- |
|
|
| FFmpeg | `ffmpeg` | Media processing: remuxing, conversion, track handling |
|
|
| FFprobe | `ffprobe` | Media analysis: inspecting tracks and container details |
|
|
| MKVToolNix | `mkvmerge` | Muxing downloaded tracks into a final MKV |
|
|
| mkvpropedit | `mkvpropedit` | Editing MKV metadata after muxing |
|
|
| shaka-packager | `shaka-packager` / `packager` | Decrypting DRM-protected content (the default decryptor) |
|
|
|
|
!!! warning "shaka-packager is the default decryptor"
|
|
unshackle decrypts with shaka-packager unless you explicitly configure a
|
|
different decryptor. If it is missing, protected downloads will fail at the
|
|
decryption step. See the [configuration reference](../reference/configuration/drm.md#decryption) for the
|
|
`decryption` config key if you want to switch to `mp4decrypt`.
|
|
|
|
!!! danger "Do not use shaka-packager 3.0 through 3.9.x"
|
|
These versions stop with a segmentation fault on a single-track MP4 whose
|
|
internal `track_id` is 2 or more. A track that unshackle downloads from a
|
|
DASH or HLS manifest usually has such a `track_id`.
|
|
|
|
### Recommended and optional tools
|
|
|
|
These extend unshackle's capabilities. Install the ones relevant to what you
|
|
download. For example, `dovi_tool` only matters if you download Dolby Vision video.
|
|
|
|
| Tool | Binary looked up | Why it is needed |
|
|
| --- | --- | --- |
|
|
| Bento4 (`mp4decrypt`) | `mp4decrypt` | Alternative DRM decryptor to shaka-packager |
|
|
| MP4Box (GPAC) | `MP4Box` | Muxing DTS:X Profile 2 (DTS-UHD) audio |
|
|
| dovi_tool | `dovi_tool` | Dolby Vision metadata handling |
|
|
| HDR10Plus_tool | `hdr10plus_tool` | HDR10+ metadata handling |
|
|
| SubtitleEdit | `seconv`, `SubtitleEdit` | Subtitle conversion (the `SeConv` CLI from 5.x) |
|
|
| CCExtractor | `ccextractor` | Extracting closed captions |
|
|
| FFplay | `ffplay` | Simple preview player |
|
|
| MPV | `mpv` | Advanced preview player (used by `util crop`/`util range` previews) |
|
|
| HolaProxy | `hola-proxy` | Hola proxy provider support |
|
|
| Caddy | `caddy` | Optional reverse proxy for `unshackle serve --caddy` |
|
|
| Docker | `docker` | Gluetun VPN proxy support |
|
|
| Git | `git` | Fetching and updating remote service repositories |
|
|
|
|
!!! info "MP4Box is only used for DTS:X Profile 2"
|
|
Titles with DTS:X Profile 2 (DTS-UHD) audio mux to MP4; everything else muxes to MKV
|
|
with `mkvmerge`. Install with `apt install gpac`.
|
|
|
|
!!! tip "SubtitleEdit specifics"
|
|
unshackle looks for `seconv` first, the batch CLI shipped with
|
|
SubtitleEdit 5.x, before falling back to a `SubtitleEdit` (4.x) binary. The
|
|
5.0 GUI has no batch mode, so the `SeConv` CLI is what you want for
|
|
automated subtitle conversion.
|
|
|
|
## Verifying your installation
|
|
|
|
After installation, make sure that the command works and that unshackle can see
|
|
the tools it depends on.
|
|
|
|
### Make sure the command is available
|
|
|
|
```shell
|
|
unshackle --help
|
|
```
|
|
|
|
This prints the list of available commands (`dl`, `env`, `kv`,
|
|
`serve`, `wvd`, `prd`, `search`, `util`, `cfg`, `import`). If your shell reports
|
|
that `unshackle` is not found, the `uv tool` bin directory is probably not on
|
|
your `PATH`. Operate `uv tool update-shell` and open a new terminal.
|
|
|
|
### Examine the external dependencies
|
|
|
|
The `env check` subcommand inspects your environment and reports which tools it
|
|
found:
|
|
|
|
```shell
|
|
unshackle env check
|
|
```
|
|
|
|
=== "Output"
|
|
|
|
It prints a table grouped by category (Core, DRM, HDR, Subtitle, Player,
|
|
Network) with a status column: a green check for tools that resolved and a
|
|
red cross for those it could not find, plus a summary line such as
|
|
`All required tools installed ✓` or `Missing required: <names>`.
|
|
|
|
=== "From a clone"
|
|
|
|
```shell
|
|
uv run unshackle env check
|
|
```
|
|
|
|
If a required tool shows as missing, install it and put it on your `PATH` (or in
|
|
the package's `binaries/` folder), then re-run the check.
|
|
|
|
### Inspect environment paths
|
|
|
|
To see where unshackle will read its configuration from and where it stores
|
|
downloads, caches, cookies, and devices, use:
|
|
|
|
```shell
|
|
unshackle env info
|
|
```
|
|
|
|
If no configuration file exists yet, this command lists the locations unshackle
|
|
searches for one, so you know where to make it. See the
|
|
[configuration guide](configuration-file.md) for the details of that file.
|
|
|
|
## Next steps
|
|
|
|
- Set up your [configuration](configuration-file.md) file (`unshackle.yaml`).
|
|
- Start [downloading](../guide/downloading.md) titles when `env check` finds every required tool.
|