mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-10-11 10:22:02 +02:00
imSp4rky
c7ab04028a
setup downloads the external tools, writes a first config and imports CDM devices; install.sh and install.bat bootstrap uv and run it.
253 lines
10 KiB
Markdown
253 lines
10 KiB
Markdown
# Quick Start
|
|
|
|
This page takes you from a fresh install to your first downloaded file. You will
|
|
make the one piece of configuration unshackle insists on, supply the service
|
|
module and CDM it needs to fetch and decrypt media, operate a basic `unshackle dl`
|
|
command, and learn where the finished file lands.
|
|
|
|
!!! note "Before you start"
|
|
This guide assumes that you installed unshackle as
|
|
[Installation](installation.md) describes. The examples use the bare
|
|
`unshackle` command. From a git clone, the recommended install, run each
|
|
one as `uv run unshackle ...`, for example `uv run unshackle env check`.
|
|
|
|
!!! warning "unshackle includes no services"
|
|
unshackle handles manifests, DRM, downloading, and muxing. It does not include a
|
|
module for any streaming platform, so you write that part yourself
|
|
([step 3](#3-write-a-service)). `EXAMPLE` in this guide stands in for the tag you
|
|
give yours.
|
|
|
|
## 1. Run setup
|
|
|
|
unshackle drives several external tools (FFmpeg, MKVToolNix, shaka-packager, and
|
|
others) to decrypt, repack, and mux media, and it needs a config file. The
|
|
`unshackle setup` command prepares both. If you used the install script, setup
|
|
has already run. You can run it again at any time:
|
|
|
|
```shell
|
|
unshackle setup
|
|
```
|
|
|
|
Setup downloads the missing required tools and, if you agree, groups of optional
|
|
tools. If no `unshackle.yaml` exists, it writes a minimal one with your downloads
|
|
folder. It also makes the data folders and lets you import `.wvd` and `.prd`
|
|
devices, one file or a whole folder at a time. [Installation](installation.md#what-unshackle-setup-does) tells you what
|
|
each step does and where the files go.
|
|
|
|
Then make sure that unshackle finds the tools:
|
|
|
|
```shell
|
|
unshackle env check
|
|
```
|
|
|
|
The **required** tools (FFmpeg, FFprobe, MKVToolNix, mkvpropedit, and
|
|
shaka-packager) must show a green check. Optional tools such as `dovi_tool`
|
|
(Dolby Vision) and CCExtractor (closed captions) only matter for the features
|
|
that use them.
|
|
|
|
!!! note "Set up by hand"
|
|
To do these steps yourself, install the tools from the tables in
|
|
[Installation](installation.md#external-tools-on-your-path). Then run
|
|
`unshackle env info` to see where unshackle looks for `unshackle.yaml`, and
|
|
make the file in one of those locations. The
|
|
[configuration guide](configuration-file.md) gives the details.
|
|
|
|
## 2. Check the output template
|
|
|
|
unshackle refuses to start a download unless it knows how to name the output file.
|
|
That means `output_template` is the one setting a first run genuinely requires.
|
|
Everything else has a sensible default. The config that setup writes copies `tag`
|
|
and `output_template` from the example config. A minimal, working config looks like this:
|
|
|
|
```yaml title="unshackle.yaml"
|
|
output_template:
|
|
movies: "{title} ({year}) {quality} {source}"
|
|
series: "{title} {season_episode} {episode_name?} {quality} {source}"
|
|
```
|
|
|
|
unshackle fills in each `{variable}` from the title and the tracks you downloaded.
|
|
[Output and Naming](../guide/output-and-naming.md) gives the full set of valid
|
|
variables, including `resolution`, `video`, `audio`, `hdr`, `edition`, `tag`, and more.
|
|
|
|
!!! note "Spaces or dots?"
|
|
unshackle auto-detects your naming style from the template: if the separators
|
|
between variables are mostly spaces, it uses spaces. If they are mostly dots,
|
|
it makes scene-style `Title.S01E01.1080p` names. Write the template in the
|
|
style you want the filenames to look.
|
|
|
|
!!! warning "Editing config from the CLI strips comments"
|
|
You can read and set keys with `unshackle cfg` (for example
|
|
`unshackle cfg tag MYGROUP` or `unshackle cfg --list`), but writing a value
|
|
rewrites the file and **removes any comments** it contained. If you keep notes
|
|
in your config, edit the file by hand instead.
|
|
|
|
## 3. Write a service
|
|
|
|
The service tag you pass to `dl` (like `EXAMPLE`) maps to a **service module**, the
|
|
plugin that talks to one streaming platform. unshackle includes none, so you write
|
|
the one you need. [Creating a Service](../dev/creating-a-service.md) covers how.
|
|
|
|
Put the finished module in your `directories.services` folder (`unshackle env info`
|
|
shows the path). The tag then works with `dl`, `search`, and the other service
|
|
commands.
|
|
|
|
## 4. Add a CDM for DRM
|
|
|
|
Most streaming services encrypt their titles. To fetch content keys, unshackle
|
|
needs a **CDM**, a Widevine device (`.wvd`) or a PlayReady device (`.prd`). If you
|
|
imported devices during `unshackle setup`, they are already in place. If setup also
|
|
wrote your config, it set `cdm.default` to the device that you chose. Otherwise, add a
|
|
Widevine device you already have with:
|
|
|
|
```shell
|
|
unshackle wvd add /path/to/device.wvd
|
|
```
|
|
|
|
This validates the file and moves it into your WVDs directory. Then point services
|
|
at it in your config. The `cdm` map uses the service tag as its config key, with a
|
|
`default` that covers everything else:
|
|
|
|
```yaml title="unshackle.yaml"
|
|
cdm:
|
|
default: my_device # the .wvd file's name, without the extension
|
|
EXAMPLE: my_other_device # override for a specific service
|
|
```
|
|
|
|
PlayReady works the same way with `.prd` files created and managed by the
|
|
[`prd`](../guide/cli-reference.md#prd) command. If a title is DRM-free, unshackle needs no CDM.
|
|
|
|
!!! tip
|
|
Operate `unshackle wvd parse my_device` to inspect a device's security level
|
|
and contents, and `unshackle env info` to show where unshackle stores WVDs and PRDs.
|
|
|
|
## 5. Supply authentication
|
|
|
|
Services that require a login read either **cookies** or **credentials**.
|
|
|
|
- **Cookies**: export the service's cookies to a Netscape-format text file and
|
|
place it in your cookies directory. unshackle looks for, in order:
|
|
`cookies/{SERVICE}.txt`, then `cookies/{SERVICE}/{profile}.txt`, then
|
|
`cookies/{SERVICE}/default.txt`. So unshackle finds a file at `cookies/EXAMPLE.txt`
|
|
automatically for the `EXAMPLE` service.
|
|
|
|
unshackle repairs the usual export damage in memory and does not change your
|
|
file: a missing header line, a byte-order mark, spaces in place of tabs, and
|
|
rows a text editor broke. unshackle refuses a JSON export. Export the cookies
|
|
again in Netscape format.
|
|
|
|
- **Credentials**: store a username and password per service in your config:
|
|
|
|
```yaml title="unshackle.yaml"
|
|
credentials:
|
|
EXAMPLE: "email@example.com:your-password"
|
|
```
|
|
|
|
Use the `-p/--profile` flag to switch between multiple accounts for the same
|
|
service. Whether a given service needs cookies, credentials, or nothing at all
|
|
depends on the service module.
|
|
|
|
## 6. Find a title (optional)
|
|
|
|
If you have a URL or ID already, skip this. Otherwise, find a title on the service
|
|
and note the `id` it prints, because that is what you feed to `dl`:
|
|
|
|
```shell
|
|
unshackle search EXAMPLE "My Show"
|
|
```
|
|
|
|
You can also show what a service gives for a given title without downloading:
|
|
|
|
```shell
|
|
unshackle dl --list-titles EXAMPLE 81234567 # show seasons/episodes
|
|
unshackle dl --list EXAMPLE 81234567 # show available tracks
|
|
```
|
|
|
|
## 7. Do your first download
|
|
|
|
A download always has three parts:
|
|
|
|
```
|
|
unshackle dl <FLAGS> <SERVICE-TAG> <TITLE>
|
|
```
|
|
|
|
- **`dl`** carries every quality, language, track, and output flag.
|
|
- **`<SERVICE-TAG>`** picks which service to talk to (e.g. `EXAMPLE`).
|
|
- **`<TITLE>`** is the URL, ID, or slug the service understands.
|
|
|
|
A good first command asks for 1080p with English audio:
|
|
|
|
```shell title="Your first download"
|
|
unshackle dl -q 1080 -l en EXAMPLE 81234567
|
|
```
|
|
|
|
unshackle will fetch the title, select the tracks that match your flags, and get
|
|
the content keys through your CDM (and any key vaults). It then decrypts, muxes, and
|
|
tags the result.
|
|
|
|
### Handy first flags
|
|
|
|
| Flag | Meaning |
|
|
|---|---|
|
|
| `-q`, `--quality` | Target resolution(s), e.g. `-q 1080` or `-q 1080,720`. Defaults to best available. |
|
|
| `-l`, `--lang` | Language(s) for video and audio, e.g. `-l en` or `-l orig,en`. `orig` = the title's original language. Defaults to `orig`. |
|
|
| `-sl`, `--s-lang` | Subtitle language(s); defaults to `all`. |
|
|
| `-v`, `--vcodec` | Video codec, e.g. `-v H.265`. Defaults to any. |
|
|
| `-r`, `--range` | Dynamic range, e.g. `-r HDR10` or `-r DV`. Defaults to `SDR`. |
|
|
| `-w`, `--wanted` | Which episodes, e.g. `-w S01` or `-w S01E01-S01E03`. For music, which tracks, e.g. `-w 1-5` or `-w 2x3` for disc 2 track 3. |
|
|
| `-o`, `--output` | Override the output directory for this run. |
|
|
| `--list` | List the tracks that would be downloaded, then stop. |
|
|
|
|
!!! example "A few realistic variations"
|
|
```shell
|
|
# A whole first season in the best available quality
|
|
unshackle dl -w S01 EXAMPLE 81234567
|
|
|
|
# 2160p HDR10 with the original-language audio plus English subtitles
|
|
unshackle dl -q 2160 -r HDR10 -l orig -sl en EXAMPLE 81234567
|
|
|
|
# Just the newest episode of an ongoing show
|
|
unshackle dl --latest-episode EXAMPLE 81234567
|
|
```
|
|
|
|
See [Downloading](../guide/downloading.md) for the complete flag reference, including
|
|
codec, bitrate, channel-layout, and track-type selection.
|
|
|
|
## 8. Where the output lands
|
|
|
|
By default, unshackle writes finished files to the `downloads` directory.
|
|
`unshackle env info` shows its exact path. A config from `unshackle setup` uses the
|
|
folder that you gave at its prompt. Without that setting, the default is a `downloads`
|
|
folder one level above the installed `unshackle` package. Override it for one
|
|
command with `-o`:
|
|
|
|
```shell
|
|
unshackle dl -q 1080 -o /mnt/media/incoming EXAMPLE 81234567
|
|
```
|
|
|
|
- unshackle writes **movies** as a single `.mkv` file named from your `movies` template.
|
|
- unshackle groups **TV episodes** into a per-show / per-season folder (from your
|
|
`series` template) unless you pass `--no-folder`.
|
|
- unshackle builds the filename from your `output_template` and adds IMDb/TMDB/TVDB IDs to
|
|
the file's metadata tags when available.
|
|
|
|
To change the default output location permanently, set it in your config:
|
|
|
|
```yaml title="unshackle.yaml"
|
|
directories:
|
|
downloads: /mnt/media/incoming
|
|
```
|
|
|
|
## Where to go next
|
|
|
|
- **[Downloading](../guide/downloading.md)**. The full `dl` command: quality, codecs,
|
|
languages, track selection, hybrid Dolby Vision, and output control.
|
|
- **[Configuration](configuration-file.md)**. Every `unshackle.yaml` config key, plus
|
|
directories, key vaults, proxies, and naming templates.
|
|
- **[REST API](../dev/rest-api/index.md)**. Operate the `serve` server to drive downloads
|
|
over HTTP.
|
|
|
|
!!! tip "You are never far from help"
|
|
`unshackle --help`, `unshackle dl --help`, and `unshackle <command> --help`
|
|
show every option. When in doubt, add `--list` to a `dl`
|
|
command to preview what it would do before it downloads anything.
|