Deployed 8b10b79 with MkDocs version: 1.6.1

This commit is contained in:
2026-08-20 03:01:15 +00:00
parent 01248725da
commit 94f2b09ef6
40 changed files with 1967 additions and 1920 deletions
+67 -63
View File
@@ -599,10 +599,10 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#1-check-your-environment" class="md-nav__link">
<a href="#1-examine-your-environment" class="md-nav__link">
<span class="md-ellipsis">
1. Check your environment
1. Examine your environment
</span>
</a>
@@ -610,22 +610,22 @@
</li>
<li class="md-nav__item">
<a href="#2-create-a-minimal-config" class="md-nav__link">
<a href="#2-make-a-minimal-config" class="md-nav__link">
<span class="md-ellipsis">
2. Create a minimal config
2. Make a minimal config
</span>
</a>
<nav class="md-nav" aria-label="2. Create a minimal config">
<nav class="md-nav" aria-label="2. Make a minimal config">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#the-one-key-you-must-set" class="md-nav__link">
<a href="#the-one-config-key-you-must-set" class="md-nav__link">
<span class="md-ellipsis">
The one key you must set
The one config key you must set
</span>
</a>
@@ -660,10 +660,10 @@
</li>
<li class="md-nav__item">
<a href="#5-provide-authentication" class="md-nav__link">
<a href="#5-supply-authentication" class="md-nav__link">
<span class="md-ellipsis">
5. Provide authentication
5. Supply authentication
</span>
</a>
@@ -682,15 +682,15 @@
</li>
<li class="md-nav__item">
<a href="#7-run-your-first-download" class="md-nav__link">
<a href="#7-do-your-first-download" class="md-nav__link">
<span class="md-ellipsis">
7. Run your first download
7. Do your first download
</span>
</a>
<nav class="md-nav" aria-label="7. Run your first download">
<nav class="md-nav" aria-label="7. Do your first download">
<ul class="md-nav__list">
<li class="md-nav__item">
@@ -2066,10 +2066,10 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#1-check-your-environment" class="md-nav__link">
<a href="#1-examine-your-environment" class="md-nav__link">
<span class="md-ellipsis">
1. Check your environment
1. Examine your environment
</span>
</a>
@@ -2077,22 +2077,22 @@
</li>
<li class="md-nav__item">
<a href="#2-create-a-minimal-config" class="md-nav__link">
<a href="#2-make-a-minimal-config" class="md-nav__link">
<span class="md-ellipsis">
2. Create a minimal config
2. Make a minimal config
</span>
</a>
<nav class="md-nav" aria-label="2. Create a minimal config">
<nav class="md-nav" aria-label="2. Make a minimal config">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#the-one-key-you-must-set" class="md-nav__link">
<a href="#the-one-config-key-you-must-set" class="md-nav__link">
<span class="md-ellipsis">
The one key you must set
The one config key you must set
</span>
</a>
@@ -2127,10 +2127,10 @@
</li>
<li class="md-nav__item">
<a href="#5-provide-authentication" class="md-nav__link">
<a href="#5-supply-authentication" class="md-nav__link">
<span class="md-ellipsis">
5. Provide authentication
5. Supply authentication
</span>
</a>
@@ -2149,15 +2149,15 @@
</li>
<li class="md-nav__item">
<a href="#7-run-your-first-download" class="md-nav__link">
<a href="#7-do-your-first-download" class="md-nav__link">
<span class="md-ellipsis">
7. Run your first download
7. Do your first download
</span>
</a>
<nav class="md-nav" aria-label="7. Run your first download">
<nav class="md-nav" aria-label="7. Do your first download">
<ul class="md-nav__list">
<li class="md-nav__item">
@@ -2220,8 +2220,8 @@
<h1 id="quick-start">Quick Start<a class="headerlink" href="#quick-start" title="Permanent link">&para;</a></h1>
<p>This page takes you from a fresh install to your first downloaded file. You will
create the one piece of configuration unshackle insists on, supply the service
module and CDM it needs to fetch and decrypt media, run a basic <code>unshackle dl</code>
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 <code>unshackle dl</code>
command, and learn where the finished file lands.</p>
<div class="admonition note">
<p class="admonition-title">Before you start</p>
@@ -2236,10 +2236,10 @@ module for any streaming platform, so you write that part yourself
(<a href="#3-write-a-service">step 3</a>). <code>EXAMPLE</code> in this guide stands in for the tag you
give yours.</p>
</div>
<h2 id="1-check-your-environment">1. Check your environment<a class="headerlink" href="#1-check-your-environment" title="Permanent link">&para;</a></h2>
<h2 id="1-examine-your-environment">1. Examine your environment<a class="headerlink" href="#1-examine-your-environment" title="Permanent link">&para;</a></h2>
<p>unshackle drives several external tools (FFmpeg, MKVToolNix, shaka-packager, and
others) to decrypt, repack, and mux media. Confirm they are visible before you
download anything:</p>
others) to decrypt, repack, and mux media. Make sure that they are visible before
you download anything:</p>
<div class="language-shell highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>unshackle<span class="w"> </span>env<span class="w"> </span>check
</span></code></pre></div>
<p>This prints a dependency table. The <strong>required</strong> tools (FFmpeg, FFprobe,
@@ -2251,12 +2251,14 @@ matter for the features that use them.</p>
<p>The summary line at the bottom reports <code>installed/total</code> and lists anything
required that is still missing, so you know exactly what to install next.</p>
</div>
<h2 id="2-create-a-minimal-config">2. Create a minimal config<a class="headerlink" href="#2-create-a-minimal-config" title="Permanent link">&para;</a></h2>
<p>unshackle reads a single YAML file named <code>unshackle.yaml</code>. To see where it looks
for that file, and where it <em>would</em> accept one if you have not made it yet, run:</p>
<h2 id="2-make-a-minimal-config">2. Make a minimal config<a class="headerlink" href="#2-make-a-minimal-config" title="Permanent link">&para;</a></h2>
<p>unshackle reads a single configuration file named <code>unshackle.yaml</code>. To see where it
looks for that file, and where it <em>would</em> accept one if you have not made it yet,
use this command:</p>
<div class="language-shell highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>unshackle<span class="w"> </span>env<span class="w"> </span>info
</span></code></pre></div>
<p>If no config exists, this prints the candidate locations. In search order they are:</p>
<p>If no config exists, this prints the candidate locations. In the order unshackle
examines them, they are:</p>
<ol>
<li><code>unshackle.yaml</code> inside the unshackle package folder.</li>
<li><code>unshackle.yaml</code> in that folder's parent.</li>
@@ -2264,9 +2266,9 @@ for that file, and where it <em>would</em> accept one if you have not made it ye
(<code>~/.config/unshackle/</code> on Linux, <code>%LOCALAPPDATA%\unshackle\</code> on Windows,
<code>~/Library/Application Support/unshackle/</code> on macOS).</li>
</ol>
<p>The <strong>first</strong> file that exists wins. Create <code>unshackle.yaml</code> in one of those
<p>The <strong>first</strong> file that exists wins. Make <code>unshackle.yaml</code> in one of those
locations.</p>
<h3 id="the-one-key-you-must-set">The one key you must set<a class="headerlink" href="#the-one-key-you-must-set" title="Permanent link">&para;</a></h3>
<h3 id="the-one-config-key-you-must-set">The one config key you must set<a class="headerlink" href="#the-one-config-key-you-must-set" title="Permanent link">&para;</a></h3>
<p>unshackle refuses to start a download unless it knows how to name the output file.
That means <code>output_template</code> is the one setting a first run genuinely requires.
Everything else has a sensible default. A minimal, working config looks like this:</p>
@@ -2274,14 +2276,14 @@ Everything else has a sensible default. A minimal, working config looks like thi
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="w"> </span><span class="nt">movies</span><span class="p">:</span><span class="w"> </span><span class="s">"{title}</span><span class="nv"> </span><span class="s">({year})</span><span class="nv"> </span><span class="s">{quality}</span><span class="nv"> </span><span class="s">{source}"</span>
</span><span id="__span-2-3"><a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="w"> </span><span class="nt">series</span><span class="p">:</span><span class="w"> </span><span class="s">"{title}</span><span class="nv"> </span><span class="s">{season_episode}</span><span class="nv"> </span><span class="s">{episode_name?}</span><span class="nv"> </span><span class="s">{quality}</span><span class="nv"> </span><span class="s">{source}"</span>
</span></code></pre></div>
<p>Each <code>{variable}</code> is filled in from the title and the tracks you downloaded. The
full set of valid variables, including <code>resolution</code>, <code>video</code>, <code>audio</code>, <code>hdr</code>,
<code>edition</code>, <code>tag</code>, and more, is documented in <a href="../../guide/output-and-naming/">Output and Naming</a>.</p>
<p>unshackle fills in each <code>{variable}</code> from the title and the tracks you downloaded.
<a href="../../guide/output-and-naming/">Output and Naming</a> gives the full set of valid
variables, including <code>resolution</code>, <code>video</code>, <code>audio</code>, <code>hdr</code>, <code>edition</code>, <code>tag</code>, and more.</p>
<div class="admonition note">
<p class="admonition-title">Spaces or dots?</p>
<p>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 produces scene-style <code>Title.S01E01.1080p</code> names. Write the template in the
between variables are mostly spaces, it uses spaces. If they are mostly dots,
it makes scene-style <code>Title.S01E01.1080p</code> names. Write the template in the
style you want the filenames to look.</p>
</div>
<div class="admonition warning">
@@ -2299,33 +2301,33 @@ the one you need. <a href="../../dev/creating-a-service/">Creating a Service</a>
shows the path). The tag then works with <code>dl</code>, <code>search</code>, and the other service
commands.</p>
<h2 id="4-add-a-cdm-for-drm">4. Add a CDM for DRM<a class="headerlink" href="#4-add-a-cdm-for-drm" title="Permanent link">&para;</a></h2>
<p>Most streaming content is encrypted. To fetch decryption keys, unshackle needs a
<strong>CDM</strong>, a Widevine device (<code>.wvd</code>) or a PlayReady device (<code>.prd</code>). Register a
<p>Most streaming services encrypt their titles. To fetch content keys, unshackle
needs a <strong>CDM</strong>, a Widevine device (<code>.wvd</code>) or a PlayReady device (<code>.prd</code>). Add a
Widevine device you already have with:</p>
<div class="language-shell highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>unshackle<span class="w"> </span>wvd<span class="w"> </span>add<span class="w"> </span>/path/to/device.wvd
</span></code></pre></div>
<p>This validates the file and moves it into your WVDs directory. Then point services
at it in your config. The <code>cdm</code> map is keyed by service tag, with a <code>default</code> that
covers everything else:</p>
at it in your config. The <code>cdm</code> map uses the service tag as its config key, with a
<code>default</code> that covers everything else:</p>
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="nt">cdm</span><span class="p">:</span>
</span><span id="__span-4-2"><a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="w"> </span><span class="nt">default</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">my_device</span><span class="w"> </span><span class="c1"># the .wvd file's name, without the extension</span>
</span><span id="__span-4-3"><a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w"> </span><span class="nt">EXAMPLE</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">my_other_device</span><span class="w"> </span><span class="c1"># override for a specific service</span>
</span></code></pre></div>
<p>PlayReady works the same way with <code>.prd</code> files created and managed by the
<a href="../../guide/cli-reference/#prd"><code>prd</code></a> command. If a title is DRM-free, no CDM is needed.</p>
<a href="../../guide/cli-reference/#prd"><code>prd</code></a> command. If a title is DRM-free, unshackle needs no CDM.</p>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>Run <code>unshackle wvd parse my_device</code> to inspect a device's security level and
contents, and <code>unshackle env info</code> to confirm where WVDs and PRDs are stored.</p>
<p>Operate <code>unshackle wvd parse my_device</code> to inspect a device's security level
and contents, and <code>unshackle env info</code> to show where unshackle stores WVDs and PRDs.</p>
</div>
<h2 id="5-provide-authentication">5. Provide authentication<a class="headerlink" href="#5-provide-authentication" title="Permanent link">&para;</a></h2>
<h2 id="5-supply-authentication">5. Supply authentication<a class="headerlink" href="#5-supply-authentication" title="Permanent link">&para;</a></h2>
<p>Services that require a login read either <strong>cookies</strong> or <strong>credentials</strong>.</p>
<ul>
<li>
<p><strong>Cookies</strong>: export the service's cookies to a Netscape-format text file and
place it in your cookies directory. unshackle looks for, in order:
<code>cookies/{SERVICE}.txt</code>, then <code>cookies/{SERVICE}/{profile}.txt</code>, then
<code>cookies/{SERVICE}/default.txt</code>. So a file at <code>cookies/EXAMPLE.txt</code> is picked up
<code>cookies/{SERVICE}/default.txt</code>. So unshackle finds a file at <code>cookies/EXAMPLE.txt</code>
automatically for the <code>EXAMPLE</code> service.</p>
</li>
<li>
@@ -2339,15 +2341,15 @@ contents, and <code>unshackle env info</code> to confirm where WVDs and PRDs are
service. Whether a given service needs cookies, credentials, or nothing at all
depends on the service module.</p>
<h2 id="6-find-a-title-optional">6. Find a title (optional)<a class="headerlink" href="#6-find-a-title-optional" title="Permanent link">&para;</a></h2>
<p>If you have a URL or ID already, skip this. Otherwise, search the service for a
title and note the <code>id</code> it prints, since that is what you feed to <code>dl</code>:</p>
<p>If you have a URL or ID already, skip this. Otherwise, find a title on the service
and note the <code>id</code> it prints, because that is what you feed to <code>dl</code>:</p>
<div class="language-shell highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>unshackle<span class="w"> </span>search<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="s2">"My Show"</span>
</span></code></pre></div>
<p>You can also list what a service exposes for a given title without downloading:</p>
<p>You can also show what a service gives for a given title without downloading:</p>
<div class="language-shell highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--list-titles<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span><span class="w"> </span><span class="c1"># show seasons/episodes</span>
</span><span id="__span-7-2"><a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--list<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span><span class="w"> </span><span class="c1"># show available tracks</span>
</span></code></pre></div>
<h2 id="7-run-your-first-download">7. Run your first download<a class="headerlink" href="#7-run-your-first-download" title="Permanent link">&para;</a></h2>
<h2 id="7-do-your-first-download">7. Do your first download<a class="headerlink" href="#7-do-your-first-download" title="Permanent link">&para;</a></h2>
<p>A download always has three parts:</p>
<div class="language-text highlight"><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>unshackle dl &lt;FLAGS&gt; &lt;SERVICE-TAG&gt; &lt;TITLE&gt;
</span></code></pre></div>
@@ -2359,8 +2361,9 @@ title and note the <code>id</code> it prints, since that is what you feed to <co
<p>A good first command asks for 1080p with English audio:</p>
<div class="language-shell highlight"><span class="filename">Your first download</span><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-q<span class="w"> </span><span class="m">1080</span><span class="w"> </span>-l<span class="w"> </span>en<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<p>unshackle will fetch the title, select the tracks matching your flags, acquire
keys through your CDM (and any key vaults), then decrypt, mux, and tag the result.</p>
<p>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.</p>
<h3 id="handy-first-flags">Handy first flags<a class="headerlink" href="#handy-first-flags" title="Permanent link">&para;</a></h3>
<table>
<thead>
@@ -2419,14 +2422,15 @@ keys through your CDM (and any key vaults), then decrypt, mux, and tag the resul
<p>See <a href="../../guide/downloading/">Downloading</a> for the complete flag reference, including
codec, bitrate, channel-layout, and track-type selection.</p>
<h2 id="8-where-the-output-lands">8. Where the output lands<a class="headerlink" href="#8-where-the-output-lands" title="Permanent link">&para;</a></h2>
<p>By default, unshackle writes finished files to the <code>downloads</code> directory
(<code>unshackle env info</code> shows its exact path; the built-in default is a <code>downloads</code>
folder one level above the installed <code>unshackle</code> package). Override it per run with <code>-o</code>:</p>
<p>By default, unshackle writes finished files to the <code>downloads</code> directory.
<code>unshackle env info</code> shows its exact path. The built-in default is a <code>downloads</code>
folder one level above the installed <code>unshackle</code> package. Override it for one
command with <code>-o</code>:</p>
<div class="language-shell highlight"><pre><span></span><code><span id="__span-11-1"><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-q<span class="w"> </span><span class="m">1080</span><span class="w"> </span>-o<span class="w"> </span>/mnt/media/incoming<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<ul>
<li>unshackle writes <strong>movies</strong> as a single <code>.mkv</code> file named from your <code>movies</code> template.</li>
<li><strong>TV episodes</strong> are grouped into a per-show / per-season folder (from your
<li>unshackle groups <strong>TV episodes</strong> into a per-show / per-season folder (from your
<code>series</code> template) unless you pass <code>--no-folder</code>.</li>
<li>unshackle builds the filename from your <code>output_template</code> and adds IMDb/TMDB/TVDB IDs to
the file's metadata tags when available.</li>
@@ -2439,15 +2443,15 @@ folder one level above the installed <code>unshackle</code> package). Override i
<ul>
<li><strong><a href="../../guide/downloading/">Downloading</a></strong>. The full <code>dl</code> command: quality, codecs,
languages, track selection, hybrid Dolby Vision, and output control.</li>
<li><strong><a href="../configuration-file/">Configuration</a></strong>. Every <code>unshackle.yaml</code> key, plus
<li><strong><a href="../configuration-file/">Configuration</a></strong>. Every <code>unshackle.yaml</code> config key, plus
directories, key vaults, proxies, and naming templates.</li>
<li><strong><a href="../../dev/rest-api/">REST API</a></strong>. Run the <code>serve</code> server to drive downloads over
HTTP.</li>
<li><strong><a href="../../dev/rest-api/">REST API</a></strong>. Operate the <code>serve</code> server to drive downloads
over HTTP.</li>
</ul>
<div class="admonition tip">
<p class="admonition-title">You are never far from help</p>
<p><code>unshackle --help</code>, <code>unshackle dl --help</code>, and <code>unshackle &lt;command&gt; --help</code>
list every option. When in doubt, add <code>--list</code> to a <code>dl</code>
show every option. When in doubt, add <code>--list</code> to a <code>dl</code>
command to preview what it would do before it downloads anything.</p>
</div>