Deployed 9016b52 with MkDocs version: 1.6.1

This commit is contained in:
2026-08-12 01:18:53 +00:00
parent 0f9b700e1a
commit f78dd279d5
15 changed files with 860 additions and 595 deletions
+10
View File
@@ -2403,6 +2403,16 @@ Click <code>cli</code> entry point plus three abstract methods.</p>
<td><code>bool</code></td>
<td>Set <code>True</code> on a service with no subtitle tracks to skip subtitle handling entirely.</td>
</tr>
<tr>
<td><code>ANIME</code></td>
<td><code>bool</code></td>
<td>Set <code>True</code> when the catalog is anime, so metadata lookups prefer AniList. A title's own <code>anime</code> flag overrides it.</td>
</tr>
<tr>
<td><code>DAILY</code></td>
<td><code>bool</code></td>
<td>Set <code>True</code> when the catalog is daily/date-based (talk shows, news, sports), so episodes are named by air date. A title's own <code>daily</code> flag overrides it.</td>
</tr>
</tbody>
</table>
<div class="admonition note">
+53 -4
View File
@@ -3178,6 +3178,49 @@
</div>
</div>
<p>Each serialized title carries <code>type</code> (<code>"episode"</code>, <code>"movie"</code>, or <code>"other"</code>), <code>name</code>, <code>id</code>, <code>language</code>, <code>description</code>, <code>date</code>, and <code>cover_url</code>. Episodes and movies add <code>year</code>; episodes additionally add <code>series_title</code>, <code>season</code>, and <code>number</code>.</p>
<p>These keys are sent only when the title carries them, so a title without them serializes exactly as before:</p>
<table>
<thead>
<tr>
<th>Key</th>
<th>Type</th>
<th>On</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>part</code></td>
<td>integer</td>
<td>episode</td>
<td>Part index of a <a href="../../creating-a-service/#split-episodes">split episode</a>, counting from 1.</td>
</tr>
<tr>
<td><code>air_date</code></td>
<td>string</td>
<td>episode</td>
<td>ISO air date of <a href="../../../guide/downloading/#daily-and-date-based-content">dated content</a>. unshackle names the episode by date instead of <code>SxxExx</code>.</td>
</tr>
<tr>
<td><code>absolute</code></td>
<td>integer</td>
<td>episode</td>
<td>Absolute episode number across all seasons.</td>
</tr>
<tr>
<td><code>daily</code></td>
<td>boolean</td>
<td>episode</td>
<td>The episode is daily/date-based. Set from the title, or from the service's <code>DAILY</code> class attribute.</td>
</tr>
<tr>
<td><code>anime</code></td>
<td>boolean</td>
<td>episode, movie</td>
<td>The title is anime, so metadata lookups prefer AniList. Set from the title, or from the service's <code>ANIME</code> class attribute.</td>
</tr>
</tbody>
</table>
<div class="admonition info">
<p class="admonition-title"><code>part</code> on a split episode</p>
<p>A service that splits one episode into several separately playable videos reports each
@@ -3475,7 +3518,7 @@ is unaffected. See <a href="../../creating-a-service/#split-episodes">Split epis
<td><code>wanted</code></td>
<td>string[]</td>
<td><code>[]</code></td>
<td>Episode/season selectors. Accepts the part form, <code>"S01E01.2"</code>.</td>
<td>Episode/season selectors. Accepts the part form, <code>"S01E01.2"</code>, and the air-date form, <code>"2026-08-11"</code> or <code>"2026-08-01:2026-08-31"</code>.</td>
</tr>
<tr>
<td><code>latest_episode</code></td>
@@ -3616,10 +3659,10 @@ is unaffected. See <a href="../../creating-a-service/#split-episodes">Split epis
<td>Release group tag.</td>
</tr>
<tr>
<td><code>tmdb_id</code> / <code>imdb_id</code> / <code>tvdb_id</code> / <code>animeapi_id</code></td>
<td><code>tmdb_id</code> / <code>imdb_id</code> / <code>tvdb_id</code> / <code>anilist_id</code></td>
<td>-</td>
<td><code>null</code></td>
<td>External ID overrides for tagging.</td>
<td>External ID overrides. Each resolves its metadata directly instead of by a title search, and is used for tagging. Set <code>enrich</code> to also take the title, year and original language. Give at most one of <code>tmdb_id</code>, <code>imdb_id</code> and <code>tvdb_id</code>, since unshackle resolves the others from it. Sending two returns <code>400</code>. <code>anilist_id</code> still combines with one of them. <code>tmdb_id</code> and <code>tvdb_id</code> must be positive integers, <code>imdb_id</code> must look like <code>tt1375666</code>, and <code>anilist_id</code> must be a positive integer or a string like <code>mal:12345</code>, or the request returns <code>400</code>. An ID whose provider is unconfigured, such as <code>tmdb_id</code> with no <code>tmdb_api_key</code>, fails the job rather than returning <code>400</code>. <code>anilist_id</code> needs no key.</td>
</tr>
<tr>
<td><code>tvdb_order</code></td>
@@ -3631,7 +3674,13 @@ is unaffected. See <a href="../../creating-a-service/#split-episodes">Split epis
<td><code>enrich</code></td>
<td>boolean</td>
<td><code>false</code></td>
<td>Override title/year from external source, and fill in the original language. Needs one of <code>tmdb_id</code>, <code>imdb_id</code>, <code>tvdb_id</code> or <code>animeapi_id</code>; without one the job fails instead of returning <code>400</code>.</td>
<td>Overwrite title, year and original language with the external source's. Needs one of <code>tmdb_id</code>, <code>imdb_id</code>, <code>tvdb_id</code> or <code>anilist_id</code>. Without one the job fails instead of returning <code>400</code>.</td>
</tr>
<tr>
<td><code>daily</code></td>
<td>boolean</td>
<td><code>false</code></td>
<td>Treat the title as daily/date-based content and fill missing episode air dates from TVDB. The fill needs <code>enrich</code> and a TVDB ID. An air date the service already set is kept.</td>
</tr>
<tr>
<td><code>output_dir</code></td>
+10
View File
@@ -2637,6 +2637,16 @@ Two kinds of members matter: <strong>class variables</strong> that describe the
<td><code>Optional[tuple[str, ...]]</code></td>
<td>Accepted auth methods (<code>"cookies"</code> / <code>"credentials"</code>). When <code>None</code>, the REST <code>/services</code> endpoint infers them from <code>authenticate()</code>.</td>
</tr>
<tr>
<td><code>ANIME</code></td>
<td><code>bool</code></td>
<td>The catalog is anime, so metadata lookups prefer AniList. A title's own <code>anime</code> flag overrides it.</td>
</tr>
<tr>
<td><code>DAILY</code></td>
<td><code>bool</code></td>
<td>The catalog is daily/date-based, so episodes are named by air date. A title's own <code>daily</code> flag overrides it.</td>
</tr>
</tbody>
</table>
<h3 id="required-methods">Required methods<a class="headerlink" href="#required-methods" title="Permanent link">&para;</a></h3>
+20 -8
View File
@@ -3048,7 +3048,7 @@ configuration file.</p>
<tbody>
<tr>
<td><code>-w</code>, <code>--wanted</code></td>
<td>Wanted episodes, e.g. <code>S01-S05,S07</code>, <code>S01E01-S02E03</code>. Supports exclusions with a leading <code>-</code> (e.g. <code>-S03</code>). For a <a href="../downloading/#split-episodes">split episode</a>, <code>.N</code> picks one part (<code>S01E01.2</code>), a range must stay inside the episode (<code>S01E01.1-S01E01.3</code>), and <code>S01E01</code> on its own takes every part.</td>
<td>Wanted episodes, e.g. <code>S01-S05,S07</code>, <code>S01E01-S02E03</code>. Supports exclusions with a leading <code>-</code> (e.g. <code>-S03</code>). For a <a href="../downloading/#split-episodes">split episode</a>, <code>.N</code> picks one part (<code>S01E01.2</code>), a range must stay inside the episode (<code>S01E01.1-S01E01.3</code>), and <code>S01E01</code> on its own takes every part. For <a href="../downloading/#daily-and-date-based-content">dated content</a>, a token can also be an ISO air date (<code>2026-08-11</code>) or a date range with a colon (<code>2026-08-01:2026-08-31</code>).</td>
</tr>
<tr>
<td><code>--select-titles</code></td>
@@ -3164,23 +3164,27 @@ configuration file.</p>
<tbody>
<tr>
<td><code>--tmdb</code></td>
<td>TMDB ID (integer).</td>
<td>TMDB ID (integer). Used for the tags. Skips the title search. <code>--enrich</code> reads it too. Needs <code>tmdb_api_key</code>.</td>
</tr>
<tr>
<td><code>--imdb</code></td>
<td>IMDb ID, e.g. <code>tt1375666</code>.</td>
<td>IMDb ID, e.g. <code>tt1375666</code>. Used for the tags. Skips the title search. <code>--enrich</code> reads it too. Needs no key.</td>
</tr>
<tr>
<td><code>--tvdb</code></td>
<td>TVDB ID (integer). Skips the series lookup that <code>--tvdb-order</code> would otherwise do. <code>--enrich</code> reads it too.</td>
<td>TVDB ID (integer). Used for the tags. Skips the series lookup that <code>--tvdb-order</code> would otherwise do. <code>--enrich</code> reads it too. Needs <code>tvdb_api_key</code>.</td>
</tr>
<tr>
<td><code>--animeapi</code></td>
<td>AnimeAPI ID, e.g. <code>mal:12345</code> or <code>anilist:98765</code> (defaults to MAL). Back-fills TMDB/IMDb/TVDB.</td>
<td><code>--anilist</code></td>
<td>AniList ID (integer), e.g. <code>--anilist 21</code>. A MyAnimeList ID is accepted as <code>mal:12345</code> and resolved to the AniList entry. Used for the tags. Skips the title search. <code>--enrich</code> reads it too. Needs no key.</td>
</tr>
<tr>
<td><code>--enrich</code></td>
<td>Override show title/year from the external source, and fill in the original language. <strong>Requires</strong> one of <code>--tmdb</code>, <code>--imdb</code>, <code>--tvdb</code>, or <code>--animeapi</code>.</td>
<td>Overwrite show title, year and original language with the external source's. <strong>Requires</strong> one of <code>--tmdb</code>, <code>--imdb</code>, <code>--tvdb</code>, or <code>--anilist</code>.</td>
</tr>
<tr>
<td><code>--daily</code></td>
<td>Treat the title as daily/date-based content and fill missing episode air dates from TVDB. The fill needs <code>--enrich</code> and a TVDB ID. See <a href="../downloading/#daily-and-date-based-content">Daily and date-based content</a>.</td>
</tr>
<tr>
<td><code>--tvdb-order</code></td>
@@ -3188,6 +3192,14 @@ configuration file.</p>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="admonition-title">One ID at a time</p>
<p><code>--tmdb</code>, <code>--imdb</code> and <code>--tvdb</code> cannot be combined. Give one and unshackle resolves the
others from it, writing all three to the tags. <code>--anilist</code> is outside that rule and pairs
with one of them, which is how you attach a western ID to an anime title.
An ID with no provider that can resolve it, such as <code>--tmdb</code> with no <code>tmdb_api_key</code>, fails
before the download starts. <code>--anilist</code> needs no key, so it never fails this check.</p>
</div>
<h4 id="episode-ordering">Episode ordering<a class="headerlink" href="#episode-ordering" title="Permanent link">&para;</a></h4>
<p>A service does not always number a series the way TVDB's aired order does. Some services list
Futurama in TVDB's <code>alternate</code> (Streaming) order, for example. <code>--tvdb-order</code> works out which
@@ -3420,7 +3432,7 @@ and keeps the service's numbering unchanged. Pick an order that covers the whole
</tr>
<tr>
<td>DRM</td>
<td>shaka-packager*, mp4decrypt, ML-Worker</td>
<td>shaka-packager*, mp4decrypt</td>
</tr>
<tr>
<td>HDR</td>
+143 -40
View File
@@ -1030,6 +1030,17 @@
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#daily-and-date-based-content" class="md-nav__link">
<span class="md-ellipsis">
Daily and date-based content
</span>
</a>
</li>
<li class="md-nav__item">
@@ -2695,6 +2706,17 @@
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#daily-and-date-based-content" class="md-nav__link">
<span class="md-ellipsis">
Daily and date-based content
</span>
</a>
</li>
<li class="md-nav__item">
@@ -3385,7 +3407,7 @@ episodes are downloaded.</p>
<h3 id="wanted-ranges">Wanted ranges<a class="headerlink" href="#wanted-ranges" title="Permanent link">&para;</a></h3>
<p><code>-w</code> / <code>--wanted</code> accepts flexible season/episode ranges, comma-separated. Prefix a token
with <code>-</code> to exclude it.</p>
<div class="tabbed-set tabbed-alternate" data-tabs="1:4"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><input id="__tabbed_1_2" name="__tabbed_1" type="radio" /><input id="__tabbed_1_3" name="__tabbed_1" type="radio" /><input id="__tabbed_1_4" name="__tabbed_1" type="radio" /><div class="tabbed-labels"><label for="__tabbed_1_1">Whole seasons</label><label for="__tabbed_1_2">Specific episodes</label><label for="__tabbed_1_3">Exclusions</label><label for="__tabbed_1_4">Split episodes</label></div>
<div class="tabbed-set tabbed-alternate" data-tabs="1:5"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><input id="__tabbed_1_2" name="__tabbed_1" type="radio" /><input id="__tabbed_1_3" name="__tabbed_1" type="radio" /><input id="__tabbed_1_4" name="__tabbed_1" type="radio" /><input id="__tabbed_1_5" name="__tabbed_1" type="radio" /><div class="tabbed-labels"><label for="__tabbed_1_1">Whole seasons</label><label for="__tabbed_1_2">Specific episodes</label><label for="__tabbed_1_3">Exclusions</label><label for="__tabbed_1_4">Split episodes</label><label for="__tabbed_1_5">Air dates</label></div>
<div class="tabbed-content">
<div class="tabbed-block">
<div class="language-shell highlight"><pre><span></span><code><span id="__span-18-1"><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-w<span class="w"> </span>S01<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
@@ -3415,8 +3437,36 @@ with <code>-</code> to exclude it.</p>
</span><span id="__span-21-8"><a id="__codelineno-21-8" name="__codelineno-21-8" href="#__codelineno-21-8"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-w<span class="w"> </span>S01,-S01E01.2<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
</div>
<div class="tabbed-block">
<div class="language-shell highlight"><pre><span></span><code><span id="__span-22-1"><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a><span class="c1"># One day</span>
</span><span id="__span-22-2"><a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-w<span class="w"> </span><span class="m">2026</span>-08-11<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span><span id="__span-22-3"><a id="__codelineno-22-3" name="__codelineno-22-3" href="#__codelineno-22-3"></a>
</span><span id="__span-22-4"><a id="__codelineno-22-4" name="__codelineno-22-4" href="#__codelineno-22-4"></a><span class="c1"># A range of days, colon separated</span>
</span><span id="__span-22-5"><a id="__codelineno-22-5" name="__codelineno-22-5" href="#__codelineno-22-5"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-w<span class="w"> </span><span class="m">2026</span>-08-01:2026-08-31<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span><span id="__span-22-6"><a id="__codelineno-22-6" name="__codelineno-22-6" href="#__codelineno-22-6"></a>
</span><span id="__span-22-7"><a id="__codelineno-22-7" name="__codelineno-22-7" href="#__codelineno-22-7"></a><span class="c1"># August, but not the 15th</span>
</span><span id="__span-22-8"><a id="__codelineno-22-8" name="__codelineno-22-8" href="#__codelineno-22-8"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-w<span class="w"> </span><span class="m">2026</span>-08-01:2026-08-31,-2026-08-15<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
</div>
</div>
</div>
<h3 id="daily-and-date-based-content">Daily and date-based content<a class="headerlink" href="#daily-and-date-based-content" title="Permanent link">&para;</a></h3>
<p>Talk shows, news and sports have no official episode numbering, so unshackle names them
by air date. An episode that carries an air date is written as <code>Show.YYYY.MM.DD</code> instead of
<code>SxxExx</code>, the <code>{date}</code> token holds the ISO date, and the season folder becomes the year.</p>
<p>A service that only carries this kind of content sets <code>DAILY = True</code> on its class, and a
service can set <code>air_date</code> on each episode itself. Add <code>--daily</code> to mark any other title
as date-based:</p>
<div class="language-shell highlight"><pre><span></span><code><span id="__span-23-1"><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--daily<span class="w"> </span>--tvdb<span class="w"> </span><span class="m">73871</span><span class="w"> </span>--enrich<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<p>With <code>--enrich</code> and a TVDB ID, <code>--daily</code> fills in the air date of every episode that has
none. An air date the service already set is kept. Dates before 1970 and dates in the
future are skipped, because TVDB carries placeholder schedule dates for episodes that
have not aired. Without <code>--enrich</code> unshackle has no source to fill from, and says so.</p>
<p>A dated episode answers to its air date in <code>-w</code>, as well as to its <code>SxxExx</code> key. A date
token is a plain ISO date (<code>2026-08-11</code>). A date range uses a colon (<code>2026-08-01:2026-08-31</code>),
because the dashes in a date are part of the date. A range cannot span more than 1000 days.
Date tokens and <code>SxxExx</code> tokens can be mixed in one <code>-w</code>.</p>
<h3 id="split-episodes">Split episodes<a class="headerlink" href="#split-episodes" title="Permanent link">&para;</a></h3>
<p>A few services split one episode into several separately playable videos. Where a service
reports that, add <code>.N</code> after the episode to pick one part.</p>
@@ -3484,7 +3534,7 @@ the episode has no parts, rather than quietly handing you the whole episode. Run
</tr>
</tbody>
</table>
<div class="language-shell highlight"><span class="filename">Grab just the newest episode</span><pre><span></span><code><span id="__span-22-1"><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--latest-episode<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Grab just the newest episode</span><pre><span></span><code><span id="__span-24-1"><a id="__codelineno-24-1" name="__codelineno-24-1" href="#__codelineno-24-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--latest-episode<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<h2 id="including-and-excluding-track-types">Including and excluding track types<a class="headerlink" href="#including-and-excluding-track-types" title="Permanent link">&para;</a></h2>
<p>You can restrict a download to certain track categories, either positively (only these)
@@ -3510,9 +3560,9 @@ or negatively (everything but these).</p>
<li><code>--skip-subtitle-errors</code>: if a subtitle fails to download, skip it and continue rather
than aborting the whole title. Video and audio failures remain fatal.</li>
</ul>
<div class="language-shell highlight"><span class="filename">Subtitles only</span><pre><span></span><code><span id="__span-23-1"><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-S<span class="w"> </span>-sl<span class="w"> </span>en<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Subtitles only</span><pre><span></span><code><span id="__span-25-1"><a id="__codelineno-25-1" name="__codelineno-25-1" href="#__codelineno-25-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-S<span class="w"> </span>-sl<span class="w"> </span>en<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<div class="language-shell highlight"><span class="filename">Everything except chapters</span><pre><span></span><code><span id="__span-24-1"><a id="__codelineno-24-1" name="__codelineno-24-1" href="#__codelineno-24-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-nc<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Everything except chapters</span><pre><span></span><code><span id="__span-26-1"><a id="__codelineno-26-1" name="__codelineno-26-1" href="#__codelineno-26-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-nc<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<div class="admonition note">
<p class="admonition-title">Note</p>
@@ -3544,7 +3594,7 @@ are always kept.</p>
</tr>
</tbody>
</table>
<div class="language-shell highlight"><span class="filename">See the track selection without downloading</span><pre><span></span><code><span id="__span-25-1"><a id="__codelineno-25-1" name="__codelineno-25-1" href="#__codelineno-25-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>-v<span class="w"> </span>H.265<span class="w"> </span>-r<span class="w"> </span>HDR10<span class="w"> </span>--list<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">See the track selection without downloading</span><pre><span></span><code><span id="__span-27-1"><a id="__codelineno-27-1" name="__codelineno-27-1" href="#__codelineno-27-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>-v<span class="w"> </span>H.265<span class="w"> </span>-r<span class="w"> </span>HDR10<span class="w"> </span>--list<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<h2 id="output-and-muxing">Output and muxing<a class="headerlink" href="#output-and-muxing" title="Permanent link">&para;</a></h2>
<h3 id="output-location-and-folders">Output location and folders<a class="headerlink" href="#output-location-and-folders" title="Permanent link">&para;</a></h3>
@@ -3554,7 +3604,7 @@ are always kept.</p>
<li><code>--no-folder</code>: do not create a per-show folder for TV downloads.</li>
<li><code>--no-source</code>: remove the service source tag from the filename and path.</li>
</ul>
<div class="language-shell highlight"><span class="filename">Send this download somewhere specific</span><pre><span></span><code><span id="__span-26-1"><a id="__codelineno-26-1" name="__codelineno-26-1" href="#__codelineno-26-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-o<span class="w"> </span>~/Videos/incoming<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Send this download somewhere specific</span><pre><span></span><code><span id="__span-28-1"><a id="__codelineno-28-1" name="__codelineno-28-1" href="#__codelineno-28-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-o<span class="w"> </span>~/Videos/incoming<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<h3 id="muxing-behaviour">Muxing behaviour<a class="headerlink" href="#muxing-behaviour" title="Permanent link">&para;</a></h3>
<p>By default, tracks are muxed into a single Matroska (<code>.mkv</code>) file with <code>mkvmerge</code>. These
@@ -3590,14 +3640,14 @@ flags change how the output is assembled:</p>
<li><code>--tag</code>: set the release group tag (overrides the configured tag).</li>
<li><code>--repack</code>: add a <code>REPACK</code> tag to the output filename.</li>
</ul>
<div class="language-shell highlight"><span class="filename">Custom group tag and a REPACK label</span><pre><span></span><code><span id="__span-27-1"><a id="__codelineno-27-1" name="__codelineno-27-1" href="#__codelineno-27-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--tag<span class="w"> </span>MYGRP<span class="w"> </span>--repack<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Custom group tag and a REPACK label</span><pre><span></span><code><span id="__span-29-1"><a id="__codelineno-29-1" name="__codelineno-29-1" href="#__codelineno-29-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--tag<span class="w"> </span>MYGRP<span class="w"> </span>--repack<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<h2 id="proxies">Proxies<a class="headerlink" href="#proxies" title="Permanent link">&para;</a></h2>
<p><code>--proxy</code> accepts a full proxy URI, a 2-letter country code (resolved through your
configured proxy providers), or a <code>provider:region</code> form.</p>
<div class="language-shell highlight"><span class="filename">Proxy forms</span><pre><span></span><code><span id="__span-28-1"><a id="__codelineno-28-1" name="__codelineno-28-1" href="#__codelineno-28-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>us<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span><span id="__span-28-2"><a id="__codelineno-28-2" name="__codelineno-28-2" href="#__codelineno-28-2"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>nordvpn:ca<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span><span id="__span-28-3"><a id="__codelineno-28-3" name="__codelineno-28-3" href="#__codelineno-28-3"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span><span class="s1">&#39;http://user:pass@host:8080&#39;</span><span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Proxy forms</span><pre><span></span><code><span id="__span-30-1"><a id="__codelineno-30-1" name="__codelineno-30-1" href="#__codelineno-30-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>us<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span><span id="__span-30-2"><a id="__codelineno-30-2" name="__codelineno-30-2" href="#__codelineno-30-2"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>nordvpn:ca<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span><span id="__span-30-3"><a id="__codelineno-30-3" name="__codelineno-30-3" href="#__codelineno-30-3"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span><span class="s1">&#39;http://user:pass@host:8080&#39;</span><span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<p>Two related flags:</p>
<ul>
@@ -3637,9 +3687,9 @@ configured proxy providers), or a <code>provider:region</code> form.</p>
</tr>
</tbody>
</table>
<div class="language-shell highlight"><span class="filename">Two tracks at a time, eight threads each</span><pre><span></span><code><span id="__span-29-1"><a id="__codelineno-29-1" name="__codelineno-29-1" href="#__codelineno-29-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--downloads<span class="w"> </span><span class="m">2</span><span class="w"> </span>--workers<span class="w"> </span><span class="m">8</span><span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Two tracks at a time, eight threads each</span><pre><span></span><code><span id="__span-31-1"><a id="__codelineno-31-1" name="__codelineno-31-1" href="#__codelineno-31-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--downloads<span class="w"> </span><span class="m">2</span><span class="w"> </span>--workers<span class="w"> </span><span class="m">8</span><span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<div class="language-shell highlight"><span class="filename">Space out a season download</span><pre><span></span><code><span id="__span-30-1"><a id="__codelineno-30-1" name="__codelineno-30-1" href="#__codelineno-30-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-w<span class="w"> </span>S01<span class="w"> </span>--slow<span class="w"> </span><span class="m">30</span>-60<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Space out a season download</span><pre><span></span><code><span id="__span-32-1"><a id="__codelineno-32-1" name="__codelineno-32-1" href="#__codelineno-32-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>-w<span class="w"> </span>S01<span class="w"> </span>--slow<span class="w"> </span><span class="m">30</span>-60<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<h2 id="keys-vaults-and-export">Keys, vaults, and export<a class="headerlink" href="#keys-vaults-and-export" title="Permanent link">&para;</a></h2>
<p>By default, unshackle checks your <strong>key vaults</strong> first and only asks a <strong>CDM</strong> to license
@@ -3648,12 +3698,12 @@ a key when the vault misses. You can force one side or the other:</p>
<li><code>--cdm-only</code>: only use the CDM (skip vaults).</li>
<li><code>--vaults-only</code>: only use key vaults (never license via the CDM); a missing key fails.</li>
</ul>
<div class="language-shell highlight"><span class="filename">Fetch keys only, no download</span><pre><span></span><code><span id="__span-31-1"><a id="__codelineno-31-1" name="__codelineno-31-1" href="#__codelineno-31-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--skip-dl<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Fetch keys only, no download</span><pre><span></span><code><span id="__span-33-1"><a id="__codelineno-33-1" name="__codelineno-33-1" href="#__codelineno-33-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--skip-dl<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<p><code>--export</code> writes a JSON file, into the configured exports directory, containing track
info and the acquired content keys for each title. This is the format consumed by
<code>unshackle import</code> to reconstruct a download later.</p>
<div class="language-shell highlight"><span class="filename">Export track info and keys</span><pre><span></span><code><span id="__span-32-1"><a id="__codelineno-32-1" name="__codelineno-32-1" href="#__codelineno-32-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--skip-dl<span class="w"> </span>--export<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Export track info and keys</span><pre><span></span><code><span id="__span-34-1"><a id="__codelineno-34-1" name="__codelineno-34-1" href="#__codelineno-34-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--skip-dl<span class="w"> </span>--export<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<div class="admonition note">
<p class="admonition-title">Region is recorded only with a proxy</p>
@@ -3670,7 +3720,12 @@ the service. Neither end guesses a language for you, so the fix belongs in the s
</div>
<h2 id="metadata-and-tagging">Metadata and tagging<a class="headerlink" href="#metadata-and-tagging" title="Permanent link">&para;</a></h2>
<p>unshackle looks up metadata automatically, but you can override the identifiers used for
tagging and naming:</p>
tagging and naming. An ID you give is authoritative: unshackle looks it up directly instead of
searching by title, and the ID stays in the tags. An ID only settles <em>which</em> title this is.
To also take that source's title, year and original language, add <code>--enrich</code>. Give at most one
of <code>--tmdb</code>, <code>--imdb</code> and <code>--tvdb</code>; unshackle works the rest out from it. To stop the automatic
lookups but keep the IDs you give, set
<a href="../../reference/configuration/misc/#external-api-keys"><code>disable_metadata</code></a> in your config.</p>
<table>
<thead>
<tr>
@@ -3683,27 +3738,27 @@ tagging and naming:</p>
<tr>
<td><code>--tmdb</code></td>
<td><code>--tmdb 27205</code></td>
<td>Use this TMDB ID instead of automatic lookup.</td>
<td>Use this TMDB ID instead of an automatic search. Needs <code>tmdb_api_key</code>.</td>
</tr>
<tr>
<td><code>--imdb</code></td>
<td><code>--imdb tt1375666</code></td>
<td>Use this IMDb ID.</td>
<td>Use this IMDb ID instead of an automatic search. Needs no key.</td>
</tr>
<tr>
<td><code>--tvdb</code></td>
<td><code>--tvdb 73871</code></td>
<td>Use this TVDB ID instead of looking the series up.</td>
<td>Use this TVDB ID instead of looking the series up. Needs <code>tvdb_api_key</code>.</td>
</tr>
<tr>
<td><code>--animeapi</code></td>
<td><code>--animeapi mal:12345</code></td>
<td>Resolve via AnimeAPI (<code>mal:</code>/<code>anilist:</code> prefix; defaults to MAL).</td>
<td><code>--anilist</code></td>
<td><code>--anilist 21</code></td>
<td>Use this AniList ID instead of an automatic search. <code>mal:12345</code> is also accepted. Needs no key.</td>
</tr>
<tr>
<td><code>--enrich</code></td>
<td>-</td>
<td>Override the show title and year from an external source, and fill in the original language. <strong>Requires</strong> one of <code>--tmdb</code>, <code>--imdb</code>, <code>--tvdb</code>, or <code>--animeapi</code>.</td>
<td>Overwrite the show title, year and original language with the external source's. <strong>Requires</strong> one of <code>--tmdb</code>, <code>--imdb</code>, <code>--tvdb</code>, or <code>--anilist</code>.</td>
</tr>
<tr>
<td><code>--tvdb-order</code></td>
@@ -3712,11 +3767,13 @@ tagging and naming:</p>
</tr>
</tbody>
</table>
<div class="language-shell highlight"><span class="filename">Force the right IMDb match and enrich the title</span><pre><span></span><code><span id="__span-33-1"><a id="__codelineno-33-1" name="__codelineno-33-1" href="#__codelineno-33-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--imdb<span class="w"> </span>tt1375666<span class="w"> </span>--enrich<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Force the right IMDb match, and keep the service&#x27;s own naming</span><pre><span></span><code><span id="__span-35-1"><a id="__codelineno-35-1" name="__codelineno-35-1" href="#__codelineno-35-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--imdb<span class="w"> </span>tt1375666<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<div class="language-shell highlight"><span class="filename">Force the match and take IMDb&#x27;s title, year and language too</span><pre><span></span><code><span id="__span-36-1"><a id="__codelineno-36-1" name="__codelineno-36-1" href="#__codelineno-36-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--imdb<span class="w"> </span>tt1375666<span class="w"> </span>--enrich<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<h3 id="what-each-metadata-provider-supplies">What each metadata provider supplies<a class="headerlink" href="#what-each-metadata-provider-supplies" title="Permanent link">&para;</a></h3>
<p>Providers differ in what they answer with, so <code>--enrich</code> reads different fields depending on
which ID you gave it. A provider only runs when its key is configured:</p>
<p>Providers differ in what they answer with, so the fields <code>--enrich</code> can replace depend on
which ID you gave. Every provider except <code>imdb</code> only runs when its key is configured:</p>
<table>
<thead>
<tr>
@@ -3750,10 +3807,10 @@ which ID you gave it. A provider only runs when its key is configured:</p>
<td>IMDb</td>
</tr>
<tr>
<td>IMDxAPI</td>
<td><code>imdb_api_enabled</code></td>
<td>IMDb</td>
<td><em>(no key needed)</em></td>
<td>yes</td>
<td>only when looked up by ID</td>
<td>yes, alpha-2 such as <code>ko</code></td>
<td>IMDb</td>
</tr>
<tr>
@@ -3763,29 +3820,70 @@ which ID you gave it. A provider only runs when its key is configured:</p>
<td>no, it publishes a country and no language</td>
<td>IMDb, TMDB, TVDB</td>
</tr>
<tr>
<td>AniList</td>
<td><em>(no key needed)</em></td>
<td>yes</td>
<td>yes, worked out from the country of origin, such as <code>ja</code></td>
<td>AniList</td>
</tr>
</tbody>
</table>
<p>Whatever the tag looks like, unshackle normalises it before use, so <code>ko</code>, <code>kor</code> and <code>Korean</code>
all end up as the same language.</p>
<p><code>--enrich</code> consults these in a fixed order:</p>
<div class="admonition note">
<p class="admonition-title">AniList only answers for anime</p>
<p>It is last in the default provider order and returns nothing for a title that is not
anime. The only cost is one search that misses. Put <code>anilist</code> earlier in
<a href="../../reference/configuration/misc/#external-api-keys"><code>metadata_providers</code></a> if you mostly
download anime. Which of the three AniList title variants is used is set by
<a href="../../reference/configuration/misc/#external-api-keys"><code>anilist_title_language</code></a>.</p>
<p>A service can also mark its titles as anime. For those titles unshackle tries AniList
first. When AniList has no match, it falls through to the normal order.</p>
</div>
<p>Each ID goes to the providers that read that kind of ID, in
<a href="../../reference/configuration/misc/#external-api-keys"><code>metadata_providers</code></a> order:</p>
<ul>
<li><code>--tmdb</code> reads TMDB.</li>
<li><code>--imdb</code> tries IMDxAPI, then falls back to OMDb. Since <code>imdb_api_enabled</code> is <code>false</code> by
default, an OMDb key is what makes this path work for most people.</li>
<li><code>--imdb</code> reads IMDb, then falls back to OMDb. IMDb needs no key, so this path works out of
the box, and an OMDb key only matters when IMDb has no answer.</li>
<li><code>--tvdb</code> reads TVDB. It needs <code>tvdb_api_key</code>.</li>
<li><code>--animeapi</code> supplies a title, plus whichever IDs AnimeAPI knows for the show. If that
includes a TMDB, IMDb or TVDB ID, the year and language come from that provider. If it
does not, pair it with <code>--tmdb</code>, <code>--imdb</code> or <code>--tvdb</code>.</li>
<li><code>--anilist</code> reads AniList, which needs no key. It supplies the title, the year and the
original language, and writes an AniList tag. It knows no TMDB, IMDB or TVDB ID, so pair it
with <code>--tmdb</code>, <code>--imdb</code> or <code>--tvdb</code> when you want those tags as well.</li>
</ul>
<p>Language is the one field <code>--enrich</code> will not overwrite. A service that already reported an
original language keeps it, because the platform knows its own catalogue better than a
third-party match does. Everything else follows the usual override behaviour.</p>
<p>Give <strong>one</strong> of <code>--tmdb</code>, <code>--imdb</code> and <code>--tvdb</code>. They cannot be combined, because one ID does
the job on its own: unshackle resolves the other two from it and writes all three to the tags.
Passing two is an error rather than a silent choice between them. <code>--anilist</code> is the exception
and still pairs with one of the three, which is how you tag an anime title with a western ID.</p>
<p>The ID you give must have a provider that can actually resolve it, so unshackle checks that
before it downloads anything. <code>--tmdb</code> without <code>tmdb_api_key</code>, or an ID whose providers your
<code>metadata_providers</code> list leaves out, fails immediately with a message naming what to set.
<code>--imdb</code> needs no key, since the <code>imdb</code> provider is keyless and in the default order.</p>
<p>With <code>--enrich</code>, the title, year and original language are all replaced with the external
source's values, whether or not the service already filled them in. A field the source does
not answer with is left alone, and unshackle logs which fields those were, so a provider with
a thin record cannot blank out what the service told you.</p>
<p><code>--enrich</code> also fills in the absolute episode number of each episode from TVDB's absolute
order, for any series that has one and where the service did not supply it. Anime is the
usual beneficiary, but no part of this is limited to anime. This only adds the
<a href="../../reference/configuration/output/#output_template"><code>{absolute}</code></a> naming variable. The
season and episode numbers are never changed.</p>
<p>With <code>--daily</code>, <code>--enrich</code> also fills in the air date of each episode from TVDB. See
<a href="#daily-and-date-based-content">Daily and date-based content</a>.</p>
<div class="admonition warning">
<p class="admonition-title"><code>--enrich</code> replaces the original language, which affects more than the filename</p>
<p>Track selection reads the original language, so replacing it changes which audio is
treated as the original. That is the point when a service mislabels it, but it means a
wrong ID can pick the wrong audio track and not only write a wrong name. Without
<code>--enrich</code> the service's own value is kept and track selection is untouched.</p>
</div>
<h3 id="episode-ordering">Episode ordering<a class="headerlink" href="#episode-ordering" title="Permanent link">&para;</a></h3>
<p>A service does not always number a series the way TVDB's aired order does. Some services list
Futurama in TVDB's <code>alternate</code> (Streaming) order, for example, while TVDB's <code>official</code> order
holds back four season-one episodes to the start of season two. <code>--tvdb-order</code> works out which
order the service used, then renumbers the episodes into the order you asked for:</p>
<div class="language-shell highlight"><span class="filename">Download Futurama in DVD order</span><pre><span></span><code><span id="__span-34-1"><a id="__codelineno-34-1" name="__codelineno-34-1" href="#__codelineno-34-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--tvdb-order<span class="w"> </span>dvd<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
<div class="language-shell highlight"><span class="filename">Download Futurama in DVD order</span><pre><span></span><code><span id="__span-37-1"><a id="__codelineno-37-1" name="__codelineno-37-1" href="#__codelineno-37-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--tvdb-order<span class="w"> </span>dvd<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<p>Available orders are <code>official</code> (aired), <code>dvd</code>, <code>absolute</code>, <code>alternate</code>, and <code>regional</code>. Set
<code>tvdb_order</code> in your config to apply one by default.</p>
@@ -3887,7 +3985,12 @@ authoritative list.</p>
<tr>
<td><code>--wanted</code></td>
<td><code>-w</code></td>
<td>Episode/season range.</td>
<td>Episode/season range, or an air date.</td>
</tr>
<tr>
<td><code>--daily</code></td>
<td></td>
<td>Fill missing air dates from TVDB during <code>--enrich</code>.</td>
</tr>
<tr>
<td><code>--select-titles</code></td>
@@ -3955,7 +4058,7 @@ authoritative list.</p>
<td>Export track info and keys to JSON.</td>
</tr>
<tr>
<td><code>--tmdb</code> / <code>--imdb</code> / <code>--tvdb</code> / <code>--animeapi</code> / <code>--enrich</code></td>
<td><code>--tmdb</code> / <code>--imdb</code> / <code>--tvdb</code> / <code>--anilist</code> / <code>--enrich</code></td>
<td></td>
<td>Metadata overrides.</td>
</tr>
+5
View File
@@ -2636,6 +2636,11 @@ For an episode with no on-screen name, <code>{episode_name?}</code> and its adja
<td><code>2</code></td>
</tr>
<tr>
<td><code>absolute</code></td>
<td>Absolute episode number, zero-padded to 3 digits, empty when unknown</td>
<td><code>007</code></td>
</tr>
<tr>
<td><code>date</code></td>
<td>ISO air date for daily/dated content</td>
<td><code>2024-06-01</code></td>
File diff suppressed because it is too large Load Diff
+4 -2
View File
@@ -2164,7 +2164,8 @@ A service returns one of these collections from its title lookup. See
</span><span id="__span-0-11"><a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a> <span class="n">description</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
</span><span id="__span-0-12"><a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a> <span class="n">air_date</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
</span><span id="__span-0-13"><a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a> <span class="n">part</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
</span><span id="__span-0-14"><a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a><span class="p">)</span>
</span><span id="__span-0-14"><a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a> <span class="n">absolute</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
</span><span id="__span-0-15"><a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a><span class="p">)</span>
</span></code></pre></div>
<div class="doc doc-contents ">
@@ -2209,7 +2210,8 @@ A service returns one of these collections from its title lookup. See
<p>Whether a parsed <code>-w</code> key set selects this episode.</p>
<p>A part-ful episode answers to both its base key and its part key, so <code>-w s1e1</code>
takes every part. <code>!</code> keys are part-qualified exclusions resolved here.</p>
takes every part. A dated episode also answers to its ISO air date.
<code>!</code> keys are part-qualified exclusions resolved here.</p>
</div>
+2 -2
View File
@@ -2090,8 +2090,8 @@ after the flag's internal destination rather than its visible name; set these ex
<td><code>imdb_id</code></td>
</tr>
<tr>
<td><code>--animeapi</code></td>
<td><code>animeapi_id</code></td>
<td><code>--anilist</code></td>
<td><code>anilist_id</code></td>
</tr>
<tr>
<td><code>-naa</code> / <code>--noatmos</code></td>
+1 -1
View File
@@ -1951,7 +1951,7 @@ default.</p>
</tr>
<tr>
<td><a href="misc/#external-api-keys">External API keys</a></td>
<td><code>imdb_api_enabled</code>, <code>omdb_api_key</code>, <code>tmdb_api_key</code>, <code>tvdb_api_key</code>, <code>tvdb_pin</code>, <code>tvdb_order</code>, <code>simkl_client_id</code>, <code>metadata_providers</code>, <code>decrypt_labs_api_key</code>, <code>ipinfo_api_key</code></td>
<td><code>omdb_api_key</code>, <code>tmdb_api_key</code>, <code>tvdb_api_key</code>, <code>tvdb_pin</code>, <code>tvdb_order</code>, <code>simkl_client_id</code>, <code>metadata_providers</code>, <code>anilist_title_language</code>, <code>disable_metadata</code>, <code>decrypt_labs_api_key</code>, <code>ipinfo_api_key</code></td>
</tr>
<tr>
<td><a href="misc/#caching-updates">Caching &amp; updates</a></td>
+77 -12
View File
@@ -2083,16 +2083,10 @@ each metadata provider can actually answer with, see
</thead>
<tbody>
<tr>
<td><code>imdb_api_enabled</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Use the free IMDxAPI (api.tiffara.com) metadata provider, which needs no API key. Off by default since the site has been unreliable.</td>
</tr>
<tr>
<td><code>omdb_api_key</code></td>
<td>str</td>
<td><code>""</code></td>
<td><a href="https://www.omdbapi.com/">OMDb</a> API key for IMDb metadata lookups; a more reliable alternative to IMDxAPI. Free keys are available on the OMDb site.</td>
<td><a href="https://www.omdbapi.com/">OMDb</a> API key for IMDb metadata lookups; a fallback for when the keyless <code>imdb</code> provider has no answer. Free keys are available on the OMDb site.</td>
</tr>
<tr>
<td><code>tmdb_api_key</code></td>
@@ -2126,11 +2120,23 @@ each metadata provider can actually answer with, see
</tr>
<tr>
<td><code>metadata_providers</code></td>
<td>list</td>
<td>list or map</td>
<td><em>(see below)</em></td>
<td>Metadata providers to use, in the order they are tried.</td>
</tr>
<tr>
<td><code>anilist_title_language</code></td>
<td>str</td>
<td><code>english</code></td>
<td>Which AniList title variant to use: <code>english</code>, <code>romaji</code>, or <code>native</code>.</td>
</tr>
<tr>
<td><code>disable_metadata</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Set to <code>true</code> to stop all automatic metadata lookups. An ID you give yourself is still looked up.</td>
</tr>
<tr>
<td><code>decrypt_labs_api_key</code></td>
<td>str</td>
<td><code>""</code></td>
@@ -2152,11 +2158,65 @@ decides which source wins. <code>metadata_providers</code> sets that order:</p>
</span></code></pre></div>
<p>Names not in the list are never used, so this both orders and filters. Unknown names are
ignored with a warning. Leave it unset for the default order:</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="nt">metadata_providers</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">imdbapi</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">omdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">simkl</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">tmdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">tvdb</span><span class="p p-Indicator">]</span>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="nt">metadata_providers</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">imdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">omdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">simkl</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">tmdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">tvdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">anilist</span><span class="p p-Indicator">]</span>
</span></code></pre></div>
<p>Whatever the order, a provider is skipped when its API key is missing (or, for
<code>imdbapi</code>, when <code>imdb_api_enabled</code> is <code>false</code>). Available names are
<code>imdbapi</code>, <code>omdb</code>, <code>simkl</code>, <code>tmdb</code>, and <code>tvdb</code>.</p>
<p>Whatever the order, unshackle skips a provider that has no API key. <code>imdb</code> and
<code>anilist</code> need no key, so they are always available. Available names are <code>imdb</code>, <code>omdb</code>,
<code>simkl</code>, <code>tmdb</code>, <code>tvdb</code>, and <code>anilist</code>. The old name <code>imdbapi</code> still works and is read as
<code>imdb</code>.</p>
<p><code>anilist</code> is last in the default order. It only answers for anime and returns nothing for
anything else, so it is harmless there. Move it earlier if you mostly download anime.</p>
<p>The order applies to a title search and to a direct lookup of an ID you give with
<code>--tmdb</code>, <code>--imdb</code>, <code>--tvdb</code>, or <code>--anilist</code>. A supplied ID always goes to the providers
that read that kind of ID, and it never falls back to a title search.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Which AniList title <code>anilist_title_language</code> picks</p>
<p>AniList holds up to three titles for a work: the English one, the romaji transliteration,
and the native one. This option says which of them unshackle uses:</p>
<div class="language-yaml highlight"><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">anilist_title_language</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">romaji</span>
</span></code></pre></div>
<p>A work does not always have all three. When the one you asked for is unset on AniList's
side, unshackle falls back in the order english → romaji → native. It takes the first one
that is set, so you always get a title.</p>
</div>
<div class="admonition note">
<p class="admonition-title">What <code>disable_metadata</code> turns off</p>
<p>With <code>disable_metadata: true</code>, unshackle never contacts a metadata provider on its own.
The title search is dead, and that includes the keyless <code>imdb</code> provider. Titles, years and
languages then come only from the service.</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="nt">disable_metadata</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</span></code></pre></div>
<p>An ID you give with <code>--tmdb</code>, <code>--imdb</code>, <code>--tvdb</code>, or <code>--anilist</code> is your permission to use
that ID. That lookup still works. unshackle looks the ID up directly, cross references the other
IDs from it, and <code>--enrich</code> still reads that source. Only the lookups you did not ask for
are stopped.</p>
</div>
<div class="admonition note">
<p class="admonition-title">The <code>imdb</code> provider needs no key</p>
<p>It replaces the earlier <code>imdbapi</code> provider, which read a third-party mirror
(api.tiffara.com) and needed the <code>imdb_api_enabled</code> switch. That option is gone: delete it
from your config, where it is now ignored.</p>
</div>
<div class="admonition tip">
<p class="admonition-title">A different order per title kind</p>
<p>Give a map instead of one list when the best source differs by kind. TVDB is strongest on
series, TMDB on films. There are two kinds, <code>tv</code> and <code>movie</code>, and this example sets both
of them and names every provider, so nothing is left to the default:</p>
<div class="language-yaml highlight"><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">metadata_providers</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">tv</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">tvdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">tmdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">simkl</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">imdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">omdb</span><span class="p p-Indicator">]</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">movie</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">tmdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">imdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">omdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">simkl</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">tvdb</span><span class="p p-Indicator">]</span>
</span></code></pre></div>
<p>Each list is independent: it both orders and filters that kind on its own, so a provider
you leave out of <code>tv</code> is still used for <code>movie</code>. Here TVDB is tried first for a series and
last for a film.</p>
<p>You do not need to give both keys, or a full list in each. A kind you leave out uses the
default order:</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="nt">metadata_providers</span><span class="p">:</span>
</span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w"> </span><span class="nt">tv</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">tvdb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">tmdb</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># movies keep the default order</span>
</span></code></pre></div>
<p><code>tv</code> covers every episode and <code>movie</code> covers every film. unshackle only looks up
metadata for those two kinds, so any other key, such as <code>anime</code> or <code>music</code>, is ignored.</p>
</div>
<div class="admonition note">
<p class="admonition-title"><code>ipinfo_api_key</code> never touches your service sessions</p>
@@ -2317,6 +2377,11 @@ setting, and KIDs, key counts, and other metadata are always logged either way.<
<td><strong>Removed</strong></td>
<td>If set to any non-null value, unshackle exits with an error directing you to configure <a href="../output/"><code>output_template</code></a> instead.</td>
</tr>
<tr>
<td><code>imdb_api_enabled</code></td>
<td><strong>Removed</strong></td>
<td>Ignored. It gated the old <code>imdbapi</code> provider, which the keyless <a href="#external-api-keys"><code>imdb</code></a> provider replaces. Safe to delete from your config.</td>
</tr>
</tbody>
</table>
+10 -1
View File
@@ -2054,7 +2054,7 @@ folder-kind keys.</p>
<details class="example">
<summary>All valid template variables</summary>
<p><code>title</code>, <code>year</code>, <code>season</code>, <code>episode</code>, <code>season_episode</code>, <code>episode_name</code>, <code>part</code>,
<code>date</code>, <code>quality</code>, <code>resolution</code>, <code>source</code>, <code>tag</code>, <code>track_number</code>, <code>artist</code>,
<code>absolute</code>, <code>date</code>, <code>quality</code>, <code>resolution</code>, <code>source</code>, <code>tag</code>, <code>track_number</code>, <code>artist</code>,
<code>album_artist</code>, <code>album</code>, <code>disc</code>, <code>track_total</code>, <code>disc_total</code>, <code>release_type</code>, <code>genre</code>,
<code>explicit</code>, <code>isrc</code>, <code>upc</code>, <code>label</code>, <code>audio</code>, <code>audio_channels</code>, <code>audio_full</code>, <code>atmos</code>,
<code>dual</code>, <code>multi</code>, <code>dubbed</code>, <code>video</code>, <code>hdr</code>, <code>hfr</code>, <code>edition</code>, <code>repack</code>, <code>lang_tag</code>,
@@ -2071,6 +2071,15 @@ standalone variable only in a template that names neither <code>{episode}</code>
<code>{season_episode}</code>, and note that it is always empty in a folder template, since
folders do not carry the part.</p>
</div>
<div class="admonition tip">
<p class="admonition-title"><code>{absolute}</code> counts episodes across seasons</p>
<p><code>absolute</code> holds the absolute episode number, zero-padded to 3 digits (<code>007</code>), and is
empty on titles that have none. It is added to the name and never replaces <code>{season}</code>
or <code>{episode}</code>. Any series with a TVDB absolute order can use it, anime most often.
Services can supply it, and
<a href="../../../guide/downloading/#metadata-and-tagging"><code>--enrich</code></a> fills it in from TVDB.
Use <code>{absolute?}</code> so the name stays clean when it is unknown.</p>
</div>
<h2 id="tagging-naming-keys">Tagging &amp; naming keys<a class="headerlink" href="#tagging-naming-keys" title="Permanent link">&para;</a></h2>
<table>
<thead>
File diff suppressed because one or more lines are too long
+36 -36
View File
@@ -2,146 +2,146 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://docs.unshackle.dev/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/creating-a-service/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/service-architecture/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/authentication/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/endpoints/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/errors/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/job-lifecycle/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/quickstart/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/remote-sessions/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/getting-started/configuration-file/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/getting-started/installation/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/getting-started/quickstart/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/cli-reference/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/downloading/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/drm-and-cdm/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/output-and-naming/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/proxies-and-vpn/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/subtitles/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/troubleshooting/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/vaults/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/api/config/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/api/drm/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/api/service/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/api/titles/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/api/tracks/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/directories/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/download/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/drm/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/example/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/misc/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/network/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/output/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/services/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/vaults/</loc>
<lastmod>2026-08-10</lastmod>
<lastmod>2026-08-12</lastmod>
</url>
</urlset>
BIN
View File
Binary file not shown.