Deployed af17bad with MkDocs version: 1.6.1

This commit is contained in:
2026-10-01 18:24:26 +00:00
parent 7bad3da697
commit 6f00e6a114
12 changed files with 534 additions and 271 deletions
+44 -78
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-examine-your-environment" class="md-nav__link">
<a href="#1-run-setup" class="md-nav__link">
<span class="md-ellipsis">
1. Examine your environment
1. Run setup
</span>
</a>
@@ -610,31 +610,14 @@
</li>
<li class="md-nav__item">
<a href="#2-make-a-minimal-config" class="md-nav__link">
<a href="#2-check-the-output-template" class="md-nav__link">
<span class="md-ellipsis">
2. Make a minimal config
2. Check the output template
</span>
</a>
<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-config-key-you-must-set" class="md-nav__link">
<span class="md-ellipsis">
The one config key you must set
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
@@ -2096,10 +2079,10 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#1-examine-your-environment" class="md-nav__link">
<a href="#1-run-setup" class="md-nav__link">
<span class="md-ellipsis">
1. Examine your environment
1. Run setup
</span>
</a>
@@ -2107,31 +2090,14 @@
</li>
<li class="md-nav__item">
<a href="#2-make-a-minimal-config" class="md-nav__link">
<a href="#2-check-the-output-template" class="md-nav__link">
<span class="md-ellipsis">
2. Make a minimal config
2. Check the output template
</span>
</a>
<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-config-key-you-must-set" class="md-nav__link">
<span class="md-ellipsis">
The one config key you must set
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
@@ -2255,9 +2221,10 @@ module and CDM it needs to fetch and decrypt media, operate a basic <code>unshac
command, and learn where the finished file lands.</p>
<div class="admonition note">
<p class="admonition-title">Before you start</p>
<p>This guide assumes unshackle is already installed and on your <code>PATH</code>. If
<code>unshackle --help</code> does not print a help screen, work through
<a href="../installation/">Installation</a> first.</p>
<p>This guide assumes that you installed unshackle as
<a href="../installation/">Installation</a> describes. The examples use the bare
<code>unshackle</code> command. From a git clone, the recommended install, run each
one as <code>uv run unshackle ...</code>, for example <code>uv run unshackle env check</code>.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">unshackle includes no services</p>
@@ -2266,42 +2233,38 @@ 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-examine-your-environment">1. Examine your environment<a class="headerlink" href="#1-examine-your-environment" title="Permanent link">&para;</a></h2>
<h2 id="1-run-setup">1. Run setup<a class="headerlink" href="#1-run-setup" title="Permanent link">&para;</a></h2>
<p>unshackle drives several external tools (FFmpeg, MKVToolNix, shaka-packager, and
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
others) to decrypt, repack, and mux media, and it needs a config file. The
<code>unshackle setup</code> command prepares both. If you used the install script, setup
has already run. You can run it again at any time:</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>setup
</span></code></pre></div>
<p>This prints a dependency table. The <strong>required</strong> tools (FFmpeg, FFprobe,
MKVToolNix, mkvpropedit, and shaka-packager) must show a green check. Optional
tools such as <code>dovi_tool</code> (Dolby Vision) and CCExtractor (closed captions) only
matter for the features that use them.</p>
<div class="admonition tip">
<p class="admonition-title">Tip</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>
<p>Setup downloads the missing required tools and, if you agree, groups of optional
tools. If no <code>unshackle.yaml</code> exists, it writes a minimal one with your downloads
folder. It also makes the data folders and lets you import <code>.wvd</code> and <code>.prd</code>
devices, one file or a whole folder at a time. <a href="../installation/#what-unshackle-setup-does">Installation</a> tells you what
each step does and where the files go.</p>
<p>Then make sure that unshackle finds the tools:</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>check
</span></code></pre></div>
<p>The <strong>required</strong> tools (FFmpeg, FFprobe, MKVToolNix, mkvpropedit, and
shaka-packager) must show a green check. Optional tools such as <code>dovi_tool</code>
(Dolby Vision) and CCExtractor (closed captions) only matter for the features
that use them.</p>
<div class="admonition note">
<p class="admonition-title">Set up by hand</p>
<p>To do these steps yourself, install the tools from the tables in
<a href="../installation/#external-tools-on-your-path">Installation</a>. Then run
<code>unshackle env info</code> to see where unshackle looks for <code>unshackle.yaml</code>, and
make the file in one of those locations. The
<a href="../configuration-file/">configuration guide</a> gives the details.</p>
</div>
<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 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>
<li><code>unshackle.yaml</code> in your OS user-config directory
(<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. Make <code>unshackle.yaml</code> in one of those
locations.</p>
<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>
<h2 id="2-check-the-output-template">2. Check the output template<a class="headerlink" href="#2-check-the-output-template" title="Permanent link">&para;</a></h2>
<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>
Everything else has a sensible default. The config that setup writes copies <code>tag</code>
and <code>output_template</code> from the example config. A minimal, working config looks like this:</p>
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="nt">output_template</span><span class="p">:</span>
</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>
@@ -2332,7 +2295,9 @@ shows the path). The tag then works with <code>dl</code>, <code>search</code>, a
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 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
needs a <strong>CDM</strong>, a Widevine device (<code>.wvd</code>) or a PlayReady device (<code>.prd</code>). If you
imported devices during <code>unshackle setup</code>, they are already in place. If setup also
wrote your config, it set <code>cdm.default</code> to the device that you chose. Otherwise, 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>
@@ -2457,7 +2422,8 @@ tags the result.</p>
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>
<code>unshackle env info</code> shows its exact path. A config from <code>unshackle setup</code> uses the
folder that you gave at its prompt. Without that setting, the 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>