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
+4 -4
View File
@@ -2142,7 +2142,7 @@
<h1 id="config-api">Config API<a class="headerlink" href="#config-api" title="Permanent link">&para;</a></h1>
<p>Auto-generated reference for the <a class="autorefs autorefs-internal" title="&lt;code class=&quot;doc-symbol doc-symbol-heading doc-symbol-class&quot;&gt;&lt;/code&gt; &lt;span class=&quot;doc doc-object-name doc-class-name&quot;&gt;Config&lt;/span&gt;" href="#unshackle.core.config.Config"><code>Config</code></a> object that models the
<code>unshackle</code> configuration file. For a human-friendly walkthrough of every key, see the
<code>unshackle</code> configuration file. For a human-friendly walkthrough of every config key, see the
<a href="../../configuration/">Configuration Reference</a>.</p>
@@ -2242,7 +2242,7 @@
<div class="doc doc-contents ">
<p>Resolve the folder template for the given title kind.</p>
<p>Find the folder template for the given title kind.</p>
<p>kind: one of "movies", "series", "songs", "albums".
Falls back to the legacy single-string folder template, then "".</p>
@@ -2326,7 +2326,7 @@ between variables. Falls back to dot separator (scene-style) by default.</p>
<div class="doc doc-contents ">
<p>Pick the decryption tool for a service (case-insensitive), falling back to default.</p>
<p>Pick the decryption backend for a service (case-insensitive), falling back to default.</p>
</div>
@@ -2346,7 +2346,7 @@ between variables. Falls back to dot separator (scene-style) by default.</p>
<div class="doc doc-contents ">
<p>Resolve a service's top-level CDM entry (case-insensitive), with default fallback.</p>
<p>Find a service's top-level CDM entry (case-insensitive), with default fallback.</p>
</div>
+56 -53
View File
@@ -3369,10 +3369,10 @@ For configuring DRM as a user, see <a href="../../../guide/drm-and-cdm/">DRM &am
<p>AES Clear Key DRM System.</p>
<p>AES-128 ClearKey (HLS) DRM system.</p>
<p>Generally IV should be provided where possible. If not provided, it will be
set to of the same bit-size of the key.</p>
<p>Give the IV where possible. If you do not give an IV, unshackle sets it to
of the same bit-size as the content key.</p>
@@ -3408,7 +3408,7 @@ set to of the same bit-size of the key.</p>
<div class="doc doc-contents ">
<p>Warn once per track that a segment was passed through undecrypted.</p>
<p>Warn once per track that unshackle passed a segment through undecrypted.</p>
</div>
@@ -3428,7 +3428,7 @@ set to of the same bit-size of the key.</p>
<div class="doc doc-contents ">
<p>Decrypt a Track with AES Clear Key DRM.</p>
<p>Decrypt a Track with AES-128 ClearKey (HLS) DRM.</p>
</div>
@@ -3475,7 +3475,7 @@ set to of the same bit-size of the key.</p>
</td>
<td>
<div class="doc-md-description">
<p>A Key object parsed from a m3u(8) playlist using
<p>A <code>Key</code> object parsed from a m3u(8) playlist using
the <code>m3u8</code> library.</p>
</div>
</td>
@@ -3492,7 +3492,7 @@ the <code>m3u8</code> library.</p>
</td>
<td>
<div class="doc-md-description">
<p>Optional session used to request external URIs with.
<p>Optional HTTP session used to request external URIs with.
Useful to set headers, proxies, cookies, and so forth.</p>
</div>
</td>
@@ -3532,9 +3532,9 @@ Useful to set headers, proxies, cookies, and so forth.</p>
<p>W3C EME ClearKey (org.w3.clearkey) DRM System over MPEG-CENC content.</p>
<p>Distinct from the HLS AES-128 <code>ClearKey</code> class: keys here are delivered by a
license server as a JWK Set keyed by KID, and content is standard CENC
<p>W3C EME ClearKey (org.w3.clearkey) DRM System over MPEG-CENC tracks.</p>
<p>Distinct from the HLS AES-128 <code>ClearKey</code> class: a license server gives the keys
here as a JWK Set keyed by KID, and the media is standard CENC
(decrypted with shaka-packager/mp4decrypt KID:KEY pairs, same as Widevine).</p>
@@ -3733,7 +3733,8 @@ license server as a JWK Set keyed by KID, and content is standard CENC
<div class="doc doc-contents ">
<p>Serialise this DRM instance for export/import (KIDs + license URL).</p>
<p>Content keys are stored once at the export's track level, not duplicated here.</p>
<p>unshackle stores the content keys once at the export's track level, and does not
duplicate them here.</p>
</div>
@@ -3753,7 +3754,7 @@ license server as a JWK Set keyed by KID, and content is standard CENC
<div class="doc doc-contents ">
<p>Build the W3C EME ClearKey JSON license request for the unkeyed KIDs.</p>
<p>Assemble the W3C EME ClearKey JSON license request for the unkeyed KIDs.</p>
</div>
@@ -3773,11 +3774,11 @@ license server as a JWK Set keyed by KID, and content is standard CENC
<div class="doc doc-contents ">
<p>Obtain Content Keys for this DRM Instance from a ClearKey license server.</p>
<p>The licence param is expected to be a function and will be provided with the
W3C JSON license request as <code>challenge</code>. It may return the JWK Set license as
a dict, JSON str, or bytes. If it returns None and the manifest provided a
Laurl, the challenge is POSTed there directly instead.</p>
<p>Get Content Keys for this DRM Instance from a ClearKey license server.</p>
<p>The licence param is a function. unshackle gives it the W3C JSON license
request as <code>challenge</code>. It may return the JWK Set license as a dict, JSON str,
or bytes. If it returns None and the manifest gave a Laurl, unshackle POSTs the
challenge there directly instead.</p>
</div>
@@ -3802,7 +3803,7 @@ Args:
path: Path to the encrypted file to decrypt
Raises:
EnvironmentError if the required decryption executable could not be found.
ValueError if the track has not yet been downloaded.
ValueError if unshackle has not yet downloaded the track.
SubprocessError if the decryption process returned a non-zero exit code.</p>
@@ -3843,7 +3844,7 @@ Raises:
<div class="doc doc-contents ">
<p>Decrypt using Shaka Packager</p>
<p>Decrypt with shaka-packager</p>
</div>
@@ -3876,13 +3877,13 @@ Raises:
<p>MonaLisa DRM System.</p>
<p>Unlike Widevine/PlayReady, MonaLisa does not use a challenge/response flow
with a license server. Instead, the PSSH value (ticket) is provided directly
by the service API, and keys are extracted locally via a WASM module.</p>
<p>Decryption is performed in two stages:
with a license server. Instead, the service API gives the PSSH value (ticket)
directly, and a WASM module extracts the content keys locally.</p>
<p>Decryption has two stages:
1. ML-Worker binary: Removes MonaLisa encryption layer (bbts -&gt; ents)
2. AES-ECB decryption: Final decryption with service-provided key</p>
2. AES-ECB decryption: Final decryption with the service-supplied content key</p>
<p>Initialize MonaLisa DRM.</p>
<p>Initialise MonaLisa DRM.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -3921,7 +3922,7 @@ by the service API, and keys are extracted locally via a WASM module.</p>
</td>
<td>
<div class="doc-md-description">
<p>AES-ECB key for second-stage decryption (hex string or bytes).</p>
<p>AES-ECB content key for second-stage decryption (hex string or bytes).</p>
</div>
</td>
<td>
@@ -3989,7 +3990,7 @@ by the service API, and keys are extracted locally via a WASM module.</p>
</td>
<td>
<div class="doc-md-description">
<p>If key extraction fails.</p>
<p>If content key extraction fails.</p>
</div>
</td>
</tr>
@@ -4194,7 +4195,7 @@ H5DCID-V3-P1-YYYYMMDD-HHMMSS-MEDIAID-TIMESTAMP-SUFFIX</p>
</td>
<td>
<div class="doc-md-description">
<p>Dictionary mapping KID to key hex string.</p>
<p>Dictionary mapping KID to the content key hex string.</p>
</div>
</td>
</tr>
@@ -4259,7 +4260,7 @@ H5DCID-V3-P1-YYYYMMDD-HHMMSS-MEDIAID-TIMESTAMP-SUFFIX</p>
<p>Raised when no PSSH/ticket data is provided.</p>
<p>Raised when the caller gives no PSSH/ticket data.</p>
@@ -4290,7 +4291,7 @@ H5DCID-V3-P1-YYYYMMDD-HHMMSS-MEDIAID-TIMESTAMP-SUFFIX</p>
<p>Raised when key extraction from the ticket fails.</p>
<p>Raised when content key extraction from the ticket fails.</p>
@@ -4413,7 +4414,7 @@ H5DCID-V3-P1-YYYYMMDD-HHMMSS-MEDIAID-TIMESTAMP-SUFFIX</p>
<div class="doc doc-contents ">
<p>Create a MonaLisa DRM instance from a PSSH/ticket.</p>
<p>Make a MonaLisa DRM instance from a PSSH/ticket.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -4452,7 +4453,7 @@ H5DCID-V3-P1-YYYYMMDD-HHMMSS-MEDIAID-TIMESTAMP-SUFFIX</p>
</td>
<td>
<div class="doc-md-description">
<p>AES-ECB key for second-stage decryption.</p>
<p>AES-ECB content key for second-stage decryption.</p>
</div>
</td>
<td>
@@ -4605,9 +4606,9 @@ Stage 2: AES-ECB decryption (ents -&gt; ts)</p>
<div class="doc doc-contents ">
<p>MonaLisa uses per-segment decryption during download via the
on_segment_downloaded callback. By the time this method is called,
the content has already been decrypted and muxed into a container.</p>
<p>MonaLisa uses per-segment decryption during download, through the
on_segment_downloaded callback. When the caller calls this method,
unshackle has already decrypted the media and muxed it into a container.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -4726,7 +4727,8 @@ the content has already been decrypted and muxed into a container.</p>
<div class="doc doc-contents ">
<p>Serialise this DRM instance for export/import (PSSH + KIDs).</p>
<p>Content keys are stored once at the export's track level, not duplicated here.</p>
<p>unshackle stores the content keys once at the export's track level, and does not
duplicate them here.</p>
</div>
@@ -4842,7 +4844,7 @@ the content has already been decrypted and muxed into a container.</p>
<p>Return the decoded error string if a revocation HRESULT is present, else None.</p>
<p>Reads the code from the raw SOAP body (<StatusCode>0x8004C065</StatusCode>)
or from an exception message that carries it, so any service is covered.</p>
or from an exception message that carries it, so this method covers any service.</p>
</div>
@@ -4867,7 +4869,7 @@ Args:
path: Path to the encrypted file to decrypt
Raises:
EnvironmentError if the required decryption executable could not be found.
ValueError if the track has not yet been downloaded.
ValueError if unshackle has not yet downloaded the track.
SubprocessError if the decryption process returned a non-zero exit code.</p>
@@ -4908,7 +4910,7 @@ Raises:
<div class="doc doc-contents ">
<p>Decrypt using Shaka Packager (original method)</p>
<p>Decrypt with shaka-packager (original method)</p>
</div>
@@ -5221,12 +5223,12 @@ Raises:
<p>Get PSSH and KID from within the Initiation Segment of the Track Data.
It also tries to get PSSH and KID from other track data like M3U8 data
as well as through ffprobe.</p>
<p>Create a Widevine DRM System object from a track's information.
This should only be used if a PSSH could not be provided directly.
as well as through FFprobe.</p>
<p>Make a Widevine DRM System object from a track's information.
Use this method only when a PSSH cannot be given directly.
It is <em>rare</em> to need to use this.</p>
<p>You may provide your own requests session to be able to use custom
headers and more.</p>
<p>You can give your own <code>requests.Session</code> to use custom headers
and more.</p>
<p><span class="doc-section-title">Raises:</span></p>
@@ -5284,7 +5286,7 @@ headers and more.</p>
<div class="doc doc-contents ">
<p>Get PSSH and KID from within Initialization Segment Data.</p>
<p>This should only be used if a PSSH could not be provided directly.
<p>Use this method only when a PSSH cannot be given directly.
It is <em>rare</em> to need to use this.</p>
@@ -5339,7 +5341,8 @@ It is <em>rare</em> to need to use this.</p>
<div class="doc doc-contents ">
<p>Serialise this DRM instance for export/import (PSSH + KIDs).</p>
<p>Content keys are stored once at the export's track level, not duplicated here.</p>
<p>unshackle stores the content keys once at the export's track level, and does not
duplicate them here.</p>
</div>
@@ -5359,9 +5362,9 @@ It is <em>rare</em> to need to use this.</p>
<div class="doc doc-contents ">
<p>Create a CDM Session and obtain Content Keys for this DRM Instance.
The certificate and license params are expected to be a function and will
be provided with the challenge and session ID.</p>
<p>Make a CDM Session and get Content Keys for this DRM Instance.
The certificate and license params are functions. unshackle gives them
the challenge and the session ID.</p>
</div>
@@ -5381,9 +5384,9 @@ be provided with the challenge and session ID.</p>
<div class="doc doc-contents ">
<p>Create a CDM Session and obtain Content Keys for this DRM Instance.
The certificate and license params are expected to be a function and will
be provided with the challenge and session ID.</p>
<p>Make a CDM Session and get Content Keys for this DRM Instance.
The certificate and license params are functions. unshackle gives them
the challenge and the session ID.</p>
</div>
@@ -5408,7 +5411,7 @@ Args:
path: Path to the encrypted file to decrypt
Raises:
EnvironmentError if the required decryption executable could not be found.
ValueError if the track has not yet been downloaded.
ValueError if unshackle has not yet downloaded the track.
SubprocessError if the decryption process returned a non-zero exit code.</p>
@@ -5449,7 +5452,7 @@ Raises:
<div class="doc doc-contents ">
<p>Decrypt using Shaka Packager (original method)</p>
<p>Decrypt with shaka-packager (original method)</p>
</div>
+132 -132
View File
@@ -2564,13 +2564,13 @@ walkthrough and <a href="../../../dev/service-architecture/">Service Architectur
<p>requests.Session applying DEFAULT_TIMEOUT when the caller passes none.</p>
<p>requests has no native default timeout; without one a stalled connect or
read hangs forever. RnetSession bounds every request via its client's
<p>requests has no native default timeout. Without one, a stalled connect or
read hangs forever. RnetSession bounds every request through its client's
connect_timeout/read_timeout, so this mirrors that on the requests path.
A per-request non-None <code>timeout=</code> wins; an explicit <code>timeout=None</code> is
still replaced with the default by :class:<code>TimeoutHTTPAdapter</code> on the
mounted adapters, so there is no unbounded read, matching RnetSession where
the client-level timeouts always apply. Pass a large timeout instead.</p>
A per-request non-None <code>timeout=</code> wins. :class:<code>TimeoutHTTPAdapter</code> on the
mounted adapters still replaces an explicit <code>timeout=None</code> with the default,
so there is no unbounded read, as with RnetSession where the client-level
timeouts always apply. Pass a large timeout instead.</p>
@@ -2623,8 +2623,8 @@ the client-level timeouts always apply. Pass a large timeout instead.</p>
<p>HTTPAdapter applying DEFAULT_TIMEOUT when the caller passes none.</p>
<p>Backstops :class:<code>TimeoutSession</code> for the <code>session.send(prepared)</code> path,
which bypasses <code>Session.request</code>; RnetSession bounds those too via its
client, so this keeps parity. A per-request non-None <code>timeout=</code> wins;
which bypasses <code>Session.request</code>. RnetSession bounds those too through its
client, so this keeps parity. A per-request non-None <code>timeout=</code> wins.
<code>None</code> (unset, or explicitly passed) gets the default, because the adapter
cannot distinguish the two, and rnet has no unbounded mode either.</p>
@@ -2775,10 +2775,10 @@ cannot distinguish the two, and rnet has no unbounded mode either.</p>
<p>The Service Base Class.</p>
<p>A Service must implement the abstract methods; the rest are optional overrides that fall back to the base
implementation when a Service does not define them. The main flow runs the session and authentication
methods first, then titles, then tracks and chapters. The license callbacks run later still, during track
download.</p>
<p>A Service must define the abstract methods. The rest are optional overrides that fall back to the base
implementation when a Service does not define them. The main flow operates the HTTP session and
authentication methods first, then titles, then tracks and chapters. The license callbacks operate later
still, during track download.</p>
@@ -3081,8 +3081,8 @@ download.</p>
<p>Services that need separate API calls per codec/range combo can use this
helper from their get_tracks() implementation.</p>
<p>The fetch_fn signature should be: (title, codec, range_) -&gt; Tracks</p>
<p>For HYBRID range, fetch_fn is called with HDR10 and DV separately and
the DV video tracks are merged into the HDR10 result.</p>
<p>For HYBRID range, this helper calls fetch_fn with HDR10 and DV separately,
then merges the DV video tracks into the HDR10 result.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -3105,7 +3105,7 @@ the DV video tracks are merged into the HDR10 result.</p>
</td>
<td>
<div class="doc-md-description">
<p>The title being processed.</p>
<p>The title to process.</p>
</div>
</td>
<td>
@@ -3216,11 +3216,11 @@ the DV video tracks are merged into the HDR10 result.</p>
</span><span id="__span-0-299"><a id="__codelineno-0-299" name="__codelineno-0-299"></a>
</span><span id="__span-0-300"><a id="__codelineno-0-300" name="__codelineno-0-300"></a><span class="sd"> The fetch_fn signature should be: (title, codec, range_) -&gt; Tracks</span>
</span><span id="__span-0-301"><a id="__codelineno-0-301" name="__codelineno-0-301"></a>
</span><span id="__span-0-302"><a id="__codelineno-0-302" name="__codelineno-0-302"></a><span class="sd"> For HYBRID range, fetch_fn is called with HDR10 and DV separately and</span>
</span><span id="__span-0-303"><a id="__codelineno-0-303" name="__codelineno-0-303"></a><span class="sd"> the DV video tracks are merged into the HDR10 result.</span>
</span><span id="__span-0-302"><a id="__codelineno-0-302" name="__codelineno-0-302"></a><span class="sd"> For HYBRID range, this helper calls fetch_fn with HDR10 and DV separately,</span>
</span><span id="__span-0-303"><a id="__codelineno-0-303" name="__codelineno-0-303"></a><span class="sd"> then merges the DV video tracks into the HDR10 result.</span>
</span><span id="__span-0-304"><a id="__codelineno-0-304" name="__codelineno-0-304"></a>
</span><span id="__span-0-305"><a id="__codelineno-0-305" name="__codelineno-0-305"></a><span class="sd"> Args:</span>
</span><span id="__span-0-306"><a id="__codelineno-0-306" name="__codelineno-0-306"></a><span class="sd"> title: The title being processed.</span>
</span><span id="__span-0-306"><a id="__codelineno-0-306" name="__codelineno-0-306"></a><span class="sd"> title: The title to process.</span>
</span><span id="__span-0-307"><a id="__codelineno-0-307" name="__codelineno-0-307"></a><span class="sd"> fetch_fn: A callable that fetches tracks for a specific codec/range.</span>
</span><span id="__span-0-308"><a id="__codelineno-0-308" name="__codelineno-0-308"></a><span class="sd"> """</span>
</span><span id="__span-0-309"><a id="__codelineno-0-309" name="__codelineno-0-309"></a> <span class="n">all_tracks</span> <span class="o">=</span> <span class="n">Tracks</span><span class="p">()</span>
@@ -3298,9 +3298,9 @@ the DV video tracks are merged into the HDR10 result.</p>
<div class="doc doc-contents ">
<p>Creates a Python-requests Session, adds common headers
<p>Creates a Python-requests HTTP session, adds common headers
from config, cookies, retry handler, and a proxy if available.
:returns: Prepared Python-requests Session</p>
:returns: Prepared Python-requests HTTP session</p>
<details class="mkdocstrings-source">
@@ -3340,9 +3340,9 @@ from config, cookies, retry handler, and a proxy if available.
<span class="normal"><a href="#__codelineno-0-397">397</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-365"><a id="__codelineno-0-365" name="__codelineno-0-365"></a><span class="nd">@staticmethod</span>
</span><span id="__span-0-366"><a id="__codelineno-0-366" name="__codelineno-0-366"></a><span class="k">def</span><span class="w"> </span><span class="nf">get_session</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">:</span>
</span><span id="__span-0-367"><a id="__codelineno-0-367" name="__codelineno-0-367"></a><span class="w"> </span><span class="sd">"""</span>
</span><span id="__span-0-368"><a id="__codelineno-0-368" name="__codelineno-0-368"></a><span class="sd"> Creates a Python-requests Session, adds common headers</span>
</span><span id="__span-0-368"><a id="__codelineno-0-368" name="__codelineno-0-368"></a><span class="sd"> Creates a Python-requests HTTP session, adds common headers</span>
</span><span id="__span-0-369"><a id="__codelineno-0-369" name="__codelineno-0-369"></a><span class="sd"> from config, cookies, retry handler, and a proxy if available.</span>
</span><span id="__span-0-370"><a id="__codelineno-0-370" name="__codelineno-0-370"></a><span class="sd"> :returns: Prepared Python-requests Session</span>
</span><span id="__span-0-370"><a id="__codelineno-0-370" name="__codelineno-0-370"></a><span class="sd"> :returns: Prepared Python-requests HTTP session</span>
</span><span id="__span-0-371"><a id="__codelineno-0-371" name="__codelineno-0-371"></a><span class="sd"> """</span>
</span><span id="__span-0-372"><a id="__codelineno-0-372" name="__codelineno-0-372"></a> <span class="n">session</span> <span class="o">=</span> <span class="n">TimeoutSession</span><span class="p">()</span>
</span><span id="__span-0-373"><a id="__codelineno-0-373" name="__codelineno-0-373"></a> <span class="n">session</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">config</span><span class="o">.</span><span class="n">headers</span><span class="p">)</span>
@@ -3391,12 +3391,12 @@ from config, cookies, retry handler, and a proxy if available.
<p>Authenticate the Service with Cookies and/or Credentials (Email/Username and Password).</p>
<p>This is effectively a login() function. Any API calls or object initializations
needing to be made, should be made here. This will be run before any of the
following abstract functions.</p>
needing to be made, should be made here. unshackle operates this method before
any of the following abstract functions.</p>
<p>You should avoid storing or using the Credential outside this function.
Make any calls you need for any Cookies, Tokens, or such, then use those.</p>
<p>The Cookie jar should also not be stored outside this function. However, you may load
the Cookie jar into the service session.</p>
<p>Do not store the cookies outside this function either. However, you can load
the cookies into the service HTTP session.</p>
<details class="mkdocstrings-source">
@@ -3426,14 +3426,14 @@ the Cookie jar into the service session.</p>
</span><span id="__span-0-401"><a id="__codelineno-0-401" name="__codelineno-0-401"></a><span class="sd"> Authenticate the Service with Cookies and/or Credentials (Email/Username and Password).</span>
</span><span id="__span-0-402"><a id="__codelineno-0-402" name="__codelineno-0-402"></a>
</span><span id="__span-0-403"><a id="__codelineno-0-403" name="__codelineno-0-403"></a><span class="sd"> This is effectively a login() function. Any API calls or object initializations</span>
</span><span id="__span-0-404"><a id="__codelineno-0-404" name="__codelineno-0-404"></a><span class="sd"> needing to be made, should be made here. This will be run before any of the</span>
</span><span id="__span-0-405"><a id="__codelineno-0-405" name="__codelineno-0-405"></a><span class="sd"> following abstract functions.</span>
</span><span id="__span-0-404"><a id="__codelineno-0-404" name="__codelineno-0-404"></a><span class="sd"> needing to be made, should be made here. unshackle operates this method before</span>
</span><span id="__span-0-405"><a id="__codelineno-0-405" name="__codelineno-0-405"></a><span class="sd"> any of the following abstract functions.</span>
</span><span id="__span-0-406"><a id="__codelineno-0-406" name="__codelineno-0-406"></a>
</span><span id="__span-0-407"><a id="__codelineno-0-407" name="__codelineno-0-407"></a><span class="sd"> You should avoid storing or using the Credential outside this function.</span>
</span><span id="__span-0-408"><a id="__codelineno-0-408" name="__codelineno-0-408"></a><span class="sd"> Make any calls you need for any Cookies, Tokens, or such, then use those.</span>
</span><span id="__span-0-409"><a id="__codelineno-0-409" name="__codelineno-0-409"></a>
</span><span id="__span-0-410"><a id="__codelineno-0-410" name="__codelineno-0-410"></a><span class="sd"> The Cookie jar should also not be stored outside this function. However, you may load</span>
</span><span id="__span-0-411"><a id="__codelineno-0-411" name="__codelineno-0-411"></a><span class="sd"> the Cookie jar into the service session.</span>
</span><span id="__span-0-410"><a id="__codelineno-0-410" name="__codelineno-0-410"></a><span class="sd"> Do not store the cookies outside this function either. However, you can load</span>
</span><span id="__span-0-411"><a id="__codelineno-0-411" name="__codelineno-0-411"></a><span class="sd"> the cookies into the service HTTP session.</span>
</span><span id="__span-0-412"><a id="__codelineno-0-412" name="__codelineno-0-412"></a><span class="sd"> """</span>
</span><span id="__span-0-413"><a id="__codelineno-0-413" name="__codelineno-0-413"></a> <span class="k">if</span> <span class="n">cookies</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
</span><span id="__span-0-414"><a id="__codelineno-0-414" name="__codelineno-0-414"></a> <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">cookies</span><span class="p">,</span> <span class="n">CookieJar</span><span class="p">):</span>
@@ -3462,7 +3462,7 @@ the Cookie jar into the service session.</p>
<div class="doc doc-contents ">
<p>Request interactive input from the user.</p>
<p>When running locally (CLI), prompts via the shared rich console so the
<p>When running locally (CLI), prompts through the shared rich console so the
prompt renders correctly alongside Live progress / log handlers.
When running in serve mode with an :class:<code>InputBridge</code> attached,
delegates to the bridge which relays the prompt to the remote client.</p>
@@ -3483,7 +3483,7 @@ delegates to the bridge which relays the prompt to the remote client.</p>
<span class="normal"><a href="#__codelineno-0-431">431</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-421"><a id="__codelineno-0-421" name="__codelineno-0-421"></a><span class="k">def</span><span class="w"> </span><span class="nf">request_input</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">prompt</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
</span><span id="__span-0-422"><a id="__codelineno-0-422" name="__codelineno-0-422"></a><span class="w"> </span><span class="sd">"""Request interactive input from the user.</span>
</span><span id="__span-0-423"><a id="__codelineno-0-423" name="__codelineno-0-423"></a>
</span><span id="__span-0-424"><a id="__codelineno-0-424" name="__codelineno-0-424"></a><span class="sd"> When running locally (CLI), prompts via the shared rich console so the</span>
</span><span id="__span-0-424"><a id="__codelineno-0-424" name="__codelineno-0-424"></a><span class="sd"> When running locally (CLI), prompts through the shared rich console so the</span>
</span><span id="__span-0-425"><a id="__codelineno-0-425" name="__codelineno-0-425"></a><span class="sd"> prompt renders correctly alongside Live progress / log handlers.</span>
</span><span id="__span-0-426"><a id="__codelineno-0-426" name="__codelineno-0-426"></a><span class="sd"> When running in serve mode with an :class:`InputBridge` attached,</span>
</span><span id="__span-0-427"><a id="__codelineno-0-427" name="__codelineno-0-427"></a><span class="sd"> delegates to the bridge which relays the prompt to the remote client.</span>
@@ -3510,10 +3510,10 @@ delegates to the bridge which relays the prompt to the remote client.</p>
<div class="doc doc-contents ">
<p>Search by query for titles from the Service.</p>
<p>The query must be taken as a CLI argument by the Service class.
Ideally just re-use the title ID argument (i.e. self.title).</p>
<p>Search results will be displayed in the order yielded.</p>
<p>Find titles from the Service by query.</p>
<p>The Service class must take the query as a CLI argument.
Ideally re-use the title ID argument (that is, self.title).</p>
<p>unshackle displays the search results in the order yielded.</p>
<details class="mkdocstrings-source">
@@ -3529,12 +3529,12 @@ Ideally just re-use the title ID argument (i.e. self.title).</p>
<span class="normal"><a href="#__codelineno-0-441">441</a></span>
<span class="normal"><a href="#__codelineno-0-442">442</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-433"><a id="__codelineno-0-433" name="__codelineno-0-433"></a><span class="k">def</span><span class="w"> </span><span class="nf">search</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Generator</span><span class="p">[</span><span class="n">SearchResult</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">]:</span>
</span><span id="__span-0-434"><a id="__codelineno-0-434" name="__codelineno-0-434"></a><span class="w"> </span><span class="sd">"""</span>
</span><span id="__span-0-435"><a id="__codelineno-0-435" name="__codelineno-0-435"></a><span class="sd"> Search by query for titles from the Service.</span>
</span><span id="__span-0-435"><a id="__codelineno-0-435" name="__codelineno-0-435"></a><span class="sd"> Find titles from the Service by query.</span>
</span><span id="__span-0-436"><a id="__codelineno-0-436" name="__codelineno-0-436"></a>
</span><span id="__span-0-437"><a id="__codelineno-0-437" name="__codelineno-0-437"></a><span class="sd"> The query must be taken as a CLI argument by the Service class.</span>
</span><span id="__span-0-438"><a id="__codelineno-0-438" name="__codelineno-0-438"></a><span class="sd"> Ideally just re-use the title ID argument (i.e. self.title).</span>
</span><span id="__span-0-437"><a id="__codelineno-0-437" name="__codelineno-0-437"></a><span class="sd"> The Service class must take the query as a CLI argument.</span>
</span><span id="__span-0-438"><a id="__codelineno-0-438" name="__codelineno-0-438"></a><span class="sd"> Ideally re-use the title ID argument (that is, self.title).</span>
</span><span id="__span-0-439"><a id="__codelineno-0-439" name="__codelineno-0-439"></a>
</span><span id="__span-0-440"><a id="__codelineno-0-440" name="__codelineno-0-440"></a><span class="sd"> Search results will be displayed in the order yielded.</span>
</span><span id="__span-0-440"><a id="__codelineno-0-440" name="__codelineno-0-440"></a><span class="sd"> unshackle displays the search results in the order yielded.</span>
</span><span id="__span-0-441"><a id="__codelineno-0-441" name="__codelineno-0-441"></a><span class="sd"> """</span>
</span><span id="__span-0-442"><a id="__codelineno-0-442" name="__codelineno-0-442"></a> <span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Search functionality has not been implemented by </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__name__</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
</span></code></pre></div></td></tr></table></div>
@@ -3561,10 +3561,10 @@ Ideally just re-use the title ID argument (i.e. self.title).</p>
<p>Get the Widevine Service Certificate used for Privacy Mode.</p>
<p>:param challenge: The service challenge, providing this to a License endpoint should return the
privacy certificate that the service uses.
:param title: The current <code>Title</code> from get_titles that is being executed. This is provided in
case it has data needed to be used, e.g. for a HTTP request.
:param title: The current <code>Title</code> from get_titles that unshackle processes now. unshackle
gives this in case it holds data you need, for example for an HTTP request.
:param track: The current <code>Track</code> needing decryption. Provided for same reason as <code>title</code>.
:return: The Service Privacy Certificate as Bytes or a Base64 string. Don't Base64 Encode or
:return: The Service Privacy Certificate as Bytes or a Base64 string. Do not Base64 Encode or
Decode the data, return as is to reduce unnecessary computations.</p>
@@ -3591,10 +3591,10 @@ Ideally just re-use the title ID argument (i.e. self.title).</p>
</span><span id="__span-0-449"><a id="__codelineno-0-449" name="__codelineno-0-449"></a>
</span><span id="__span-0-450"><a id="__codelineno-0-450" name="__codelineno-0-450"></a><span class="sd"> :param challenge: The service challenge, providing this to a License endpoint should return the</span>
</span><span id="__span-0-451"><a id="__codelineno-0-451" name="__codelineno-0-451"></a><span class="sd"> privacy certificate that the service uses.</span>
</span><span id="__span-0-452"><a id="__codelineno-0-452" name="__codelineno-0-452"></a><span class="sd"> :param title: The current `Title` from get_titles that is being executed. This is provided in</span>
</span><span id="__span-0-453"><a id="__codelineno-0-453" name="__codelineno-0-453"></a><span class="sd"> case it has data needed to be used, e.g. for a HTTP request.</span>
</span><span id="__span-0-452"><a id="__codelineno-0-452" name="__codelineno-0-452"></a><span class="sd"> :param title: The current `Title` from get_titles that unshackle processes now. unshackle</span>
</span><span id="__span-0-453"><a id="__codelineno-0-453" name="__codelineno-0-453"></a><span class="sd"> gives this in case it holds data you need, for example for an HTTP request.</span>
</span><span id="__span-0-454"><a id="__codelineno-0-454" name="__codelineno-0-454"></a><span class="sd"> :param track: The current `Track` needing decryption. Provided for same reason as `title`.</span>
</span><span id="__span-0-455"><a id="__codelineno-0-455" name="__codelineno-0-455"></a><span class="sd"> :return: The Service Privacy Certificate as Bytes or a Base64 string. Don't Base64 Encode or</span>
</span><span id="__span-0-455"><a id="__codelineno-0-455" name="__codelineno-0-455"></a><span class="sd"> :return: The Service Privacy Certificate as Bytes or a Base64 string. Do not Base64 Encode or</span>
</span><span id="__span-0-456"><a id="__codelineno-0-456" name="__codelineno-0-456"></a><span class="sd"> Decode the data, return as is to reduce unnecessary computations.</span>
</span><span id="__span-0-457"><a id="__codelineno-0-457" name="__codelineno-0-457"></a><span class="sd"> """</span>
</span></code></pre></div></td></tr></table></div>
@@ -3617,16 +3617,16 @@ Ideally just re-use the title ID argument (i.e. self.title).</p>
<div class="doc doc-contents ">
<p>Get a Widevine License message by sending a License Request (challenge).</p>
<p>This License message contains the encrypted Content Decryption Keys and will be
<p>This License message contains the encrypted content keys and will be
read by the Cdm and decrypted.</p>
<p>This is a very important request to get correct. A bad, unexpected, or missing
value in the request can cause your key to be detected and promptly banned,
revoked, disabled, or downgraded.</p>
value in the request can cause the service to detect your CDM device. The device
can then be banned, revoked, disabled, or downgraded.</p>
<p>:param challenge: The license challenge from the Widevine CDM.
:param title: The current <code>Title</code> from get_titles that is being executed. This is provided in
case it has data needed to be used, e.g. for a HTTP request.
:param title: The current <code>Title</code> from get_titles that unshackle processes now. unshackle
gives this in case it holds data you need, for example for an HTTP request.
:param track: The current <code>Track</code> needing decryption. Provided for same reason as <code>title</code>.
:return: The License response as Bytes or a Base64 string. Don't Base64 Encode or
:return: The License response as Bytes or a Base64 string. Do not Base64 Encode or
Decode the data, return as is to reduce unnecessary computations.</p>
@@ -3653,18 +3653,18 @@ revoked, disabled, or downgraded.</p>
</span><span id="__span-0-460"><a id="__codelineno-0-460" name="__codelineno-0-460"></a><span class="w"> </span><span class="sd">"""</span>
</span><span id="__span-0-461"><a id="__codelineno-0-461" name="__codelineno-0-461"></a><span class="sd"> Get a Widevine License message by sending a License Request (challenge).</span>
</span><span id="__span-0-462"><a id="__codelineno-0-462" name="__codelineno-0-462"></a>
</span><span id="__span-0-463"><a id="__codelineno-0-463" name="__codelineno-0-463"></a><span class="sd"> This License message contains the encrypted Content Decryption Keys and will be</span>
</span><span id="__span-0-463"><a id="__codelineno-0-463" name="__codelineno-0-463"></a><span class="sd"> This License message contains the encrypted content keys and will be</span>
</span><span id="__span-0-464"><a id="__codelineno-0-464" name="__codelineno-0-464"></a><span class="sd"> read by the Cdm and decrypted.</span>
</span><span id="__span-0-465"><a id="__codelineno-0-465" name="__codelineno-0-465"></a>
</span><span id="__span-0-466"><a id="__codelineno-0-466" name="__codelineno-0-466"></a><span class="sd"> This is a very important request to get correct. A bad, unexpected, or missing</span>
</span><span id="__span-0-467"><a id="__codelineno-0-467" name="__codelineno-0-467"></a><span class="sd"> value in the request can cause your key to be detected and promptly banned,</span>
</span><span id="__span-0-468"><a id="__codelineno-0-468" name="__codelineno-0-468"></a><span class="sd"> revoked, disabled, or downgraded.</span>
</span><span id="__span-0-467"><a id="__codelineno-0-467" name="__codelineno-0-467"></a><span class="sd"> value in the request can cause the service to detect your CDM device. The device</span>
</span><span id="__span-0-468"><a id="__codelineno-0-468" name="__codelineno-0-468"></a><span class="sd"> can then be banned, revoked, disabled, or downgraded.</span>
</span><span id="__span-0-469"><a id="__codelineno-0-469" name="__codelineno-0-469"></a>
</span><span id="__span-0-470"><a id="__codelineno-0-470" name="__codelineno-0-470"></a><span class="sd"> :param challenge: The license challenge from the Widevine CDM.</span>
</span><span id="__span-0-471"><a id="__codelineno-0-471" name="__codelineno-0-471"></a><span class="sd"> :param title: The current `Title` from get_titles that is being executed. This is provided in</span>
</span><span id="__span-0-472"><a id="__codelineno-0-472" name="__codelineno-0-472"></a><span class="sd"> case it has data needed to be used, e.g. for a HTTP request.</span>
</span><span id="__span-0-471"><a id="__codelineno-0-471" name="__codelineno-0-471"></a><span class="sd"> :param title: The current `Title` from get_titles that unshackle processes now. unshackle</span>
</span><span id="__span-0-472"><a id="__codelineno-0-472" name="__codelineno-0-472"></a><span class="sd"> gives this in case it holds data you need, for example for an HTTP request.</span>
</span><span id="__span-0-473"><a id="__codelineno-0-473" name="__codelineno-0-473"></a><span class="sd"> :param track: The current `Track` needing decryption. Provided for same reason as `title`.</span>
</span><span id="__span-0-474"><a id="__codelineno-0-474" name="__codelineno-0-474"></a><span class="sd"> :return: The License response as Bytes or a Base64 string. Don't Base64 Encode or</span>
</span><span id="__span-0-474"><a id="__codelineno-0-474" name="__codelineno-0-474"></a><span class="sd"> :return: The License response as Bytes or a Base64 string. Do not Base64 Encode or</span>
</span><span id="__span-0-475"><a id="__codelineno-0-475" name="__codelineno-0-475"></a><span class="sd"> Decode the data, return as is to reduce unnecessary computations.</span>
</span><span id="__span-0-476"><a id="__codelineno-0-476" name="__codelineno-0-476"></a><span class="sd"> """</span>
</span></code></pre></div></td></tr></table></div>
@@ -3687,16 +3687,16 @@ revoked, disabled, or downgraded.</p>
<div class="doc doc-contents ">
<p>Get a PlayReady License message by sending a License Request (challenge).</p>
<p>This License message contains the encrypted Content Decryption Keys and will be
<p>This License message contains the encrypted content keys and will be
read by the CDM and decrypted.</p>
<p>This is a very important request to get correct. A bad, unexpected, or missing
value in the request can cause your key to be detected and promptly banned,
revoked, disabled, or downgraded.</p>
value in the request can cause the service to detect your CDM device. The device
can then be banned, revoked, disabled, or downgraded.</p>
<p>:param challenge: The license challenge from the PlayReady CDM.
:param title: The current <code>Title</code> from get_titles that is being executed. This is provided in
case it has data needed to be used, e.g. for a HTTP request.
:param title: The current <code>Title</code> from get_titles that unshackle processes now. unshackle
gives this in case it holds data you need, for example for an HTTP request.
:param track: The current <code>Track</code> needing decryption. Provided for same reason as <code>title</code>.
:return: The License response as Bytes or a Base64 string. Don't Base64 Encode or
:return: The License response as Bytes or a Base64 string. Do not Base64 Encode or
Decode the data, return as is to reduce unnecessary computations.</p>
@@ -3729,18 +3729,18 @@ revoked, disabled, or downgraded.</p>
</span><span id="__span-0-481"><a id="__codelineno-0-481" name="__codelineno-0-481"></a><span class="w"> </span><span class="sd">"""</span>
</span><span id="__span-0-482"><a id="__codelineno-0-482" name="__codelineno-0-482"></a><span class="sd"> Get a PlayReady License message by sending a License Request (challenge).</span>
</span><span id="__span-0-483"><a id="__codelineno-0-483" name="__codelineno-0-483"></a>
</span><span id="__span-0-484"><a id="__codelineno-0-484" name="__codelineno-0-484"></a><span class="sd"> This License message contains the encrypted Content Decryption Keys and will be</span>
</span><span id="__span-0-484"><a id="__codelineno-0-484" name="__codelineno-0-484"></a><span class="sd"> This License message contains the encrypted content keys and will be</span>
</span><span id="__span-0-485"><a id="__codelineno-0-485" name="__codelineno-0-485"></a><span class="sd"> read by the CDM and decrypted.</span>
</span><span id="__span-0-486"><a id="__codelineno-0-486" name="__codelineno-0-486"></a>
</span><span id="__span-0-487"><a id="__codelineno-0-487" name="__codelineno-0-487"></a><span class="sd"> This is a very important request to get correct. A bad, unexpected, or missing</span>
</span><span id="__span-0-488"><a id="__codelineno-0-488" name="__codelineno-0-488"></a><span class="sd"> value in the request can cause your key to be detected and promptly banned,</span>
</span><span id="__span-0-489"><a id="__codelineno-0-489" name="__codelineno-0-489"></a><span class="sd"> revoked, disabled, or downgraded.</span>
</span><span id="__span-0-488"><a id="__codelineno-0-488" name="__codelineno-0-488"></a><span class="sd"> value in the request can cause the service to detect your CDM device. The device</span>
</span><span id="__span-0-489"><a id="__codelineno-0-489" name="__codelineno-0-489"></a><span class="sd"> can then be banned, revoked, disabled, or downgraded.</span>
</span><span id="__span-0-490"><a id="__codelineno-0-490" name="__codelineno-0-490"></a>
</span><span id="__span-0-491"><a id="__codelineno-0-491" name="__codelineno-0-491"></a><span class="sd"> :param challenge: The license challenge from the PlayReady CDM.</span>
</span><span id="__span-0-492"><a id="__codelineno-0-492" name="__codelineno-0-492"></a><span class="sd"> :param title: The current `Title` from get_titles that is being executed. This is provided in</span>
</span><span id="__span-0-493"><a id="__codelineno-0-493" name="__codelineno-0-493"></a><span class="sd"> case it has data needed to be used, e.g. for a HTTP request.</span>
</span><span id="__span-0-492"><a id="__codelineno-0-492" name="__codelineno-0-492"></a><span class="sd"> :param title: The current `Title` from get_titles that unshackle processes now. unshackle</span>
</span><span id="__span-0-493"><a id="__codelineno-0-493" name="__codelineno-0-493"></a><span class="sd"> gives this in case it holds data you need, for example for an HTTP request.</span>
</span><span id="__span-0-494"><a id="__codelineno-0-494" name="__codelineno-0-494"></a><span class="sd"> :param track: The current `Track` needing decryption. Provided for same reason as `title`.</span>
</span><span id="__span-0-495"><a id="__codelineno-0-495" name="__codelineno-0-495"></a><span class="sd"> :return: The License response as Bytes or a Base64 string. Don't Base64 Encode or</span>
</span><span id="__span-0-495"><a id="__codelineno-0-495" name="__codelineno-0-495"></a><span class="sd"> :return: The License response as Bytes or a Base64 string. Do not Base64 Encode or</span>
</span><span id="__span-0-496"><a id="__codelineno-0-496" name="__codelineno-0-496"></a><span class="sd"> Decode the data, return as is to reduce unnecessary computations.</span>
</span><span id="__span-0-497"><a id="__codelineno-0-497" name="__codelineno-0-497"></a><span class="sd"> """</span>
</span><span id="__span-0-498"><a id="__codelineno-0-498" name="__codelineno-0-498"></a> <span class="c1"># Delegates license handling to the Widevine license method by default if a service-specific PlayReady implementation is not provided.</span>
@@ -3765,12 +3765,12 @@ revoked, disabled, or downgraded.</p>
<div class="doc doc-contents ">
<p>Get a W3C ClearKey License (JWK Set) by sending a License Request (challenge).</p>
<p>Used for DASH <code>org.w3.clearkey</code> content. No CDM is involved: the challenge is
<p>Used for DASH <code>org.w3.clearkey</code> tracks. unshackle uses no CDM here: the challenge is
the W3C EME JSON license request, e.g. <code>{"kids": ["&lt;base64url&gt;"], "type": "temporary"}</code>,
and the license is a JWK Set, e.g. <code>{"keys": [{"kty": "oct", "k": "...", "kid": "..."}]}</code>.</p>
<p>:param challenge: The JSON license request bytes to POST to the license server.
:param title: The current <code>Title</code> from get_titles that is being executed. This is provided in
case it has data needed to be used, e.g. for a HTTP request.
:param title: The current <code>Title</code> from get_titles that unshackle processes now. unshackle
gives this in case it holds data you need, for example for an HTTP request.
:param track: The current <code>Track</code> needing decryption. Provided for same reason as <code>title</code>.
:return: The JWK Set license as a dict, JSON str, or raw bytes. Return None (the default)
to let the framework POST the challenge to the manifest-provided Laurl, if any.
@@ -3805,13 +3805,13 @@ and the license is a JWK Set, e.g. <code>{"keys": [{"kty": "oct", "k": "...", "k
</span><span id="__span-0-504"><a id="__codelineno-0-504" name="__codelineno-0-504"></a><span class="w"> </span><span class="sd">"""</span>
</span><span id="__span-0-505"><a id="__codelineno-0-505" name="__codelineno-0-505"></a><span class="sd"> Get a W3C ClearKey License (JWK Set) by sending a License Request (challenge).</span>
</span><span id="__span-0-506"><a id="__codelineno-0-506" name="__codelineno-0-506"></a>
</span><span id="__span-0-507"><a id="__codelineno-0-507" name="__codelineno-0-507"></a><span class="sd"> Used for DASH `org.w3.clearkey` content. No CDM is involved: the challenge is</span>
</span><span id="__span-0-507"><a id="__codelineno-0-507" name="__codelineno-0-507"></a><span class="sd"> Used for DASH `org.w3.clearkey` tracks. unshackle uses no CDM here: the challenge is</span>
</span><span id="__span-0-508"><a id="__codelineno-0-508" name="__codelineno-0-508"></a><span class="sd"> the W3C EME JSON license request, e.g. ``{"kids": ["&lt;base64url&gt;"], "type": "temporary"}``,</span>
</span><span id="__span-0-509"><a id="__codelineno-0-509" name="__codelineno-0-509"></a><span class="sd"> and the license is a JWK Set, e.g. ``{"keys": [{"kty": "oct", "k": "...", "kid": "..."}]}``.</span>
</span><span id="__span-0-510"><a id="__codelineno-0-510" name="__codelineno-0-510"></a>
</span><span id="__span-0-511"><a id="__codelineno-0-511" name="__codelineno-0-511"></a><span class="sd"> :param challenge: The JSON license request bytes to POST to the license server.</span>
</span><span id="__span-0-512"><a id="__codelineno-0-512" name="__codelineno-0-512"></a><span class="sd"> :param title: The current `Title` from get_titles that is being executed. This is provided in</span>
</span><span id="__span-0-513"><a id="__codelineno-0-513" name="__codelineno-0-513"></a><span class="sd"> case it has data needed to be used, e.g. for a HTTP request.</span>
</span><span id="__span-0-512"><a id="__codelineno-0-512" name="__codelineno-0-512"></a><span class="sd"> :param title: The current `Title` from get_titles that unshackle processes now. unshackle</span>
</span><span id="__span-0-513"><a id="__codelineno-0-513" name="__codelineno-0-513"></a><span class="sd"> gives this in case it holds data you need, for example for an HTTP request.</span>
</span><span id="__span-0-514"><a id="__codelineno-0-514" name="__codelineno-0-514"></a><span class="sd"> :param track: The current `Track` needing decryption. Provided for same reason as `title`.</span>
</span><span id="__span-0-515"><a id="__codelineno-0-515" name="__codelineno-0-515"></a><span class="sd"> :return: The JWK Set license as a dict, JSON str, or raw bytes. Return None (the default)</span>
</span><span id="__span-0-516"><a id="__codelineno-0-516" name="__codelineno-0-516"></a><span class="sd"> to let the framework POST the challenge to the manifest-provided Laurl, if any.</span>
@@ -3845,10 +3845,10 @@ and the license is a JWK Set, e.g. <code>{"keys": [{"kty": "oct", "k": "...", "k
<p>Get Titles for the provided title ID.</p>
<p>Return a Movies, Series, or Album objects containing Movie, Episode, or Song title objects respectively.
The returned data must be for the given title ID, or a spawn of the title ID.</p>
<p>At least one object is expected to be returned, or it will presume an invalid Title ID was
provided.</p>
<p>You must return at least one object. If you do not, unshackle presumes an invalid
Title ID.</p>
<p>You can use the <code>data</code> dictionary class instance attribute of each Title to store data you may need later on.
This can be useful to store information on each title that will be required like any sub-asset IDs, or such.</p>
This can be useful to store information on each title that you need later, like any sub-asset IDs, or such.</p>
<details class="mkdocstrings-source">
@@ -3874,11 +3874,11 @@ This can be useful to store information on each title that will be required like
</span><span id="__span-0-527"><a id="__codelineno-0-527" name="__codelineno-0-527"></a><span class="sd"> Return a Movies, Series, or Album objects containing Movie, Episode, or Song title objects respectively.</span>
</span><span id="__span-0-528"><a id="__codelineno-0-528" name="__codelineno-0-528"></a><span class="sd"> The returned data must be for the given title ID, or a spawn of the title ID.</span>
</span><span id="__span-0-529"><a id="__codelineno-0-529" name="__codelineno-0-529"></a>
</span><span id="__span-0-530"><a id="__codelineno-0-530" name="__codelineno-0-530"></a><span class="sd"> At least one object is expected to be returned, or it will presume an invalid Title ID was</span>
</span><span id="__span-0-531"><a id="__codelineno-0-531" name="__codelineno-0-531"></a><span class="sd"> provided.</span>
</span><span id="__span-0-530"><a id="__codelineno-0-530" name="__codelineno-0-530"></a><span class="sd"> You must return at least one object. If you do not, unshackle presumes an invalid</span>
</span><span id="__span-0-531"><a id="__codelineno-0-531" name="__codelineno-0-531"></a><span class="sd"> Title ID.</span>
</span><span id="__span-0-532"><a id="__codelineno-0-532" name="__codelineno-0-532"></a>
</span><span id="__span-0-533"><a id="__codelineno-0-533" name="__codelineno-0-533"></a><span class="sd"> You can use the `data` dictionary class instance attribute of each Title to store data you may need later on.</span>
</span><span id="__span-0-534"><a id="__codelineno-0-534" name="__codelineno-0-534"></a><span class="sd"> This can be useful to store information on each title that will be required like any sub-asset IDs, or such.</span>
</span><span id="__span-0-534"><a id="__codelineno-0-534" name="__codelineno-0-534"></a><span class="sd"> This can be useful to store information on each title that you need later, like any sub-asset IDs, or such.</span>
</span><span id="__span-0-535"><a id="__codelineno-0-535" name="__codelineno-0-535"></a><span class="sd"> """</span>
</span></code></pre></div></td></tr></table></div>
</details>
@@ -4116,21 +4116,21 @@ title cache so config edits take effect without a cache reset, and before any
<p>Get Track objects of the Title.</p>
<p>Return a Tracks object, which itself can contain Video, Audio, Subtitle or even Chapters.
Tracks.videos, Tracks.audio, Tracks.subtitles, and Track.chapters should be a List of Track objects.</p>
<p>Each Track in the Tracks should represent a Video/Audio Stream/Representation/Adaptation or
a Subtitle file.</p>
<p>While one Track should only hold information for one stream/downloadable, try to get as many
unique Track objects per stream type so Stream selection by the root code can give you more
options in terms of Resolution, Bitrate, Codecs, Language, e.t.c.</p>
<p>Each Track in the Tracks should represent a Video/Audio track, Representation, or
Adaptation, or a Subtitle file.</p>
<p>While one Track should only hold information for one downloadable track, try to get as many
unique Track objects per track type so track selection by the root code can give you more
options in terms of Resolution, Bitrate, Codecs, Language, and such.</p>
<p>No decision making or filtering of which Tracks get returned should happen here. It can be
considered an error to filter for e.g. resolution, codec, and such. All filtering based on
arguments will be done by the root code automatically when needed.</p>
<p>Make sure you correctly mark which Tracks are encrypted or not, and by which DRM System
via its <code>drm</code> property.</p>
<p>If you are able to obtain the Track's KID (Key ID) as a 32 char (16 bit) HEX string, provide
it to the Track's <code>kid</code> variable as it will speed up the decryption process later on. It may
or may not be needed, that depends on the service. Generally if you can provide it, without
downloading any of the Track's stream data, then do.</p>
<p>:param title: The current <code>Title</code> from get_titles that is being executed.
<p>Make sure you correctly mark which Tracks have encryption, and which DRM System they
use, with the <code>drm</code> property.</p>
<p>If you can get the Track's KID (Key ID) as a 32 char (16 bit) HEX string, give it to the
Track's <code>kid</code> variable, as it will speed up the decryption process later on. The service
decides whether it is necessary. Generally if you can give it, without downloading any of
the Track's media data, then do.</p>
<p>:param title: The current <code>Title</code> from get_titles that unshackle processes now.
:return: Tracks object containing Video, Audio, Subtitles, and Chapters, if available.</p>
@@ -4173,26 +4173,26 @@ downloading any of the Track's stream data, then do.</p>
</span><span id="__span-0-596"><a id="__codelineno-0-596" name="__codelineno-0-596"></a><span class="sd"> Return a Tracks object, which itself can contain Video, Audio, Subtitle or even Chapters.</span>
</span><span id="__span-0-597"><a id="__codelineno-0-597" name="__codelineno-0-597"></a><span class="sd"> Tracks.videos, Tracks.audio, Tracks.subtitles, and Track.chapters should be a List of Track objects.</span>
</span><span id="__span-0-598"><a id="__codelineno-0-598" name="__codelineno-0-598"></a>
</span><span id="__span-0-599"><a id="__codelineno-0-599" name="__codelineno-0-599"></a><span class="sd"> Each Track in the Tracks should represent a Video/Audio Stream/Representation/Adaptation or</span>
</span><span id="__span-0-600"><a id="__codelineno-0-600" name="__codelineno-0-600"></a><span class="sd"> a Subtitle file.</span>
</span><span id="__span-0-599"><a id="__codelineno-0-599" name="__codelineno-0-599"></a><span class="sd"> Each Track in the Tracks should represent a Video/Audio track, Representation, or</span>
</span><span id="__span-0-600"><a id="__codelineno-0-600" name="__codelineno-0-600"></a><span class="sd"> Adaptation, or a Subtitle file.</span>
</span><span id="__span-0-601"><a id="__codelineno-0-601" name="__codelineno-0-601"></a>
</span><span id="__span-0-602"><a id="__codelineno-0-602" name="__codelineno-0-602"></a><span class="sd"> While one Track should only hold information for one stream/downloadable, try to get as many</span>
</span><span id="__span-0-603"><a id="__codelineno-0-603" name="__codelineno-0-603"></a><span class="sd"> unique Track objects per stream type so Stream selection by the root code can give you more</span>
</span><span id="__span-0-604"><a id="__codelineno-0-604" name="__codelineno-0-604"></a><span class="sd"> options in terms of Resolution, Bitrate, Codecs, Language, e.t.c.</span>
</span><span id="__span-0-602"><a id="__codelineno-0-602" name="__codelineno-0-602"></a><span class="sd"> While one Track should only hold information for one downloadable track, try to get as many</span>
</span><span id="__span-0-603"><a id="__codelineno-0-603" name="__codelineno-0-603"></a><span class="sd"> unique Track objects per track type so track selection by the root code can give you more</span>
</span><span id="__span-0-604"><a id="__codelineno-0-604" name="__codelineno-0-604"></a><span class="sd"> options in terms of Resolution, Bitrate, Codecs, Language, and such.</span>
</span><span id="__span-0-605"><a id="__codelineno-0-605" name="__codelineno-0-605"></a>
</span><span id="__span-0-606"><a id="__codelineno-0-606" name="__codelineno-0-606"></a><span class="sd"> No decision making or filtering of which Tracks get returned should happen here. It can be</span>
</span><span id="__span-0-607"><a id="__codelineno-0-607" name="__codelineno-0-607"></a><span class="sd"> considered an error to filter for e.g. resolution, codec, and such. All filtering based on</span>
</span><span id="__span-0-608"><a id="__codelineno-0-608" name="__codelineno-0-608"></a><span class="sd"> arguments will be done by the root code automatically when needed.</span>
</span><span id="__span-0-609"><a id="__codelineno-0-609" name="__codelineno-0-609"></a>
</span><span id="__span-0-610"><a id="__codelineno-0-610" name="__codelineno-0-610"></a><span class="sd"> Make sure you correctly mark which Tracks are encrypted or not, and by which DRM System</span>
</span><span id="__span-0-611"><a id="__codelineno-0-611" name="__codelineno-0-611"></a><span class="sd"> via its `drm` property.</span>
</span><span id="__span-0-610"><a id="__codelineno-0-610" name="__codelineno-0-610"></a><span class="sd"> Make sure you correctly mark which Tracks have encryption, and which DRM System they</span>
</span><span id="__span-0-611"><a id="__codelineno-0-611" name="__codelineno-0-611"></a><span class="sd"> use, with the `drm` property.</span>
</span><span id="__span-0-612"><a id="__codelineno-0-612" name="__codelineno-0-612"></a>
</span><span id="__span-0-613"><a id="__codelineno-0-613" name="__codelineno-0-613"></a><span class="sd"> If you are able to obtain the Track's KID (Key ID) as a 32 char (16 bit) HEX string, provide</span>
</span><span id="__span-0-614"><a id="__codelineno-0-614" name="__codelineno-0-614"></a><span class="sd"> it to the Track's `kid` variable as it will speed up the decryption process later on. It may</span>
</span><span id="__span-0-615"><a id="__codelineno-0-615" name="__codelineno-0-615"></a><span class="sd"> or may not be needed, that depends on the service. Generally if you can provide it, without</span>
</span><span id="__span-0-616"><a id="__codelineno-0-616" name="__codelineno-0-616"></a><span class="sd"> downloading any of the Track's stream data, then do.</span>
</span><span id="__span-0-613"><a id="__codelineno-0-613" name="__codelineno-0-613"></a><span class="sd"> If you can get the Track's KID (Key ID) as a 32 char (16 bit) HEX string, give it to the</span>
</span><span id="__span-0-614"><a id="__codelineno-0-614" name="__codelineno-0-614"></a><span class="sd"> Track's `kid` variable, as it will speed up the decryption process later on. The service</span>
</span><span id="__span-0-615"><a id="__codelineno-0-615" name="__codelineno-0-615"></a><span class="sd"> decides whether it is necessary. Generally if you can give it, without downloading any of</span>
</span><span id="__span-0-616"><a id="__codelineno-0-616" name="__codelineno-0-616"></a><span class="sd"> the Track's media data, then do.</span>
</span><span id="__span-0-617"><a id="__codelineno-0-617" name="__codelineno-0-617"></a>
</span><span id="__span-0-618"><a id="__codelineno-0-618" name="__codelineno-0-618"></a><span class="sd"> :param title: The current `Title` from get_titles that is being executed.</span>
</span><span id="__span-0-618"><a id="__codelineno-0-618" name="__codelineno-0-618"></a><span class="sd"> :param title: The current `Title` from get_titles that unshackle processes now.</span>
</span><span id="__span-0-619"><a id="__codelineno-0-619" name="__codelineno-0-619"></a><span class="sd"> :return: Tracks object containing Video, Audio, Subtitles, and Chapters, if available.</span>
</span><span id="__span-0-620"><a id="__codelineno-0-620" name="__codelineno-0-620"></a><span class="sd"> """</span>
</span></code></pre></div></td></tr></table></div>
@@ -4241,7 +4241,7 @@ downloading any of the Track's stream data, then do.</p>
</td>
<td>
<div class="doc-md-description">
<p>The current Title from <code>get_titles</code> that is being processed.</p>
<p>The current Title from <code>get_titles</code> that unshackle processes now.</p>
</div>
</td>
<td>
@@ -4252,7 +4252,7 @@ downloading any of the Track's stream data, then do.</p>
</table>
<p>You must return a Chapters object containing 0 or more Chapter objects.</p>
<p>You do not need to set a Chapter number or sort/order the chapters in any way as
the Chapters class automatically handles all of that for you. If there's no
the Chapters class automatically handles all of that for you. If there is no
descriptive name for a Chapter then do not set a name at all.</p>
<p>You must not set Chapter names to "Chapter {n}" or such. If you (or the user)
wants "Chapter {n}" style Chapter names (or similar) then they can use the config
@@ -4284,12 +4284,12 @@ option <code>chapter_fallback_name</code>. For example, <code>"Chapter {i:02}"</
</span><span id="__span-0-625"><a id="__codelineno-0-625" name="__codelineno-0-625"></a><span class="sd"> Get Chapters for the Title.</span>
</span><span id="__span-0-626"><a id="__codelineno-0-626" name="__codelineno-0-626"></a>
</span><span id="__span-0-627"><a id="__codelineno-0-627" name="__codelineno-0-627"></a><span class="sd"> Parameters:</span>
</span><span id="__span-0-628"><a id="__codelineno-0-628" name="__codelineno-0-628"></a><span class="sd"> title: The current Title from `get_titles` that is being processed.</span>
</span><span id="__span-0-628"><a id="__codelineno-0-628" name="__codelineno-0-628"></a><span class="sd"> title: The current Title from `get_titles` that unshackle processes now.</span>
</span><span id="__span-0-629"><a id="__codelineno-0-629" name="__codelineno-0-629"></a>
</span><span id="__span-0-630"><a id="__codelineno-0-630" name="__codelineno-0-630"></a><span class="sd"> You must return a Chapters object containing 0 or more Chapter objects.</span>
</span><span id="__span-0-631"><a id="__codelineno-0-631" name="__codelineno-0-631"></a>
</span><span id="__span-0-632"><a id="__codelineno-0-632" name="__codelineno-0-632"></a><span class="sd"> You do not need to set a Chapter number or sort/order the chapters in any way as</span>
</span><span id="__span-0-633"><a id="__codelineno-0-633" name="__codelineno-0-633"></a><span class="sd"> the Chapters class automatically handles all of that for you. If there's no</span>
</span><span id="__span-0-633"><a id="__codelineno-0-633" name="__codelineno-0-633"></a><span class="sd"> the Chapters class automatically handles all of that for you. If there is no</span>
</span><span id="__span-0-634"><a id="__codelineno-0-634" name="__codelineno-0-634"></a><span class="sd"> descriptive name for a Chapter then do not set a name at all.</span>
</span><span id="__span-0-635"><a id="__codelineno-0-635" name="__codelineno-0-635"></a>
</span><span id="__span-0-636"><a id="__codelineno-0-636" name="__codelineno-0-636"></a><span class="sd"> You must not set Chapter names to "Chapter {n}" or such. If you (or the user)</span>
@@ -4354,7 +4354,7 @@ option <code>chapter_fallback_name</code>. For example, <code>"Chapter {i:02}"</
</td>
<td>
<div class="doc-md-description">
<p>The Path to the Segment that was downloaded.</p>
<p>The Path to the downloaded Segment.</p>
</div>
</td>
<td>
@@ -4380,7 +4380,7 @@ option <code>chapter_fallback_name</code>. For example, <code>"Chapter {i:02}"</
</span><span id="__span-0-646"><a id="__codelineno-0-646" name="__codelineno-0-646"></a>
</span><span id="__span-0-647"><a id="__codelineno-0-647" name="__codelineno-0-647"></a><span class="sd"> Parameters:</span>
</span><span id="__span-0-648"><a id="__codelineno-0-648" name="__codelineno-0-648"></a><span class="sd"> track: The Track object that had a Segment downloaded.</span>
</span><span id="__span-0-649"><a id="__codelineno-0-649" name="__codelineno-0-649"></a><span class="sd"> segment: The Path to the Segment that was downloaded.</span>
</span><span id="__span-0-649"><a id="__codelineno-0-649" name="__codelineno-0-649"></a><span class="sd"> segment: The Path to the downloaded Segment.</span>
</span><span id="__span-0-650"><a id="__codelineno-0-650" name="__codelineno-0-650"></a><span class="sd"> """</span>
</span></code></pre></div></td></tr></table></div>
</details>
@@ -4424,7 +4424,7 @@ option <code>chapter_fallback_name</code>. For example, <code>"Chapter {i:02}"</
</td>
<td>
<div class="doc-md-description">
<p>The Track object that was downloaded.</p>
<p>The downloaded Track object.</p>
</div>
</td>
<td>
@@ -4448,7 +4448,7 @@ option <code>chapter_fallback_name</code>. For example, <code>"Chapter {i:02}"</
</span><span id="__span-0-654"><a id="__codelineno-0-654" name="__codelineno-0-654"></a><span class="sd"> Called when a Track has finished downloading.</span>
</span><span id="__span-0-655"><a id="__codelineno-0-655" name="__codelineno-0-655"></a>
</span><span id="__span-0-656"><a id="__codelineno-0-656" name="__codelineno-0-656"></a><span class="sd"> Parameters:</span>
</span><span id="__span-0-657"><a id="__codelineno-0-657" name="__codelineno-0-657"></a><span class="sd"> track: The Track object that was downloaded.</span>
</span><span id="__span-0-657"><a id="__codelineno-0-657" name="__codelineno-0-657"></a><span class="sd"> track: The downloaded Track object.</span>
</span><span id="__span-0-658"><a id="__codelineno-0-658" name="__codelineno-0-658"></a><span class="sd"> """</span>
</span></code></pre></div></td></tr></table></div>
</details>
@@ -4492,7 +4492,7 @@ option <code>chapter_fallback_name</code>. For example, <code>"Chapter {i:02}"</
</td>
<td>
<div class="doc-md-description">
<p>The Track object that was decrypted.</p>
<p>The decrypted Track object.</p>
</div>
</td>
<td>
@@ -4524,7 +4524,7 @@ option <code>chapter_fallback_name</code>. For example, <code>"Chapter {i:02}"</
</td>
<td>
<div class="doc-md-description">
<p>The HLS segment information that was decrypted.</p>
<p>The decrypted HLS segment information.</p>
</div>
</td>
<td>
@@ -4550,9 +4550,9 @@ option <code>chapter_fallback_name</code>. For example, <code>"Chapter {i:02}"</
</span><span id="__span-0-662"><a id="__codelineno-0-662" name="__codelineno-0-662"></a><span class="sd"> Called when a Track has finished decrypting.</span>
</span><span id="__span-0-663"><a id="__codelineno-0-663" name="__codelineno-0-663"></a>
</span><span id="__span-0-664"><a id="__codelineno-0-664" name="__codelineno-0-664"></a><span class="sd"> Parameters:</span>
</span><span id="__span-0-665"><a id="__codelineno-0-665" name="__codelineno-0-665"></a><span class="sd"> track: The Track object that was decrypted.</span>
</span><span id="__span-0-665"><a id="__codelineno-0-665" name="__codelineno-0-665"></a><span class="sd"> track: The decrypted Track object.</span>
</span><span id="__span-0-666"><a id="__codelineno-0-666" name="__codelineno-0-666"></a><span class="sd"> drm: The DRM object it decrypted with.</span>
</span><span id="__span-0-667"><a id="__codelineno-0-667" name="__codelineno-0-667"></a><span class="sd"> segment: The HLS segment information that was decrypted.</span>
</span><span id="__span-0-667"><a id="__codelineno-0-667" name="__codelineno-0-667"></a><span class="sd"> segment: The decrypted HLS segment information.</span>
</span><span id="__span-0-668"><a id="__codelineno-0-668" name="__codelineno-0-668"></a><span class="sd"> """</span>
</span></code></pre></div></td></tr></table></div>
</details>
@@ -4596,7 +4596,7 @@ option <code>chapter_fallback_name</code>. For example, <code>"Chapter {i:02}"</
</td>
<td>
<div class="doc-md-description">
<p>The Track object that was repacked.</p>
<p>The repacked Track object.</p>
</div>
</td>
<td>
@@ -4620,7 +4620,7 @@ option <code>chapter_fallback_name</code>. For example, <code>"Chapter {i:02}"</
</span><span id="__span-0-672"><a id="__codelineno-0-672" name="__codelineno-0-672"></a><span class="sd"> Called when a Track has finished repacking.</span>
</span><span id="__span-0-673"><a id="__codelineno-0-673" name="__codelineno-0-673"></a>
</span><span id="__span-0-674"><a id="__codelineno-0-674" name="__codelineno-0-674"></a><span class="sd"> Parameters:</span>
</span><span id="__span-0-675"><a id="__codelineno-0-675" name="__codelineno-0-675"></a><span class="sd"> track: The Track object that was repacked.</span>
</span><span id="__span-0-675"><a id="__codelineno-0-675" name="__codelineno-0-675"></a><span class="sd"> track: The repacked Track object.</span>
</span><span id="__span-0-676"><a id="__codelineno-0-676" name="__codelineno-0-676"></a><span class="sd"> """</span>
</span></code></pre></div></td></tr></table></div>
</details>
@@ -4641,10 +4641,10 @@ option <code>chapter_fallback_name</code>. For example, <code>"Chapter {i:02}"</
<div class="doc doc-contents ">
<p>Called when a Track is about to be Multiplexed into a Container.</p>
<p>Note: Right now only MKV containers are multiplexed but in the future
this may also be called when multiplexing to other containers like
MP4 via ffmpeg/mp4box.</p>
<p>Called immediately before unshackle multiplexes a Track into a Container.</p>
<p>Note: Right now unshackle multiplexes only MKV containers. In the future
unshackle can also call this when it multiplexes to other containers like
MP4 with FFmpeg/mp4box.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -4667,7 +4667,7 @@ MP4 via ffmpeg/mp4box.</p>
</td>
<td>
<div class="doc-md-description">
<p>The Track object that was repacked.</p>
<p>The repacked Track object.</p>
</div>
</td>
<td>
@@ -4692,14 +4692,14 @@ MP4 via ffmpeg/mp4box.</p>
<span class="normal"><a href="#__codelineno-0-687">687</a></span>
<span class="normal"><a href="#__codelineno-0-688">688</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-678"><a id="__codelineno-0-678" name="__codelineno-0-678"></a><span class="k">def</span><span class="w"> </span><span class="nf">on_track_multiplex</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">track</span><span class="p">:</span> <span class="n">AnyTrack</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
</span><span id="__span-0-679"><a id="__codelineno-0-679" name="__codelineno-0-679"></a><span class="w"> </span><span class="sd">"""</span>
</span><span id="__span-0-680"><a id="__codelineno-0-680" name="__codelineno-0-680"></a><span class="sd"> Called when a Track is about to be Multiplexed into a Container.</span>
</span><span id="__span-0-680"><a id="__codelineno-0-680" name="__codelineno-0-680"></a><span class="sd"> Called immediately before unshackle multiplexes a Track into a Container.</span>
</span><span id="__span-0-681"><a id="__codelineno-0-681" name="__codelineno-0-681"></a>
</span><span id="__span-0-682"><a id="__codelineno-0-682" name="__codelineno-0-682"></a><span class="sd"> Note: Right now only MKV containers are multiplexed but in the future</span>
</span><span id="__span-0-683"><a id="__codelineno-0-683" name="__codelineno-0-683"></a><span class="sd"> this may also be called when multiplexing to other containers like</span>
</span><span id="__span-0-684"><a id="__codelineno-0-684" name="__codelineno-0-684"></a><span class="sd"> MP4 via ffmpeg/mp4box.</span>
</span><span id="__span-0-682"><a id="__codelineno-0-682" name="__codelineno-0-682"></a><span class="sd"> Note: Right now unshackle multiplexes only MKV containers. In the future</span>
</span><span id="__span-0-683"><a id="__codelineno-0-683" name="__codelineno-0-683"></a><span class="sd"> unshackle can also call this when it multiplexes to other containers like</span>
</span><span id="__span-0-684"><a id="__codelineno-0-684" name="__codelineno-0-684"></a><span class="sd"> MP4 with FFmpeg/mp4box.</span>
</span><span id="__span-0-685"><a id="__codelineno-0-685" name="__codelineno-0-685"></a>
</span><span id="__span-0-686"><a id="__codelineno-0-686" name="__codelineno-0-686"></a><span class="sd"> Parameters:</span>
</span><span id="__span-0-687"><a id="__codelineno-0-687" name="__codelineno-0-687"></a><span class="sd"> track: The Track object that was repacked.</span>
</span><span id="__span-0-687"><a id="__codelineno-0-687" name="__codelineno-0-687"></a><span class="sd"> track: The repacked Track object.</span>
</span><span id="__span-0-688"><a id="__codelineno-0-688" name="__codelineno-0-688"></a><span class="sd"> """</span>
</span></code></pre></div></td></tr></table></div>
</details>
@@ -4729,7 +4729,7 @@ MP4 via ffmpeg/mp4box.</p>
<div class="doc doc-contents ">
<p>Sanitize a proxy URI for logs by redacting any embedded userinfo (username/password).</p>
<p>Sanitise a proxy URI for logs by redacting any embedded userinfo (username/password).</p>
<p><span class="doc-section-title">Examples:</span></p>
@@ -4779,7 +4779,7 @@ MP4 via ffmpeg/mp4box.</p>
<span class="normal"><a href="#__codelineno-0-136">136</a></span>
<span class="normal"><a href="#__codelineno-0-137">137</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-101"><a id="__codelineno-0-101" name="__codelineno-0-101"></a><span class="k">def</span><span class="w"> </span><span class="nf">sanitize_proxy_for_log</span><span class="p">(</span><span class="n">uri</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
</span><span id="__span-0-102"><a id="__codelineno-0-102" name="__codelineno-0-102"></a><span class="w"> </span><span class="sd">"""</span>
</span><span id="__span-0-103"><a id="__codelineno-0-103" name="__codelineno-0-103"></a><span class="sd"> Sanitize a proxy URI for logs by redacting any embedded userinfo (username/password).</span>
</span><span id="__span-0-103"><a id="__codelineno-0-103" name="__codelineno-0-103"></a><span class="sd"> Sanitise a proxy URI for logs by redacting any embedded userinfo (username/password).</span>
</span><span id="__span-0-104"><a id="__codelineno-0-104" name="__codelineno-0-104"></a>
</span><span id="__span-0-105"><a id="__codelineno-0-105" name="__codelineno-0-105"></a><span class="sd"> Examples:</span>
</span><span id="__span-0-106"><a id="__codelineno-0-106" name="__codelineno-0-106"></a><span class="sd"> - http://user:pass@host:8080 -&gt; http://REDACTED@host:8080</span>
+2 -2
View File
@@ -2523,7 +2523,7 @@ takes every part. A dated episode also answers to its ISO air date.
<div class="doc doc-contents ">
<p>Season folder label: air year for dated content, else SxxExx-style season.</p>
<p>Season folder label: air year when the air date parsed to a date, else SxxExx-style season.</p>
</div>
@@ -2833,7 +2833,7 @@ takes every part. A dated episode also answers to its ISO air date.
<p>Whether a parsed <code>-w</code> key set selects this song.</p>
<p>A song shares the episode key space, its disc reading as the season and its track
as the episode, so <code>-w 1-5</code> takes tracks 1 to 5 and <code>-w 2x3</code> takes disc 2
track 3. A song has no parts and no air date, so it answers to one key only.</p>
track 3. A song has no parts and no air date, so it answers to its disc-and-track key only.</p>
</div>
+176 -171
View File
@@ -3943,10 +3943,10 @@
<p>Create a new Attachment.</p>
<p>Make a new Attachment.</p>
<p>If providing a path, the file must already exist.
If providing a URL, download() fetches the file during the download phase.
Either path or url must be provided.</p>
You must give either path or url.</p>
<p>If name is not provided it will use the file name (without extension).
If mime_type is not provided, it will try to guess it.</p>
@@ -4051,7 +4051,7 @@ If mime_type is not provided, it will try to guess it.</p>
</td>
<td>
<div class="doc-md-description">
<p>Optional requests session to use for downloading.</p>
<p>Optional requests HTTP session to download the file with.</p>
</div>
</td>
<td>
@@ -4169,7 +4169,7 @@ If mime_type is not provided, it will try to guess it.</p>
<div class="doc doc-contents ">
<p>Create an attachment from a URL.</p>
<p>Make an attachment from a URL.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -4256,7 +4256,7 @@ If mime_type is not provided, it will try to guess it.</p>
</td>
<td>
<div class="doc-md-description">
<p>Optional requests session to use for downloading.</p>
<p>Optional requests HTTP session to download the file with.</p>
</div>
</td>
<td>
@@ -4328,7 +4328,7 @@ If mime_type is not provided, it will try to guess it.</p>
<p>Create a new Audio track object.</p>
<p>Make a new Audio track object.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -4352,8 +4352,8 @@ If mime_type is not provided, it will try to guess it.</p>
<td>
<div class="doc-md-description">
<p>An Audio.Codec enum representing the audio codec.
If not specified, MediaInfo will be used to retrieve the codec
once the track has been downloaded.</p>
If not specified, unshackle uses MediaInfo to get the codec
after it downloads the track.</p>
</div>
</td>
<td>
@@ -4370,7 +4370,7 @@ once the track has been downloaded.</p>
<td>
<div class="doc-md-description">
<p>A number or float representing the average bandwidth in bits/s.
Float values are rounded up to the nearest integer.</p>
unshackle rounds float values up to the nearest integer.</p>
</div>
</td>
<td>
@@ -4404,7 +4404,7 @@ not supported. All numbers and strings will be cast to float.</p>
</td>
<td>
<div class="doc-md-description">
<p>The number of Joint-Object-Coding Channels/Objects in the audio stream.</p>
<p>The number of Joint-Object-Coding Channels/Objects in the audio track.</p>
</div>
</td>
<td>
@@ -4469,7 +4469,7 @@ recommended.</p>
<div class="doc doc-contents ">
<p>Return True if the audio track contains Dolby Atmos.</p>
<p>Return True if the audio track contains Atmos.</p>
</div>
@@ -4495,11 +4495,11 @@ recommended.</p>
<div class="doc doc-contents ">
<p>Converts a Channel string to a float representing audio channel count and layout.
<p>Converts a Channel string to a float representing the audio channel layout.
E.g. "3" -&gt; "3.0", "2.1" -&gt; "2.1", ".1" -&gt; "0.1".</p>
<p>This does not validate channel strings as genuine channel counts or valid layouts.
It does not convert the value to assume a sub speaker channel layout, e.g. 5.1-&gt;6.0.
It also does not support expanded surround sound channel layout strings like 7.1.2.</p>
It also cannot read expanded surround sound channel layout strings like 7.1.2.</p>
</div>
@@ -4550,14 +4550,14 @@ It also does not support expanded surround sound channel layout strings like 7.1
<p>Create a new Chapter with a Timestamp and optional name.</p>
<p>Make a new Chapter with a Timestamp and optional name.</p>
<p>The timestamp may be in the following formats:
- "HH:MM:SS" string, e.g., <code>25:05:23</code>.
- "HH:MM:SS.mss" string, e.g., <code>25:05:23.120</code>.
- a timecode integer in milliseconds, e.g., <code>90323120</code> is <code>25:05:23.120</code>.
- a timecode float in seconds, e.g., <code>90323.12</code> is <code>25:05:23.120</code>.</p>
<p>If you have a timecode integer in seconds, just multiply it by 1000.
If you have a timecode float in milliseconds (no decimal value), just convert
<p>If you have a timecode integer in seconds, multiply it by 1000.
If you have a timecode float in milliseconds (no decimal value), convert
it to an integer.</p>
@@ -4620,7 +4620,7 @@ it to an integer.</p>
<div class="doc doc-contents ">
<p>Check if Chapter is named.</p>
<p>True if the Chapter has a name.</p>
</div>
@@ -4801,7 +4801,7 @@ https://mkvtoolnix.download/doc/mkvmerge.html#mkvmerge.chapters.simple</p>
<li>{j}: A number starting at 1 that increments any time a Chapter has no name.
E.g., <code>"Chapter {j}"</code>: "Chapter 1", "Intro", "Chapter 2".</li>
</ul>
<p>These are formatted with f-strings, directives are supported.
<p>unshackle formats these with f-strings, so format directives work.
For example, <code>"Chapter {i:02}"</code> will result in <code>"Chapter 01"</code>.</p>
@@ -4946,7 +4946,7 @@ If no DV track is available but HDR10+ is present, it will convert HDR10+ to DV.
<div class="doc doc-contents ">
<p>Generate Level 5 active area metadata via crop detection on the HDR10 stream.</p>
<p>Make Level 5 active area metadata through crop detection on the HDR10 track.</p>
<p>This resolves mismatches where DV has no black bars but HDR10 does (or vice versa)
by telling the display the correct active area.</p>
@@ -4975,7 +4975,7 @@ by telling the display the correct active area.</p>
<p>Clamp static L6 values to a valid relationship.</p>
<p>MaxCLL must not exceed the mastering-display peak (some HDR10+ sources ship
MaxCLL 10000 on a 1000-nit master), and MaxFALL must not exceed
MaxCLL. A value of 0 means "unknown" and is preserved as-is.</p>
MaxCLL. A value of 0 means "unknown", and this method keeps it as-is.</p>
</div>
@@ -5015,7 +5015,7 @@ MaxCLL. A value of 0 means "unknown" and is preserved as-is.</p>
<div class="doc doc-contents ">
<p>Extract HDR10+ metadata from the video stream</p>
<p>Extract HDR10+ metadata from the video track</p>
</div>
@@ -5035,7 +5035,7 @@ MaxCLL. A value of 0 means "unknown" and is preserved as-is.</p>
<div class="doc doc-contents ">
<p>Extract mastering display and content light level metadata from the HDR10 stream via ffprobe.</p>
<p>Extract mastering display and Content Light Level metadata from the HDR10 track with FFprobe.</p>
<p>Returns (max_mdl, min_mdl, max_cll, max_fall) in dovi_tool level6 units:
- max_mdl: nits (integer)
- min_mdl: 0.0001 nit units (integer)
@@ -5099,7 +5099,7 @@ MaxCLL. A value of 0 means "unknown" and is preserved as-is.</p>
<p>Create a new Subtitle track object.</p>
<p>Make a new Subtitle track object.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -5123,8 +5123,8 @@ MaxCLL. A value of 0 means "unknown" and is preserved as-is.</p>
<td>
<div class="doc-md-description">
<p>A Subtitle.Codec enum representing the subtitle format.
If not specified, MediaInfo will be used to retrieve the format
once the track has been downloaded.</p>
If not specified, unshackle uses MediaInfo to get the format
after it downloads the track.</p>
</div>
</td>
<td>
@@ -5141,18 +5141,18 @@ once the track has been downloaded.</p>
<td>
<div class="doc-md-description">
<p>Closed Caption.
- Intended as if you couldn't hear the audio at all.
- Can have Sound as well as Dialogue, but doesn't have to.
- Original source would be from an EIA-CC encoded stream. Typically all
- Intended as if you could not hear the audio at all.
- Can have Sound as well as Dialogue, but does not have to.
- Original source would be from EIA-CC encoded video. Typically all
upper-case characters.
Indicators of it being CC without knowing original source:
- Extracted with CCExtractor, or
- &gt;&gt;&gt; (or similar) being used at the start of some or all lines, or
- &gt;&gt;&gt; (or similar) at the start of some or all lines, or
- All text is uppercase or at least the majority, or
- Subtitles are Scrolling-text style (one line appears, oldest line
then disappears).
Just because you downloaded it as a SRT or VTT or such, doesn't mean it
isn't from an EIA-CC stream. And I wouldn't take the streaming services
- Subtitles use the scrolling-text style (one line appears, oldest
line then disappears).
The fact that you downloaded it as a SRT or VTT or such does not mean it
is not from an EIA-CC stream. And I would not take the streaming services
(CC) as gospel either as they tend to get it wrong too.</p>
</div>
</td>
@@ -5170,15 +5170,16 @@ Just because you downloaded it as a SRT or VTT or such, doesn't mean it
<td>
<div class="doc-md-description">
<p>Deaf or Hard-of-Hearing. Also known as HOH in the UK (EU?).
- Intended as if you couldn't hear the audio at all.
- MUST have Sound as well as Dialogue to be considered SDH.
- It has no "syntax" or "format" but is not transmitted using archaic
forms like EIA-CC streams, would be intended for transmission via
SubRip (SRT), WebVTT (VTT), TTML, etc.
If you can see important audio/sound transcriptions and not just dialogue
and it doesn't have the indicators of CC, then it's most likely SDH.
If it doesn't have important audio/sounds transcriptions it might just be
regular subtitling (you wouldn't mark as CC or SDH). This would be the
- Intended as if you could not hear the audio at all.
- MUST have Sound as well as Dialogue to count as SDH.
- It has no "syntax" or "format", but it is not transmitted in
archaic forms like EIA-CC streams. It is intended for transmission
through SubRip (SRT), WebVTT (VTT), TTML, and the other modern
subtitle formats.
If you can see important audio/sound transcriptions and not only dialogue
and it does not have the indicators of CC, then it is most likely SDH.
If it does not have important audio/sounds transcriptions it might only be
regular subtitling (you would not mark as CC or SDH). This would be the
case for most translation subtitles. Like Anime for example.</p>
</div>
</td>
@@ -5195,15 +5196,15 @@ Just because you downloaded it as a SRT or VTT or such, doesn't mean it
</td>
<td>
<div class="doc-md-description">
<p>Typically used if there's important information at some point in time
like watching Dubbed content and an important Sign or Letter is shown
<p>Typically used if there is important information at some point in time
like watching a Dubbed title and an important Sign or Letter is shown
or someone talking in a different language.
Forced tracks are recommended by the Matroska Spec to be played if
The Matroska Spec recommends that the player plays Forced tracks if
the player's current playback audio language matches a subtitle
marked as "forced".
However, that doesn't mean every player works like this but there is
However, that does not mean every player works like this but there is
no other way to reliably work with Forced subtitles where multiple
forced subtitles may be in the output file. Just know what to expect
forced subtitles may be in the output file. Know what to expect
with "forced" subtitles.</p>
</div>
</td>
@@ -5213,17 +5214,17 @@ Just because you downloaded it as a SRT or VTT or such, doesn't mean it
</tr>
</tbody>
</table>
<p>Note: If codec is not specified some checks may be skipped or assume a value.
Specifying as much information as possible is highly recommended.</p>
<p>Note: If codec is not specified, unshackle can skip some checks or assume a value.
Give as much information as possible.</p>
<details class="information-on-subtitle-types" open>
<summary>Information on Subtitle Types</summary>
<p>https://bit.ly/2Oe4fLC (3PlayMedia Blog on SUB vs CC vs SDH).
However, I wouldn't pay much attention to the claims about SDH needing to
be in the original source language. It's logically not true.</p>
<p>CC == Closed Captions. Source: Basically every site.
SDH = Subtitles for the Deaf or Hard-of-Hearing. Source: Basically every site.
However, I would not pay much attention to the claims about SDH needing to
be in the original language. It is logically not true.</p>
<p>CC == Closed Captions. Source: Every site.
SDH = Subtitles for the Deaf or Hard-of-Hearing. Source: Every site.
HOH = Exact same as SDH. Is a term used in the UK. Source: https://bit.ly/2PGJatz (ICO UK)</p>
<p>More in-depth information, examples, and stuff to look for can be found in the Parameter
explanation list above.</p>
@@ -5335,7 +5336,7 @@ every cue by it during conversion.</p>
</td>
<td>
<div class="doc-md-description">
<p>The WebVTT content as string</p>
<p>The WebVTT text as string</p>
</div>
</td>
<td>
@@ -5361,7 +5362,7 @@ every cue by it during conversion.</p>
</td>
<td>
<div class="doc-md-description">
<p>Sanitized WebVTT content</p>
<p>Sanitized WebVTT text</p>
</div>
</td>
</tr>
@@ -5390,7 +5391,7 @@ every cue by it during conversion.</p>
<div class="doc doc-contents ">
<p>Check if WebVTT content has cue identifiers that need removal.</p>
<p>Examine WebVTT text for cue identifiers that need removal.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -5413,7 +5414,7 @@ every cue by it during conversion.</p>
</td>
<td>
<div class="doc-md-description">
<p>The WebVTT content as string</p>
<p>The WebVTT text as string</p>
</div>
</td>
<td>
@@ -5439,7 +5440,7 @@ every cue by it during conversion.</p>
</td>
<td>
<div class="doc-md-description">
<p>True if cue identifiers are detected, False otherwise</p>
<p>True if the text has cue identifiers, False otherwise</p>
</div>
</td>
</tr>
@@ -5469,9 +5470,9 @@ every cue by it during conversion.</p>
<div class="doc doc-contents ">
<p>Remove WebVTT cue identifiers that can confuse subtitle parsers.</p>
<p>Some services use cue identifiers like "Q0", "Q1", etc.
<p>Some services use cue identifiers such as "Q0" and "Q1"
that appear on their own line before the timing line. These can be
incorrectly parsed as part of the previous cue's text content by
incorrectly parsed as part of the previous cue's text by
some parsers (like pysubs2).</p>
@@ -5495,7 +5496,7 @@ some parsers (like pysubs2).</p>
</td>
<td>
<div class="doc-md-description">
<p>The WebVTT content as string</p>
<p>The WebVTT text as string</p>
</div>
</td>
<td>
@@ -5521,7 +5522,7 @@ some parsers (like pysubs2).</p>
</td>
<td>
<div class="doc-md-description">
<p>Sanitized WebVTT content with cue identifiers removed</p>
<p>Sanitized WebVTT text with cue identifiers removed</p>
</div>
</td>
</tr>
@@ -5574,7 +5575,7 @@ some parsers (like pysubs2).</p>
<div class="doc doc-contents ">
<p>Check if WebVTT content has overlapping cues that need merging.</p>
<p>Examine WebVTT text for overlapping cues that need merging.</p>
<p>Detects cues with start times within 50ms of each other and the same end time,
which indicates multi-line subtitles split into separate cues.</p>
@@ -5599,7 +5600,7 @@ which indicates multi-line subtitles split into separate cues.</p>
</td>
<td>
<div class="doc-md-description">
<p>The WebVTT content as string</p>
<p>The WebVTT text as string</p>
</div>
</td>
<td>
@@ -5625,7 +5626,7 @@ which indicates multi-line subtitles split into separate cues.</p>
</td>
<td>
<div class="doc-md-description">
<p>True if overlapping cues are detected, False otherwise</p>
<p>True if the text has overlapping cues, False otherwise</p>
</div>
</td>
</tr>
@@ -5681,7 +5682,7 @@ line: position (lower percentage = higher on screen = first line).</p>
</td>
<td>
<div class="doc-md-description">
<p>The WebVTT content as string</p>
<p>The WebVTT text as string</p>
</div>
</td>
<td>
@@ -5707,7 +5708,7 @@ line: position (lower percentage = higher on screen = first line).</p>
</td>
<td>
<div class="doc-md-description">
<p>WebVTT content with overlapping cues merged</p>
<p>WebVTT text with overlapping cues merged</p>
</div>
</td>
</tr>
@@ -5736,10 +5737,11 @@ line: position (lower percentage = higher on screen = first line).</p>
<div class="doc doc-contents ">
<p>More thorough sanitization of WebVTT files to handle multiple potential issues.</p>
<p>This is lossy, so use it only as a fallback once normal parsing has failed. Everything before the
WEBVTT header line is discarded and the header itself is reduced to a bare "WEBVTT" line. Negative
timestamps become 00:00:00.000 and timestamps missing the hours field are padded to HH:MM:SS.mmm.</p>
<p>More thorough sanitization of WebVTT files that corrects multiple potential issues.</p>
<p>This is lossy, so use it only as a fallback once normal parsing has failed. This method discards
everything before the WEBVTT header line and reduces the header itself to a bare "WEBVTT" line.
Negative timestamps become 00:00:00.000, and it pads timestamps that have no hours field to
HH:MM:SS.mmm.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -5762,7 +5764,7 @@ timestamps become 00:00:00.000 and timestamps missing the hours field are padded
</td>
<td>
<div class="doc-md-description">
<p>The WebVTT content as string</p>
<p>The WebVTT text as string</p>
</div>
</td>
<td>
@@ -5788,7 +5790,7 @@ timestamps become 00:00:00.000 and timestamps missing the hours field are padded
</td>
<td>
<div class="doc-md-description">
<p>Sanitized WebVTT content</p>
<p>Sanitized WebVTT text</p>
</div>
</td>
</tr>
@@ -5814,14 +5816,14 @@ timestamps become 00:00:00.000 and timestamps missing the hours field are padded
<div class="doc doc-contents ">
<p>Convert this Subtitle to another format.</p>
<p>Backend selection is data-driven (see <code>tracks/subtitle_convert.py</code>): the best
available backend that supports source-&gt;target is used, falling back through the
capability chain on failure. The backend can be pinned via the <code>conversion_method</code>
config key (<code>auto</code> | <code>subby</code> | <code>pysubs2</code> | <code>subtitleedit</code> | <code>pycaption</code>),
or nudged per-service via <code>preferred_conversion_method</code>; an explicit config value
always wins.</p>
<p><code>forced</code> marks an explicit user request (<code>--sub-format</code>). Lossy downconverts of
styled formats (SSA/ASS -&gt; SRT) are skipped unless <code>forced</code> is True.</p>
<p>Backend selection is data-driven (see <code>tracks/subtitle_convert.py</code>): unshackle
uses the best available backend that can convert source-&gt;target, and falls back
through the capability chain on failure. The <code>conversion_method</code> config key
(<code>auto</code> | <code>subby</code> | <code>pysubs2</code> | <code>subtitleedit</code> | <code>pycaption</code>) pins the
backend, and <code>preferred_conversion_method</code> nudges it per-service. An explicit
config value always wins.</p>
<p><code>forced</code> marks an explicit user request (<code>--sub-format</code>). unshackle skips lossy
downconverts of styled formats (SSA/ASS -&gt; SRT) unless <code>forced</code> is True.</p>
</div>
@@ -5850,8 +5852,8 @@ styled formats (SSA/ASS -&gt; SRT) are skipped unless <code>forced</code> is Tru
- the <code>Fontname</code> column of every <code>Style:</code> line in <code>[V4+ Styles]</code>/<code>[V4 Styles]</code>
(column located from the section's <code>Format:</code> line, not assumed by index), and
- inline <code>\fn</code> font overrides inside <code>Dialogue</code> override blocks.</p>
<p>Leading <code>@</code> (vertical-writing prefix) is stripped and names are de-duplicated
case-insensitively, preferring a mixed-case spelling over an all-lowercase one.</p>
<p>This method removes a leading <code>@</code> (vertical-writing prefix), de-duplicates the
names case-insensitively, and prefers a mixed-case spelling over an all-lowercase one.</p>
</div>
@@ -5898,7 +5900,7 @@ case-insensitively, preferring a mixed-case spelling over an all-lowercase one.<
</td>
<td>
<div class="doc-md-description">
<p>The WebVTT content as string</p>
<p>The WebVTT text as string</p>
</div>
</td>
<td>
@@ -5924,7 +5926,7 @@ case-insensitively, preferring a mixed-case spelling over an all-lowercase one.<
</td>
<td>
<div class="doc-md-description">
<p>Sanitized WebVTT content with corrupted lines removed</p>
<p>Sanitized WebVTT text with corrupted lines removed</p>
</div>
</td>
</tr>
@@ -5956,7 +5958,7 @@ case-insensitively, preferring a mixed-case spelling over an all-lowercase one.<
<p>Space out the WEBVTT Headers from Captions.</p>
<p>Segmented VTT when merged may have the WEBVTT headers part of the next caption
as they were not separated far enough from the previous caption and ended up
being considered as caption text rather than the header for the next segment.</p>
as caption text rather than the header for the next segment.</p>
</div>
@@ -6029,9 +6031,9 @@ being considered as caption text rather than the header for the next segment.</p
<div class="doc doc-contents ">
<p>Convert Segmented DASH WebVTT cues into a pycaption Caption List.
Also returns an ISO 639-2 alpha-3 language code if available.</p>
Also returns an ISO 639-2 alpha-3 language tag if available.</p>
<p>Code ported originally by xhlove to Python from shaka-player.
Has since been improved upon by rlaphoenix using pymp4 and
rlaphoenix has since improved it with pymp4 and
pycaption functions.</p>
@@ -6052,8 +6054,8 @@ pycaption functions.</p>
<div class="doc doc-contents ">
<p>Strip captions for hearing impaired (SDH).</p>
<p>The SDH stripping method is determined by the 'sdh_method' setting in config:
<p>Remove the SDH captions.</p>
<p>The 'sdh_method' setting in config gives the SDH stripping method:
- 'auto' (default): Tries subby first, then SubtitleEdit, then filter-subs
- 'subby': Uses subby's SDHStripper
- 'subtitleedit': Uses SubtitleEdit when available
@@ -6078,7 +6080,7 @@ pycaption functions.</p>
<div class="doc doc-contents ">
<p>Reverse RTL (Right to Left) Start/End on Captions.
This can be used to fix the positioning of sentence-ending characters.</p>
Use this to fix the positioning of sentence-ending characters.</p>
</div>
@@ -6160,7 +6162,7 @@ This can be used to fix the positioning of sentence-ending characters.</p>
<div class="doc doc-contents ">
<p>Return the session, or a new <code>Session</code> if none was set.</p>
<p>Return the HTTP session, or a new <code>Session</code> if none was set.</p>
</div>
@@ -6245,7 +6247,7 @@ This can be used to fix the positioning of sentence-ending characters.</p>
<div class="doc doc-contents ">
<p>Arbitrary track data dictionary.</p>
<p>A defaultdict is used with a dict as the factory for easier
<p>This uses a defaultdict with a dict as the factory for easier
nested saving and safer exists-checks.</p>
<p>Reserved keys:</p>
<ul>
@@ -6262,8 +6264,8 @@ nested saving and safer exists-checks.</p>
<li>segment_durations: list[int] - A list of each segment's duration.</li>
</ul>
<p>You should not add, change, or remove any data within reserved keys.
You may use their data but do note that the values of them may change
or be removed at any point.</p>
You may use their data, but note that these values can change or be removed
at any point.</p>
</div>
@@ -6296,8 +6298,8 @@ or be removed at any point.</p>
<div class="doc doc-contents ">
<p>Download and optionally Decrypt this Track.</p>
<p>A URL-descriptor Video or Audio track with no <code>drm</code> set has its DRM probed from the init data of the
stream and stored on the track, so a service need not declare <code>drm</code> itself.</p>
<p>For a URL-descriptor Video or Audio track with no <code>drm</code> set, unshackle probes the DRM from the
track's init data and stores it on the track, so a service need not declare <code>drm</code> itself.</p>
</div>
@@ -6383,7 +6385,7 @@ This will overwrite anything at the target path.</p>
<div class="doc doc-contents ">
<p>Serialise the track for export/import (identity/URL/descriptor/language).</p>
<p>DRM is not serialised here; the export writer attaches the licensed DRM + keys.
<p>DRM is not serialised here. The export writer attaches the licensed DRM + keys.
Subclasses add their own codec/quality fields.</p>
@@ -6408,7 +6410,7 @@ Subclasses add their own codec/quality fields.</p>
<div class="doc doc-contents ">
<p>Build the shared Track constructor kwargs from a <code>to_dict()</code> payload.</p>
<p>Assemble the shared Track constructor kwargs from a <code>to_dict()</code> payload.</p>
<p>DRM is not reconstructed here: <code>to_dict</code> does not serialise it, and the import
flow attaches the licensed DRM + content keys separately.</p>
@@ -6495,15 +6497,15 @@ flow attaches the licensed DRM + content keys separately.</p>
<div class="doc doc-contents ">
<p>Probe the DRM encryption Key ID (KID) for this specific track.</p>
<p>It currently supports finding the Key ID by probing the track's stream
with ffprobe for <code>enc_key_id</code> data, as well as for mp4 <code>tenc</code> (Track
Encryption) boxes.</p>
<p>It can find the Key ID by probing the track with FFprobe for
<code>enc_key_id</code> data, as well as for mp4 <code>tenc</code> (Track Encryption)
boxes.</p>
<p>It explicitly ignores PSSH information like the <code>PSSH</code> box, as the box
is likely to contain multiple Key IDs that may or may not be for this
specific track.</p>
<p>To retrieve the initialization segment, this method calls :meth:<code>get_init_segment</code>
with the positional and keyword arguments. The return value of <code>get_init_segment</code>
is then used to determine the Key ID.</p>
with the positional and keyword arguments. This method then uses the return value
of <code>get_init_segment</code> to find the Key ID.</p>
<p><span class="doc-section-title">Returns:</span></p>
@@ -6521,7 +6523,7 @@ is then used to determine the Key ID.</p>
</td>
<td>
<div class="doc-md-description">
<p>The Key ID as a UUID object, or None if the Key ID could not be determined.</p>
<p>The Key ID as a UUID object, or None if unshackle cannot find the Key ID.</p>
</div>
</td>
</tr>
@@ -6546,7 +6548,7 @@ is then used to determine the Key ID.</p>
<div class="doc doc-contents ">
<p>Load DRM information for this track if it was deferred during parsing.</p>
<p>Load DRM information for this track if the parser deferred it.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -6595,7 +6597,7 @@ is then used to determine the Key ID.</p>
</td>
<td>
<div class="doc-md-description">
<p>True if DRM was loaded or already present, False if failed</p>
<p>True if the DRM loaded or is already present, False if the load failed</p>
</div>
</td>
</tr>
@@ -6645,11 +6647,11 @@ is then used to determine the Key ID.</p>
<div class="doc doc-contents ">
<p>Get the Track's Initial Segment Data Stream.</p>
<p>HLS and DASH tracks must explicitly provide a URL to the init segment or file.
Providing the byte-range for the init segment is recommended where possible.</p>
<p>If <code>byte_range</code> is not set, it will make a HEAD request and check the size of
the file. If the size could not be determined, it will download up to the first
<p>Get the Track's initial segment data.</p>
<p>HLS and DASH tracks must explicitly give a URL to the init segment or file.
Give the byte-range for the init segment where possible.</p>
<p>If <code>byte_range</code> is not set, it will make a HEAD request and examine the size of
the file. If it cannot find the size, it will download up to the first
20KB only, which should contain the entirety of the init segment. You may
override this by changing the <code>maximum_size</code>.</p>
<p>The default maximum_size of 20000 (20KB) is a tried-and-tested value that
@@ -6676,9 +6678,9 @@ seems to work well across the board.</p>
</td>
<td>
<div class="doc-md-description">
<p>Size to assume as the content length if byte-range is not
used, the content size could not be determined, or the content size
is larger than it. A value of 20000 (20KB) or higher is recommended.</p>
<p>Size to assume as the response body length if byte-range is
not used, if unshackle cannot find the body size, or if the body size
is larger than it. Use a value of 20000 (20KB) or higher.</p>
</div>
</td>
<td>
@@ -6726,7 +6728,7 @@ is larger than it. A value of 20000 (20KB) or higher is recommended.</p>
</td>
<td>
<div class="doc-md-description">
<p>Session context, e.g., authorization and headers.</p>
<p>HTTP session context, for example authorization and headers.</p>
</div>
</td>
<td>
@@ -6754,13 +6756,13 @@ is larger than it. A value of 20000 (20KB) or higher is recommended.</p>
<div class="doc doc-contents ">
<p>Remux the track with ffmpeg <code>-c copy</code>.</p>
<p>When <code>bsf_v</code> is given it is folded into the same pass as <code>-bsf:v</code> (used to
normalize video VUI colour metadata without a second full-file remux). Repackaging
is mandatory; the bitstream filter is best-effort. If the combined run fails (and it
isn't the AAC-retry case) it is retried once without <code>bsf_v</code> so the remux still
succeeds. Returns True if the requested <code>bsf_v</code> was applied (always False when
<code>bsf_v</code> is None, since nothing was requested).</p>
<p>Remux the track with FFmpeg <code>-c copy</code>.</p>
<p>A given <code>bsf_v</code> goes into the same pass as <code>-bsf:v</code>, which normalises video VUI
colour metadata without a second full-file remux. Repackaging is mandatory. The
bitstream filter is best-effort: if the combined pass fails, and it is not the
AAC-retry case, unshackle tries it again once without <code>bsf_v</code> so the remux still
succeeds. Returns True if unshackle applied the requested <code>bsf_v</code> (always False
when <code>bsf_v</code> is None, because the caller requested nothing).</p>
</div>
@@ -6828,7 +6830,7 @@ It provides convenience functions for listing, sorting, and selecting tracks.</p
<div class="doc doc-contents ">
<p>Check if a track already exists by various methods.</p>
<p>Examine whether a track already exists, by various methods.</p>
</div>
@@ -6848,7 +6850,9 @@ It provides convenience functions for listing, sorting, and selecting tracks.</p
<div class="doc doc-contents ">
<p>Add a provided track to its appropriate array and ensuring it's not a duplicate.</p>
<p>Add a provided track to its appropriate array.</p>
<p>A track whose ID is already in the collection raises ValueError. With <code>warn_only</code>
set, this method skips such a track and logs how many it skipped.</p>
</div>
@@ -6916,7 +6920,7 @@ It provides convenience functions for listing, sorting, and selecting tracks.</p
<div class="doc doc-contents ">
<p>Sort subtitle tracks by various track attributes to a common P2P standard.
You may optionally provide a sequence of languages to prioritize to the top.</p>
You may optionally give a sequence of languages to prioritise to the top.</p>
<details class="section-order" open>
@@ -6937,8 +6941,8 @@ You may optionally provide a sequence of languages to prioritize to the top.</p>
(Least to most captions expected in the subtitle)</li>
</ul>
</details> <p>type_priority overrides the Type Order with an explicit ranking of "forced",
"normal", and "sdh" (cc counts as sdh); unlisted types fall to the end.</p>
<p>group_by sets the major key. "type" (default) keeps every forced track together,
"normal", and "sdh" (cc counts as sdh). Unlisted types fall to the end.</p>
<p>group_by sets the major sort order. "type" (default) keeps every forced track together,
then every normal, then every SDH, each block ascending by language. "language"
groups by language instead, so Finnish sits next to Finnish SDH, with the Type
Order applied inside each language.</p>
@@ -6988,8 +6992,9 @@ sorts "en-US" and "en-GB".</p>
<div class="doc doc-contents ">
<p>Concatenate video selections, dropping duplicates (by track id, order-preserving).</p>
<p>A DV track can be chosen as both the hybrid ingredient (lowest) and an explicit
deliverable; without dedup the same track would be muxed/downloaded twice.</p>
<p>A caller can choose a DV track as both the hybrid ingredient (lowest) and an
explicit deliverable. Without dedup, unshackle would mux and download the same
track twice.</p>
</div>
@@ -7014,9 +7019,10 @@ deliverable; without dedup the same track would be muxed/downloaded twice.</p>
<div class="doc doc-contents ">
<p>Split videos into hybrid-ingredient candidates and the standalone-deliverable pool.</p>
<p>HDR10/HDR10+/DV tracks are hybrid ingredients; they only enter the standalone
pool when their range was explicitly requested alongside HYBRID, so e.g.
<code>-r HYBRID</code> muxes only the hybrid while <code>-r HYBRID,HDR10P</code> also delivers HDR10+.</p>
<p>HDR10/HDR10+/DV tracks are hybrid ingredients. They only enter the standalone
pool when the user explicitly requested their range alongside HYBRID, so for
example <code>-r HYBRID</code> muxes only the hybrid while <code>-r HYBRID,HDR10P</code> also delivers
HDR10+.</p>
</div>
@@ -7043,8 +7049,8 @@ pool when their range was explicitly requested alongside HYBRID, so e.g.
<div class="doc doc-contents ">
<p>Mark tracks selected only as hybrid ingredients so the standalone mux loop skips them.</p>
<p>A track that was also picked as an explicit deliverable (same track in both
selections) stays unflagged and is muxed standalone alongside the hybrid.</p>
<p>A track that the caller also selected as an explicit deliverable (same track in both
selections) stays unflagged, and the standalone mux loop muxes it alongside the hybrid.</p>
</div>
@@ -7074,7 +7080,7 @@ selections) stays unflagged and is muxed standalone alongside the hybrid.</p>
<p>Multiplex all the Tracks into a Matroska Container file.</p>
<p>A failed mux does not raise. mkvmerge's exit code and error lines come back alongside the
output path, and the caller must check them.</p>
output path, and the caller must examine them.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -7130,8 +7136,8 @@ instead of the filename if set.</p>
</td>
<td>
<div class="doc-md-description">
<p>Update a rich progress bar via <code>completed=...</code>. This must be the
progress object's update() func, pre-set with task id via functools.partial.</p>
<p>Update a rich progress bar with <code>completed=...</code>. This must be the
progress object's update() func, pre-set with task id by functools.partial.</p>
</div>
</td>
<td>
@@ -7147,8 +7153,8 @@ progress object's update() func, pre-set with task id via functools.partial.</p>
</td>
<td>
<div class="doc-md-description">
<p>Whether audio is expected in the output. Used to determine
if embedded audio metadata should be added.</p>
<p>Whether the output must have audio. unshackle uses this to
decide if it adds embedded audio metadata.</p>
</div>
</td>
<td>
@@ -7197,8 +7203,8 @@ for audio metadata when multiple video tracks exist.</p>
</td>
<td>
<div class="doc-md-description">
<p>Explicit destination for the muxed container. When None (default) the
path is derived from the first track, so callers muxing several track groups that
<p>Explicit destination for the muxed container. When None (default)
unshackle derives the path from the first track, so callers muxing several track groups that
share a video list must pass distinct paths to avoid clobbering each other.</p>
</div>
</td>
@@ -7252,7 +7258,7 @@ share a video list must pass distinct paths to avoid clobbering each other.</p>
<p>Create a new Video track object.</p>
<p>Make a new Video track object.</p>
<p><span class="doc-section-title">Parameters:</span></p>
@@ -7276,8 +7282,8 @@ share a video list must pass distinct paths to avoid clobbering each other.</p>
<td>
<div class="doc-md-description">
<p>A Video.Codec enum representing the video codec.
If not specified, MediaInfo will be used to retrieve the codec
once the track has been downloaded.</p>
If not specified, unshackle uses MediaInfo to get the codec
after it downloads the track.</p>
</div>
</td>
<td>
@@ -7293,7 +7299,7 @@ once the track has been downloaded.</p>
</td>
<td>
<div class="doc-md-description">
<p>A Video.Range enum representing the video color range.
<p>A Video.Range enum representing the video colour range.
Defaults to SDR if not specified.</p>
</div>
</td>
@@ -7311,7 +7317,7 @@ Defaults to SDR if not specified.</p>
<td>
<div class="doc-md-description">
<p>A number or float representing the average bandwidth in bytes/s.
Float values are rounded up to the nearest integer.</p>
unshackle rounds float values up to the nearest integer.</p>
</div>
</td>
<td>
@@ -7370,9 +7376,8 @@ All strings will be cast to either a number or float.</p>
</tr>
</tbody>
</table>
<p>Note: If codec, bitrate, width, height, or fps is not specified some checks
may be skipped or assume a value. Specifying as much information as possible
is highly recommended.</p>
<p>Note: If codec, bitrate, width, height, or fps is not specified, unshackle can
skip some checks or assume a value. Give as much information as possible.</p>
@@ -7450,18 +7455,18 @@ is highly recommended.</p>
<div class="doc doc-contents ">
<p>Convert CICP (Coding-Independent Code Points) values to Video Range.</p>
<p>CICP is defined in ITU-T H.273 and ISO/IEC 23091-2 for signaling video
color properties independently of the compression codec. These values are
<p>ITU-T H.273 and ISO/IEC 23091-2 define CICP for signalling video
colour properties independently of the compression codec. These values are
used across AVC (H.264), HEVC (H.265), VVC, AV1, and other modern codecs.</p>
<p>The enum values (Primaries, Transfer, Matrix) match the official specifications:
- ITU-T H.273: Coding-independent code points for video signal type identification
- ISO/IEC 23091-2: Information technology — Coding-independent code points — Part 2: Video
- ISO/IEC 23091-2: Information technology - Coding-independent code points - Part 2: Video
- H.264 Table E-3 (Colour Primaries) and Table E-4 (Transfer Characteristics)
- H.265 Table E.3 and E.4 (identical to H.264)</p>
<p>Note: Value 0 = "Reserved" and Value 2 = "Unspecified" per specification.
While both effectively mean "unknown" in practice, the distinction matters for
spec compliance. Value 2 was added based on user feedback (GitHub issue) and
verified against FFmpeg's AVColorPrimaries/AVColorTransferCharacteristic enums.</p>
spec compliance. Value 2 was added after user feedback (GitHub issue) and matches
FFmpeg's AVColorPrimaries/AVColorTransferCharacteristic enums.</p>
<p>Sources:
- https://www.itu.int/rec/T-REC-H.273
- https://www.itu.int/rec/T-REC-H.Sup19-202104-I
@@ -7494,7 +7499,7 @@ verified against FFmpeg's AVColorPrimaries/AVColorTransferCharacteristic enums.<
<div class="doc doc-contents ">
<p>Change the Video's Color Range to Limited (0) or Full (1).</p>
<p>Change the Video's Colour Range to Limited (0) or Full (1).</p>
</div>
@@ -7515,9 +7520,9 @@ verified against FFmpeg's AVColorPrimaries/AVColorTransferCharacteristic enums.<
<div class="doc doc-contents ">
<p>Return the <code>-bsf:v</code> value that rewrites SPS VUI colour metadata to match <code>self.range</code>.</p>
<p>Returns None when no rewrite is needed: SDR/DV/HYBRID ranges, non-AVC/HEVC codecs, a
<p>Returns None when a rewrite is not necessary: SDR/DV/HYBRID ranges, non-AVC/HEVC codecs, a
missing file, or when the bitstream already ships the correct colour metadata. Otherwise
returns a <code>{h264,hevc}_metadata=...</code> string suitable for ffmpeg <code>-bsf:v</code>.</p>
returns a <code>{h264,hevc}_metadata=...</code> string suitable for FFmpeg <code>-bsf:v</code>.</p>
</div>
@@ -7540,8 +7545,8 @@ returns a <code>{h264,hevc}_metadata=...</code> string suitable for ffmpeg <code
<p>Rewrite SPS VUI colour metadata to match <code>self.range</code>.</p>
<p>Some services ship HDR10/HLG bitstreams with stale BT.709 VUI, which makes
downstream tools mis-classify the file. The manifest-derived range is the
source of truth. Skips SDR, DV, and HYBRID. Returns True if the bitstream
was rewritten.</p>
source of truth. Skips SDR, DV, and HYBRID. Returns True if unshackle rewrote
the bitstream.</p>
</div>
@@ -7581,19 +7586,19 @@ was rewritten.</p>
<div class="doc doc-contents ">
<p>Extract Apple-Style c608 box (CEA-608) subtitle using ccextractor.</p>
<p>This isn't much more than a wrapper to the track.ccextractor function.
All this does, is actually check if a c608 box exists and only if so
does it actually call ccextractor.</p>
<p>Even though there is a possibility of more than one c608 box, only one
can actually be extracted. It is also very possible this
<p>Extract Apple-Style c608 box (CEA-608) subtitle using CCExtractor.</p>
<p>This is not much more than a wrapper to the track.ccextractor function.
All this does is examine if a c608 box exists, and only then
does it call CCExtractor.</p>
<p>Even though there is a possibility of more than one c608 box, unshackle
can extract only one. It is also very possible this
needs to be done before any decryption as the decryption may destroy
some of the metadata.</p>
<details class="todo" open>
<summary>Need a test file with more than one c608 box to add support for</summary>
<p>more than one CEA-608 extraction.</p>
<summary>Need a test file with more than one c608 box, before unshackle can</summary>
<p>extract more than one CEA-608 track.</p>
</details>
</div>
@@ -7615,9 +7620,9 @@ some of the metadata.</p>
<p>Remove EIA-CC data from Bitstream while keeping SEI data.</p>
<p>This works by removing all NAL Unit's with the Type of 6 from the bistream
and then re-adding SEI data (effectively a new NAL Unit with just the SEI data).
Only bitstreams with x264 encoding information is currently supported due to the
obscurity on the MDAT mp4 box structure. Therefore, we need to use hacky regex.</p>
and then re-adding SEI data (effectively a new NAL Unit with only the SEI data).
unshackle can do this only for bitstreams with x264 encoding information, because of
the obscurity on the MDAT mp4 box structure. Therefore, we need to use hacky regex.</p>
</div>
+15 -15
View File
@@ -1975,11 +1975,11 @@
<h1 id="directories">Directories<a class="headerlink" href="#directories" title="Permanent link">&para;</a></h1>
<p>The <code>directories</code> key is a <strong>dict</strong> mapping directory names to filesystem paths. Only the
names listed below are honoured; a handful are <strong>protected</strong> and cannot be moved (attempts
to override them are silently skipped). All defaults are computed relative to the installed
package, and every user-settable path is passed through <code>Path(...).expanduser()</code>, so <code>~</code>
works.</p>
<p>The <code>directories</code> config key is a <strong>dict</strong> mapping directory names to filesystem paths.
unshackle honours only the names listed below. A handful are <strong>protected</strong> and you cannot
move them, and unshackle silently ignores an override of one. unshackle computes all
defaults relative to the installed package, and passes every user-settable path through
<code>Path(...).expanduser()</code>, so <code>~</code> works.</p>
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nt">directories</span><span class="p">:</span>
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w"> </span><span class="nt">downloads</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">~/Media/unshackle</span>
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="w"> </span><span class="nt">temp</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/mnt/fast-scratch/unshackle-temp</span>
@@ -2129,9 +2129,9 @@ works.</p>
<p class="admonition-title">The <code>services</code> directory is special</p>
<p><code>services</code> may be a <strong>list</strong>, and each entry can be either a local directory or a
<strong>repository spec</strong>: a git URL (<code>https://...</code>, <code>ssh://...</code>, <code>git@...</code>, or anything ending in
<code>.git</code>) or <code>owner/repo</code> shorthand. Repo specs are cloned and updated automatically; plain
paths are used as-is. <strong>List order is priority</strong>: the first source to define a service
tag wins.</p>
<code>.git</code>) or <code>owner/repo</code> shorthand. unshackle clones and updates repo specs automatically,
and uses plain paths as they are. <strong>List order is priority</strong>: the first source to define a
service tag wins.</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">directories</span><span class="p">:</span>
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span>
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">you/your-services</span><span class="w"> </span><span class="c1"># cloned from GitHub</span>
@@ -2141,11 +2141,11 @@ tag wins.</p>
</div>
<div class="admonition info">
<p class="admonition-title">How git-backed service repos are handled</p>
<p>unshackle's use of git is <strong>read-only on the remote</strong>: it only ever performs a shallow
<code>clone</code>, <code>fetch</code>, <code>pull</code>, and a local <code>reset</code>; <strong>nothing is ever pushed</strong>. Private repos
are authenticated through your existing git credential helper, and unshackle stores no
<p>unshackle's use of git is <strong>read-only on the remote</strong>: it only ever does a shallow
<code>clone</code>, <code>fetch</code>, <code>pull</code>, and a local <code>reset</code>. <strong>unshackle never pushes anything</strong>. Your
existing git credential helper authenticates private repos, and unshackle stores no
tokens of its own. Clones live under <code>&lt;first-local-services-dir&gt;/_repos/&lt;host&gt;__&lt;owner&gt;__&lt;repo&gt;/</code>
(or the bundled <code>unshackle/services</code>), and <strong>nothing is written to the cache directory</strong>. After
(or the bundled <code>unshackle/services</code>), and <strong>unshackle writes nothing to the cache directory</strong>. After
the first clone unshackle re-pulls <strong>at most once every 24 h</strong>, so it does not touch the
network on every run.</p>
</div>
@@ -2165,9 +2165,9 @@ discarding any local edits.</p>
point <code>services</code> at a writable path, or cloning will fail.</p>
</div>
<h2 id="filenames">Filenames<a class="headerlink" href="#filenames" title="Permanent link">&para;</a></h2>
<p>The <code>filenames</code> key is a <strong>dict</strong> of templated file/name patterns. Each value is used
verbatim (no path processing). Braced fields like <code>{time}</code> and <code>{service}</code> are filled in at
runtime.</p>
<p>The <code>filenames</code> config key is a <strong>dict</strong> of templated file/name patterns. unshackle uses
each value verbatim (no path processing). It fills in braced fields like <code>{time}</code> and
<code>{service}</code> at runtime.</p>
<table>
<thead>
<tr>
+22 -21
View File
@@ -2111,12 +2111,13 @@
<ul>
<li><strong>Type:</strong> <code>dict</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>{}</code></li>
</ul>
<p>Persistent defaults for the <code>dl</code> command. The block is used as Click's <code>default_map</code>, so any
<code>dl</code> flag can be given a default here. See <a href="../../../guide/downloading/">Downloading</a> and the
<p>Persistent defaults for the <code>dl</code> command. unshackle uses the block as Click's <code>default_map</code>,
so you can give any <code>dl</code> flag a default here. See <a href="../../../guide/downloading/">Downloading</a> and the
<a href="../../../guide/cli-reference/">CLI Reference</a> for what each flag does.</p>
<p><strong>Key naming.</strong> A key is the flag's long name with dashes replaced by underscores
(<code>--best-available</code> → <code>best_available</code>, <code>--sub-format</code> → <code>sub_format</code>). A few keys are named
after the flag's internal destination rather than its visible name; set these exact keys:</p>
<p><strong>Config key naming.</strong> A config key is the flag's long name with dashes replaced by
underscores (<code>--best-available</code> → <code>best_available</code>, <code>--sub-format</code> → <code>sub_format</code>). A few
config keys use the flag's internal destination and not its visible name. Set these exact
config keys:</p>
<table>
<thead>
<tr>
@@ -2162,7 +2163,7 @@ after the flag's internal destination rather than its visible name; set these ex
<p><strong>Precedence</strong> (highest first): an explicit CLI flag → a per-service
<a href="../services/"><code>services.&lt;TAG&gt;.dl</code></a> override → this global <code>dl:</code> block → the built-in
default. In other words, config only fills in options you did not set on the command line.</p>
<p>Common keys (a useful subset; every <code>dl</code> flag works):</p>
<p>Common config keys. This is a useful subset, and every <code>dl</code> flag works:</p>
<table>
<thead>
<tr>
@@ -2323,28 +2324,28 @@ applies to that service only.</p>
<div class="admonition note">
<p class="admonition-title"><code>serve</code> uses these same keys</p>
<p>The <a href="../services/#serve"><code>serve</code></a> block accepts most of the same <code>dl</code> option keys at its top level
to set server-wide download defaults for every request it handles. Keys the API does not know
are ignored there (<code>speed_limit</code>, for example; <code>serve</code> has its own <code>global_speed_limit</code>).</p>
to set server-wide download defaults for every request it handles. The API ignores the
config keys it does not know there, <code>speed_limit</code> for example. <code>serve</code> has its own
<code>global_speed_limit</code>.</p>
</div>
<h2 id="continue_downloads"><code>continue_downloads</code><a class="headerlink" href="#continue_downloads" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Type:</strong> <code>bool</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>false</code></li>
</ul>
<p>Keep a failed download's completed segment files so the next attempt resumes from where it
<p>Keep a failed download's completed segment files so the next download resumes from where it
stopped instead of restarting from byte zero.</p>
<p>Only whole, fully downloaded segments are reused; partially written segments are always
discarded, and no partial-byte (<code>Range</code>) resume across runs takes place. Reuse also
requires proof that the remote content is unchanged: the manifest URL, segment count, and
byte ranges must all match the previous run, otherwise the download silently restarts
clean.</p>
<p>unshackle reuses only whole, fully downloaded segments. It always discards partially written
segments, and no partial-byte (<code>Range</code>) resume across runs takes place. Reuse is possible only
with proof that the segmentation did not change. The manifest URL, segment count, and byte
ranges must all match the previous download, or the download silently restarts clean.</p>
<div class="admonition note">
<p class="admonition-title">What can and cannot resume</p>
<ul>
<li>Segmented DASH, ISM, and HLS tracks resume.</li>
<li>Single-file (non-segmented) downloads and DASH tracks collapsed to a single ranged
download never produce segment files, so this option does not apply to them (the
download never make segment files, so this option does not apply to them (the
downloader has its own in-flight partial-file handling for those).</li>
<li>HLS resumes Widevine/PlayReady and unencrypted content only; AES-128 content always
<li>HLS resumes Widevine/PlayReady and unencrypted titles only. An AES-128 title always
restarts. An HLS failure during the post-download merge step also restarts.</li>
</ul>
</div>
@@ -2356,8 +2357,8 @@ command line (the flag can only enable resume, never disable it).</p>
<ul>
<li><strong>Type:</strong> <code>dict</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>{}</code></li>
</ul>
<p>Subtitle handling: SDH stripping, format conversion, and whether subtitles are muxed in or
written as sidecar files. See <a href="../../../guide/subtitles/">Subtitles</a> for the full guide.</p>
<p>Subtitle handling: SDH stripping, format conversion, and whether unshackle muxes the subtitles
in or writes them as sidecar files. See <a href="../../../guide/subtitles/">Subtitles</a> for the full guide.</p>
<table>
<thead>
<tr>
@@ -2482,7 +2483,7 @@ controls the order inside each language.</p>
</tr>
</tbody>
</table>
<p>Nothing is removed, unlike <code>-sl</code>, which drops every subtitle language it does not name.</p>
<p>unshackle removes nothing, unlike <code>-sl</code>, which drops every subtitle language it does not name.</p>
<p>Use <code>orig</code> in the list for the title's original language. A base tag also covers its
regional forms, so <code>en</code> sorts <code>en-US</code> and <code>en-GB</code>, but <code>zh</code> does <strong>not</strong> cover
<code>zh-Hant</code>, which you must name. The sort ignores entries that match no track, and it
@@ -2580,8 +2581,8 @@ bitrate alone, with those same Atmos/descriptive rules still applied.</p>
<li><strong>Type:</strong> <code>dict</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>{}</code></li>
</ul>
<p>Language-tag remapping and the rule engine behind the <code>{lang_tag}</code> filename variable. When a
<code>rules</code> list is present, each rule is evaluated in order and the first match's <code>tag</code> is used.
A rule may test:</p>
<code>rules</code> list is present, unshackle evaluates each rule in order and uses the first match's
<code>tag</code>. A rule can examine:</p>
<table>
<thead>
<tr>
+15 -15
View File
@@ -2099,19 +2099,19 @@ profile:</p>
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a><span class="w"> </span><span class="nt">playready</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sl3000</span>
</span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></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">chromecdm_l3</span>
</span></code></pre></div>
<p>Quality keys support <code>1080</code>, <code>&gt;=1080</code>, <code>&gt;720</code>, <code>&lt;=576</code>, <code>&lt;480</code> style comparisons; DRM keys
are <code>widevine</code> / <code>playready</code>. Quality keys are matched first, but only when a video height is
known; if the value is still a dict after that, <code>widevine</code>/<code>playready</code> are used when present,
otherwise the credential profile name, then <code>default</code>.</p>
<p>The resolved name is looked up in <a href="#remote_cdm"><code>remote_cdm</code></a> by <code>name</code> first. If no entry
matches, it is loaded as a local device file, in this order: <code>&lt;name&gt;.prd</code> in
<p>Quality keys can hold <code>1080</code>, <code>&gt;=1080</code>, <code>&gt;720</code>, <code>&lt;=576</code>, <code>&lt;480</code> style comparisons. DRM keys
are <code>widevine</code> / <code>playready</code>. unshackle matches the quality keys first, but only when a video
height is known. If the value is still a dict after that, unshackle uses
<code>widevine</code>/<code>playready</code> when present, or else the credential profile name, then <code>default</code>.</p>
<p>unshackle finds the resolved name in <a href="#remote_cdm"><code>remote_cdm</code></a> by <code>name</code> first. If no entry
matches, unshackle loads it as a local device file, in this order: <code>&lt;name&gt;.prd</code> in
<code>directories.prds</code>, <code>&lt;name&gt;.prd</code> in <code>directories.wvds</code>, then <code>&lt;name&gt;.wvd</code> in
<code>directories.wvds</code>.</p>
<h2 id="remote_cdm"><code>remote_cdm</code><a class="headerlink" href="#remote_cdm" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Type:</strong> <code>list[dict]</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>[]</code></li>
</ul>
<p>A list of remote CDM server definitions. Each entry is matched by its <code>name</code> (referenced from
<p>A list of remote CDM definitions. unshackle matches each entry by its <code>name</code> (referenced from
<a href="#cdm"><code>cdm</code></a>), and its <code>type</code> selects the backend:</p>
<table>
<thead>
@@ -2203,7 +2203,7 @@ configuration error.</p>
</tr>
</tbody>
</table>
<p>PlayReady mode is used when <code>device_type</code> is <code>PLAYREADY</code> or <code>device_name</code> starts with <code>SL</code>.</p>
<p>unshackle uses PlayReady mode when <code>device_type</code> is <code>PLAYREADY</code> or <code>device_name</code> starts with <code>SL</code>.</p>
<h3 id="remote-cdm-custom-api"><code>custom_api</code> fields<a class="headerlink" href="#remote-cdm-custom-api" title="Permanent link">&para;</a></h3>
<table>
<thead>
@@ -2261,8 +2261,8 @@ configuration error.</p>
</tr>
</tbody>
</table>
<p>Transforms cover base64/hex/JSON encoding and <code>kid:key</code> parsing. PlayReady mode is used when
<code>device.type</code> is <code>PLAYREADY</code> or the device name is <code>SL2</code>/<code>SL3</code>.</p>
<p>Transforms cover base64/hex/JSON encoding and <code>kid:key</code> parsing. unshackle uses PlayReady mode
when <code>device.type</code> is <code>PLAYREADY</code> or the device name is <code>SL2</code>/<code>SL3</code>.</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">remote_cdm</span><span class="p">:</span>
</span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">my_custom</span>
</span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="w"> </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">custom_api</span>
@@ -2288,11 +2288,11 @@ configuration error.</p>
<ul>
<li><strong>Type:</strong> <code>str</code> or <code>dict</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>"shaka"</code></li>
</ul>
<p>Selects the tool used to physically decrypt CENC content. The value is compared
case-insensitively; <code>"mp4decrypt"</code> selects Bento4's mp4decrypt, and <strong>anything else</strong>
(including <code>"shaka"</code>) selects shaka-packager. When the value is a dict, the service key is
matched case-insensitively and the <code>default</code> entry is the fallback.</p>
<p>HLS AES-128 ClearKey is decrypted in-process and ignores this setting.</p>
<p>Selects the tool that physically decrypts CENC-encrypted tracks. unshackle compares the value
case-insensitively. <code>"mp4decrypt"</code> selects Bento4's mp4decrypt, and <strong>anything else</strong>
(including <code>"shaka"</code>) selects shaka-packager. When the value is a dict, unshackle compares the
service tag case-insensitively and uses the <code>default</code> entry as the fallback.</p>
<p>unshackle decrypts HLS AES-128 ClearKey in-process and ignores this setting.</p>
<div class="tabbed-set tabbed-alternate" data-tabs="1:2"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><input id="__tabbed_1_2" name="__tabbed_1" type="radio" /><div class="tabbed-labels"><label for="__tabbed_1_1">Global</label><label for="__tabbed_1_2">Per-service</label></div>
<div class="tabbed-content">
<div class="tabbed-block">
+1 -1
View File
@@ -1908,7 +1908,7 @@
<h1 id="a-complete-annotated-example">A complete annotated example<a class="headerlink" href="#a-complete-annotated-example" title="Permanent link">&para;</a></h1>
<p>The following config sets a handful of common keys. Every key not shown keeps its default.</p>
<p>The following config sets a handful of common config keys. Every config key not shown keeps its default.</p>
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nt">directories</span><span class="p">:</span>
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w"> </span><span class="nt">downloads</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">~/Media/unshackle</span>
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="w"> </span><span class="nt">temp</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/mnt/scratch/unshackle</span>
+6 -6
View File
@@ -1917,17 +1917,17 @@
<h1 id="configuration-reference">Configuration Reference<a class="headerlink" href="#configuration-reference" title="Permanent link">&para;</a></h1>
<p>Every key you can set in <code>unshackle.yaml</code>, with its name, type, default value, and behaviour,
<p>Every config key you can set in <code>unshackle.yaml</code>, with its name, type, default value, and behaviour,
split into one page per area. A worked config is on the <a href="example/">annotated example</a> page.</p>
<p>Where the file lives, how unshackle discovers it, and how to edit it:
<a href="../../getting-started/configuration-file/">The Configuration File</a>.</p>
<div class="admonition info">
<p class="admonition-title">How defaults work</p>
<p>Every key is optional except <a href="output/"><code>output_template</code></a>, which <code>dl</code> requires.
Without it, <code>dl</code> aborts with an error. If you omit any other key, unshackle uses
the built-in default listed here. There is <strong>no schema validation</strong>: unknown keys are
silently ignored (they never become settings), and the file is parsed with
<code>yaml.safe_load</code>. An empty or missing file means every other key falls back to its
<p>Every config key is optional except <a href="output/"><code>output_template</code></a>, which <code>dl</code> requires.
Without it, <code>dl</code> aborts with an error. If you do not write any other config key, unshackle
uses the built-in default listed here. There is <strong>no schema validation</strong>: unshackle
silently ignores unknown config keys (they never become settings), and reads the file with
<code>yaml.safe_load</code>. An empty or missing file means every other config key falls back to its
default.</p>
</div>
<div class="admonition warning">
+18 -18
View File
@@ -2122,7 +2122,7 @@
<p>Smaller configuration areas: external metadata API keys, caching and update checks, logging and debug flags, and deprecated keys.</p>
<h2 id="external-api-keys">External API keys<a class="headerlink" href="#external-api-keys" title="Permanent link">&para;</a></h2>
<p>All are unset by default and enable optional metadata/geolocation features. For which fields
each metadata provider can actually answer with, see
each metadata provider can answer with, see
<a href="../../../guide/downloading/#what-each-metadata-provider-supplies">What each metadata provider supplies</a>.</p>
<table>
<thead>
@@ -2204,7 +2204,7 @@ each metadata provider can actually answer with, see
</table>
<div class="admonition note">
<p class="admonition-title">How <code>metadata_providers</code> is applied</p>
<p>A lookup goes to each provider in turn and stops at the first good match, so the order
<p>A lookup goes to each metadata provider in turn and stops at the first good match, so the order
decides which source wins. <code>metadata_providers</code> sets that order:</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-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">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></code></pre></div>
@@ -2212,8 +2212,8 @@ decides which source wins. <code>metadata_providers</code> sets that order:</p>
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">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, 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>,
<p>Whatever the order, unshackle skips a metadata provider that has no API key. <code>imdb</code> and
<code>anilist</code> need no API 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
@@ -2235,18 +2235,18 @@ that is set, so you always get a title.</p>
<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
The title search is dead, and that includes the keyless <code>imdb</code> metadata 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>
IDs from it, and <code>--enrich</code> still reads that source. unshackle stops only the lookups you
did not ask for.</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
<p>It replaces the earlier <code>imdbapi</code> metadata 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>
@@ -2254,26 +2254,26 @@ from your config, where it is now ignored.</p>
<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>
of them and names every metadata 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>Each list is independent: it both orders and filters that kind on its own, so unshackle
still uses for <code>movie</code> a metadata provider you leave out of <code>tv</code>. Here unshackle tries TVDB
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>
metadata for those two kinds, so unshackle ignores any other config key, such as <code>anime</code> or <code>music</code>.</p>
</div>
<div class="admonition note">
<p class="admonition-title"><code>ipinfo_api_key</code> never touches your service sessions</p>
<p>The token is only ever sent to <code>api.ipinfo.io</code> as a per-request <code>Authorization</code> header; it
is <strong>never</strong> attached to your service session, so it cannot leak to a streaming provider.
<p>unshackle sends the token only to <code>api.ipinfo.io</code>, as a per-request <code>Authorization</code> header.
It <strong>never</strong> goes on your service HTTP session, so it cannot leak to a streaming service.
Lookups degrade gracefully through a fallback chain: the authenticated Lite endpoint (higher
rate limits, and ASN/continent data, but no city or region) → anonymous ipinfo →
<code>ip-api.in</code> as a last resort.</p>
@@ -2409,19 +2409,19 @@ result in <code>directories.cache/update_check.json</code>.</p>
</table>
<div class="admonition note">
<p class="admonition-title">Effect of <code>set_terminal_bg</code></p>
<p>When on, the theme's background colour is appended to the foreground styles, which makes
<p>When on, unshackle appends the theme's background colour to the foreground styles, which makes
the full colour palette render correctly on terminals whose <em>default</em> background differs
from unshackle's theme. When off, such terminals can render the ASCII-art banner and
coloured output incorrectly.</p>
</div>
<div class="admonition danger">
<p class="admonition-title">Key exposure</p>
<p>With <code>debug_keys</code> on, decryption content keys are written to the structured debug log at
<p>With <code>debug_keys</code> on, unshackle writes the content keys to the structured debug log at
INFO level during the DRM handshake. Treat <code>debug</code>, <code>debug_keys</code>, and the <code>unshackle_debug_*.jsonl</code> files as
sensitive, and keep <code>redact_paths</code> enabled when sharing logs.</p>
<p><code>debug_keys</code> affects <strong>only</strong> content-encryption keys (the <code>content_key</code>/<code>key</code> fields).
Passwords, tokens, cookies, and session tokens are <strong>always</strong> redacted regardless of this
setting, and KIDs, key counts, and other metadata are always logged either way.</p>
setting, and KIDs, content key counts, and other metadata are always logged either way.</p>
</div>
<hr />
<h2 id="deprecated-removed-keys">Deprecated &amp; removed keys<a class="headerlink" href="#deprecated-removed-keys" title="Permanent link">&para;</a></h2>
+8 -8
View File
@@ -2023,7 +2023,7 @@
<ul>
<li><strong>Type:</strong> <code>dict</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>{}</code></li>
</ul>
<p>TLS-fingerprinting and HTTP client settings for the rnet-based session.</p>
<p>TLS-fingerprinting and HTTP client settings for the rnet-based HTTP session.</p>
<table>
<thead>
<tr>
@@ -2140,24 +2140,24 @@ honours it (only when <code>network</code> is absent) but emits a <code>Deprecat
<ul>
<li><strong>Type:</strong> <code>dict</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>{}</code></li>
</ul>
<p>Default HTTP headers merged into every session unshackle creates.</p>
<p>Default HTTP headers merged into every HTTP session unshackle makes.</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">headers</span><span class="p">:</span>
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="w"> </span><span class="nt">Accept-Language</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">en-US,en;q=0.9</span>
</span></code></pre></div>
<div class="admonition warning">
<p class="admonition-title">Don't set <code>Accept-Encoding</code> (and similar) here</p>
<p>Compatibility headers such as <code>Accept-Encoding</code> are set by the rnet HTTP backend as part of
its browser-impersonation profile; overriding them breaks the impersonation fingerprint.
This block is for cross-service defaults only (for example <code>Accept-Language</code>,
<code>User-Agent</code>); per-service headers belong in that service's own config.</p>
its browser-impersonation profile. If you override them, you break the impersonation
fingerprint. This block is for cross-service defaults only (for example <code>Accept-Language</code>,
<code>User-Agent</code>). Per-service headers belong in that service's own config.</p>
</div>
<h2 id="proxy_providers"><code>proxy_providers</code><a class="headerlink" href="#proxy_providers" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Type:</strong> <code>dict</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>{}</code></li>
</ul>
<p>Proxy/VPN provider configuration. Each sub-key names a provider, and its block is passed
straight to that provider's constructor. See <a href="../../../guide/proxies-and-vpn/">Proxies &amp; VPN</a> for
the full provider guide. Recognised providers and their exit ports:</p>
<p>Proxy/VPN provider configuration. Each sub-key names a proxy provider, and unshackle passes its
block straight to that provider's constructor. See <a href="../../../guide/proxies-and-vpn/">Proxies &amp; VPN</a>
for the full proxy provider guide. Recognised proxy providers and their exit ports:</p>
<table>
<thead>
<tr>
+16 -15
View File
@@ -2072,7 +2072,7 @@ dropped.</p>
</span><span id="__span-0-6"><a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></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><span id="__span-0-7"><a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></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">({year})"</span>
</span></code></pre></div>
<p><strong>The nested <code>folder</code> sub-key</strong> controls output subfolders and is popped out of
<p><strong>The nested <code>folder</code> sub-key</strong> controls output subfolders, and unshackle pops it out of
<code>output_template</code>:</p>
<ul>
<li>A <strong>dict</strong> sets per-kind folder templates (kinds: <code>movies</code>, <code>series</code>, <code>songs</code>, <code>albums</code>).</li>
@@ -2104,7 +2104,7 @@ folders do not carry the part.</p>
<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>
empty on titles that have none. You add it to the name yourself, and it 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.
@@ -2143,7 +2143,7 @@ Use <code>{absolute?}</code> so the name stays clean when it is unknown.</p>
<td><code>chapter_fallback_name</code></td>
<td>str</td>
<td><code>""</code></td>
<td>Fallback chapter-name template, e.g. <code>"Chapter {i:02}"</code>.</td>
<td>Fallback template for chapter names, e.g. <code>"Chapter {i:02}"</code>.</td>
</tr>
<tr>
<td><code>unicode_filenames</code></td>
@@ -2158,8 +2158,8 @@ Use <code>{absolute?}</code> so the name stays clean when it is unknown.</p>
<li><strong>Type:</strong> <code>list</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>[]</code></li>
</ul>
<p>Conditionally replaces <a href="#tagging-naming-keys"><code>tag</code></a> for a given download. Each rule pairs a <code>when</code>
dict of conditions with the <code>tag</code> to use when they hold. Rules are evaluated in order and the
first match wins; if no rule matches, the global <code>tag</code> is kept.</p>
dict of conditions with the <code>tag</code> to use when they hold. unshackle evaluates the rules in
order and the first match wins. If no rule matches, the global <code>tag</code> stays.</p>
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><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">tag_rules</span><span class="p">:</span>
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">when</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> title_type</span><span class="p">:</span><span class="w"> </span><span class="nv">movie</span><span class="p p-Indicator">,</span><span class="nt"> lang_tag</span><span class="p">:</span><span class="w"> </span><span class="nv">SUBBED</span><span class="w"> </span><span class="p p-Indicator">}</span>
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="w"> </span><span class="nt">tag</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">SUBMOVIES</span>
@@ -2169,29 +2169,30 @@ first match wins; if no rule matches, the global <code>tag</code> is kept.</p>
<p>Rule semantics:</p>
<ul>
<li>Every condition in <code>when</code> must hold (they are AND-ed).</li>
<li>A value may be a scalar or a list; a list matches if <strong>any</strong> entry matches.</li>
<li>A value can be a scalar or a list. A list matches if <strong>any</strong> entry matches.</li>
<li>Comparison is case-insensitive string equality.</li>
<li>The keys of <code>when</code> are the filename template variables that describe the release itself:
<li>The keys of <code>when</code> are the filename template variables for the release itself:
<code>title_type</code>, <code>quality</code>, <code>resolution</code>, <code>source</code>, <code>video</code>, <code>hdr</code>, <code>hfr</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>edition</code>, <code>repack</code>,
and <code>lang_tag</code>. Only these are available. The title's own fields (<code>title</code>, <code>year</code>, <code>season</code>,
<code>episode</code>, and so on) are added after the rules run and cannot be matched.</li>
<li>An unknown key in <code>when</code> is a mistake: unshackle logs a warning that names the key and skips
that rule. A rule without conditions or without a <code>tag</code> is also warned about and skipped.</li>
and <code>lang_tag</code>. Only these are available. unshackle adds the title's own fields (<code>title</code>,
<code>year</code>, <code>season</code>, <code>episode</code>, and so on) after it evaluates the rules, so a condition cannot
use them.</li>
<li>An unknown key in <code>when</code> is a mistake: unshackle logs a warning that names the key
and skips that rule. unshackle also warns about a rule without conditions or without a <code>tag</code>, and skips it.</li>
</ul>
<p>Put the more specific rules first, because the first match ends the search.</p>
<p>Put the more specific rules first, because unshackle stops at the first match.</p>
<div class="admonition warning">
<p class="admonition-title">Match <code>hdr</code> on the exact value</p>
<p>Matching is exact, and <code>hdr</code> is a composite label for Dolby Vision titles: a DV title with
an HDR10 base layer gives <code>DV.HDR</code>, and with an HDR10+ base layer <code>DV.HDR10P</code>. Plain <code>DV</code>
does <strong>not</strong> match those. List every variant you want, as the example above does. Note
does <strong>not</strong> match those. Name every variant you want, as the example above does. Note
also that HDR10 gives <code>HDR</code>, not <code>HDR10</code>. The full set of values is <code>HDR</code>, <code>HDR10P</code>, <code>DV</code>,
<code>DV.HDR</code>, <code>DV.HDR10P</code>, and <code>HLG</code>, as listed in the
<a href="../../../guide/output-and-naming/#template-variables">variable table</a>.</p>
</div>
<h3 id="operators">Operators<a class="headerlink" href="#operators" title="Permanent link">&para;</a></h3>
<p>A condition value may start with a comparison operator, which is applied to the rest of the
value:</p>
<p>A condition value can start with a comparison operator, which unshackle applies to the rest of
the value:</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">tag_rules</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="p p-Indicator">-</span><span class="w"> </span><span class="nt">when</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> resolution</span><span class="p">:</span><span class="w"> </span><span class="s">"&lt;1080"</span><span class="w"> </span><span class="p p-Indicator">}</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">tag</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">SDGROUP</span>
+36 -36
View File
@@ -2263,12 +2263,12 @@
<h1 id="post-scripts">Post-download scripts<a class="headerlink" href="#post-scripts" title="Permanent link">&para;</a></h1>
<p>Run your own script when a download finishes, with unshackle's metadata passed in as
<p>Operate your own script when a download finishes, with unshackle's metadata passed in as
<code>{variable}</code> placeholders. Use it to hand a finished file to an uploader, send a
notification, or start a library scan.</p>
<h2 id="post_scripts"><code>post_scripts</code><a class="headerlink" href="#post_scripts" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Type:</strong> <code>list[dict]</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>[]</code> (no scripts run)</li>
<li><strong>Type:</strong> <code>list[dict]</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>[]</code> (unshackle operates no scripts)</li>
</ul>
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nt">post_scripts</span><span class="p">:</span>
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="s">"python</span><span class="nv"> </span><span class="s">/opt/upload.py</span><span class="nv"> </span><span class="s">{filepath}</span><span class="nv"> </span><span class="s">--service={service}</span><span class="nv"> </span><span class="s">--season={season}</span><span class="nv"> </span><span class="s">--episode={episode}</span><span class="nv"> </span><span class="s">--tmdb={tmdb}</span><span class="nv"> </span><span class="s">--subs={sidecars}"</span>
@@ -2277,7 +2277,7 @@ notification, or start a library scan.</p>
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="s">"python</span><span class="nv"> </span><span class="s">/opt/notify.py</span><span class="nv"> </span><span class="s">--title={title}</span><span class="nv"> </span><span class="s">--episode={episode}"</span>
</span></code></pre></div>
<p>Every entry that matches the event and mode runs, so one download can feed an uploader and
a notifier without a wrapper script. An entry may also be written as a plain string, which
a notifier without a wrapper script. You can also write an entry as a plain string, which
is the same as <code>{command: "...", event: success, mode: file}</code>.</p>
<table>
<thead>
@@ -2305,13 +2305,13 @@ is the same as <code>{command: "...", event: success, mode: file}</code>.</p>
</tr>
</tbody>
</table>
<p>An entry whose <code>event</code> or <code>mode</code> is not one of the listed values is skipped and logs a
warning naming the bad value, once per command. An entry whose <code>command</code> cannot be split
into arguments, such as one with an unbalanced quote, is skipped with a warning too. Neither
stops the download or the other entries.</p>
<p>unshackle skips an entry whose <code>event</code> or <code>mode</code> is not one of the listed values, and logs a
warning that names the bad value, once per command. unshackle also skips an entry whose
<code>command</code> it cannot split into arguments, such as one with an unbalanced quote, and logs a
warning. Neither stops the download or the other entries.</p>
<h2 id="how-the-command-runs">How the command runs<a class="headerlink" href="#how-the-command-runs" title="Permanent link">&para;</a></h2>
<p>The command is split into arguments <strong>first</strong>, and variables are substituted into those
arguments afterwards. The process runs without a shell.</p>
<p>unshackle splits the command into arguments <strong>first</strong>, and then substitutes the variables
into those arguments. The process runs without a shell.</p>
<p>This is what keeps a title like <code>Bob"; rm -rf ~</code> harmless: a value can never turn into an
extra argument or a shell operator, and you never have to think about quoting. It also
means a path containing spaces always arrives as a single argument on every OS.</p>
@@ -2321,19 +2321,19 @@ means a path containing spaces always arrives as a single argument on every OS.<
first stops a value becoming a <em>new</em> argument, but a value on its own can still be a
whole argument. A bare <code>{title}</code> whose value is <code>--upload-file=/etc/passwd</code> would arrive
as an option to your script, not as text. Write <code>--title={title}</code>, not a bare <code>{title}</code>,
so a service can never forge a flag. unshackle refuses to run a command when a
so a service can never forge a flag. unshackle refuses to operate a command when a
substituted value would become an option-like token (one that starts with <code>-</code>), and logs
a warning instead.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">No shell features, and name your interpreter</p>
<p>Pipes, <code>&amp;&amp;</code>, <code>&gt;</code> redirection, <code>~</code> and globs do not work, because no shell is involved.
<p>Pipes, <code>&amp;&amp;</code>, <code>&gt;</code> redirection, <code>~</code> and globs do not work, because unshackle uses no shell.
If you want them, make the shell explicit: <code>bash -c "..."</code>.</p>
<p>For the same reason there is no interpreter lookup. Write <code>python /opt/upload.py</code>
rather than <code>/opt/upload.py</code>. unshackle will not guess whether you meant the system
Python or the one in its own virtual environment.</p>
<p>On Windows, when a <strong>fixed</strong> part of an argument contains a space, quote the whole
argument (<code>"--out=C:\My Dir\{filename}"</code>), not just the value. Substituted values
argument (<code>"--out=C:\My Dir\{filename}"</code>), not only the value. Substituted values
never need quoting on any OS.</p>
<p>On Windows, do not target a <code>.bat</code> or <code>.cmd</code> file directly. Windows runs batch files
through <code>cmd.exe</code>, whose argument quoting differs from every other program and has a
@@ -2352,7 +2352,7 @@ throttling them. If your script is heavy, queue the work inside it or use <code>
</div>
<h2 id="variables">Variables<a class="headerlink" href="#variables" title="Permanent link">&para;</a></h2>
<p>Metadata comes from the same naming context that produced the file's name, built per output
file. So <code>{quality}</code> and <code>{hdr}</code> always describe the file being passed. Downloading
file. So <code>{quality}</code> and <code>{hdr}</code> always give the values for the file unshackle passes in. Downloading
<code>-q 1080,2160 -r HDR10,SDR</code> produces four files, each with its own invocation and its own
values.</p>
<table>
@@ -2422,10 +2422,10 @@ values.</p>
<div class="admonition warning">
<p class="admonition-title">Empty variables become an empty string</p>
<p><code>--tmdb={tmdb}</code> with no ID resolved hands your script <code>--tmdb=</code>, so treat an empty
string as absent. Write your script to handle every variable being empty.</p>
string as absent. Write your script to accept an empty value for every variable.</p>
<p>Empty is common, and not only when data is missing:</p>
<ul>
<li>Nothing was resolved. <code>{tmdb}</code> is empty when no metadata provider found the title,
<li>No metadata provider found an ID. <code>{tmdb}</code> is empty when no metadata provider found the title,
the matching API key is missing, or the title is a movie you gave no ID for.</li>
<li>The title has no such field. Movies have no <code>{season}</code> or <code>{episode}</code>, and music has
neither.</li>
@@ -2495,22 +2495,21 @@ puts in <code>{title}</code>.</p>
<p><code>{year}</code> is empty when the service gives the release no year. <code>{ext}</code> is the container the
track arrived in, such as <code>.flac</code>, because a music download is not muxed.</p>
<h3 id="tagging-ids">Tagging IDs<a class="headerlink" href="#tagging-ids" title="Permanent link">&para;</a></h3>
<p><code>{tmdb}</code>, <code>{imdb}</code> and <code>{tvdb}</code> carry the IDs unshackle is tagging the file with, read at
the moment the hook is dispatched rather than snapshotted at the start of the run. An
episode's TMDB ID is resolved by the title search inside the download loop, so a hook fires
with it already filled in.</p>
<p><code>{tmdb}</code>, <code>{imdb}</code> and <code>{tvdb}</code> carry the IDs unshackle tags the file with. unshackle reads
them at the moment it sends the hook, and not at the start of the run. The title search inside
the download loop finds an episode's TMDB ID, so a hook fires with it already filled in.</p>
<p>They hold an ID you passed with <code>--tmdb</code>, <code>--imdb</code> or <code>--tvdb</code>, plus a TMDB ID the episode
search resolved. No such search runs for a movie, so a movie hook gets them empty unless you
passed one.</p>
<h3 id="sidecar-files">Sidecar files<a class="headerlink" href="#sidecar-files" title="Permanent link">&para;</a></h3>
<p><code>{sidecars}</code> holds the sidecar subtitle files written beside the output, which are the only
extra files a download leaves next to it. Attachments such as fonts are muxed into the
container and temporary artwork is deleted, so neither appears. Expect <code>{sidecars}</code> to be
extra files a download leaves next to it. unshackle muxes attachments such as fonts into the
container and deletes temporary artwork, so neither appears. Expect <code>{sidecars}</code> to be
empty unless <a href="../download/#subtitle"><code>subtitle.output_mode</code></a> is <code>sidecar</code> or <code>both</code>, which is
not the default. A music download writes no sidecars at all.</p>
<p>Paths are absolute and separated by a newline, because a newline is the only character that
cannot appear in a filename on any supported OS. The whole list arrives as a single
argument, so no quoting is needed in your template.</p>
argument, so your template needs no quoting.</p>
<p>When one download writes several outputs (<code>-q 1080,720</code>), each output's folder gets its own
copy of the sidecar files, and each invocation lists the copies sitting beside its own
<code>{filepath}</code>.</p>
@@ -2558,7 +2557,7 @@ that title and then returns. It downloads no further title, and no <code>season<
hook fires after that point. This applies to every title type. If one episode of S01
fails, the S01 hook does not fire at all.</p>
</div>
<p>The hook is keyed to the folder, not to the season, so one season landing in several
<p>unshackle attaches the hook to the folder, not to the season, so one season landing in several
folders (<code>-q 1080,720</code> with a quality-dependent folder template) fires it once per folder,
each with its own <code>{folder}</code>. A movie is a group of its own: a <code>season</code> hook fires for a
movie's folder as soon as the movie finishes.</p>
@@ -2611,9 +2610,9 @@ title object already knew: <code>{title}</code>, <code>{title_raw}</code>, <code
<code>{episode}</code>, <code>{episode_name}</code>, <code>{service}</code>, the tagging IDs and <code>{error}</code>. Everything that
comes from the naming context, such as <code>{quality}</code>, <code>{hdr}</code>, <code>{artist}</code> and <code>{album}</code>, is
empty.</p>
<p>A resumed <code>--continue</code> download that finishes runs <code>success</code> as usual. Because unshackle
does not wait for your script, it never sees its exit code, so a failing script is not
reported anywhere. Your script owns its own error handling and logging.</p>
<p>A resumed <code>--continue-downloads</code> download that finishes runs <code>success</code> as usual. Because
unshackle does not wait for your script, it never sees its exit code, so a failing script
is not reported anywhere. Your script owns its own error handling and logging.</p>
<p>A <code>success</code> hook always names a file this run wrote. There is no skip-if-exists path in
<code>dl</code> today, so nothing fires for a title that was not downloaded.</p>
<h2 id="-postscript"><code>--postscript</code><a class="headerlink" href="#-postscript" title="Permanent link">&para;</a></h2>
@@ -2626,29 +2625,30 @@ configured entry runs while it is in use. That includes your <code>season</code>
entries, which have no <code>--postscript</code> equivalent.</p>
<h2 id="the-rest-api">The REST API<a class="headerlink" href="#the-rest-api" title="Permanent link">&para;</a></h2>
<p>The API never accepts a post-script command. <code>postscript</code>, <code>post_script</code> and <code>post_scripts</code>
in a <code>POST /api/download</code> body are rejected with <code>400 INVALID_PARAMETERS</code>, because a command
arriving from an HTTP caller would be remote code execution.</p>
<p>Scripts defined in <code>unshackle.yaml</code> do run for API jobs, music jobs included. Only the
in a <code>POST /api/download</code> body get <code>400 INVALID_PARAMETERS</code>. A command that arrives from an
HTTP caller would be remote code execution.</p>
<p>unshackle does operate the scripts defined in <code>unshackle.yaml</code> for API jobs, music jobs
included. Only the
command itself may not cross the network.</p>
<h2 id="logging">Logging<a class="headerlink" href="#logging" title="Permanent link">&para;</a></h2>
<p>The command that was run is logged twice: at <code>DEBUG</code> level on the console, and as a
<p>unshackle logs the command it operated twice: at <code>DEBUG</code> level on the console, and as a
<code>post_script_dispatch</code> entry in the
<a href="../../../guide/troubleshooting/#the-structured-json-debug-log">structured JSON debug log</a>
when that log is enabled.</p>
<p>Both are masked the same way, honouring <a href="../misc/"><code>redact_paths</code></a>, which is on by default.
when that log is on.</p>
<p>unshackle masks both the same way, and honours <a href="../misc/"><code>redact_paths</code></a>, which is on by default.
Debug logs get shared in issue reports, and a hook command line is mostly paths. URL
credentials and <code>token=</code> / <code>api_key=</code> query parameters are also masked.</p>
<div class="admonition warning">
<p class="admonition-title">Do not hardcode secrets in the command</p>
<p>An arbitrary secret in the command line, such as <code>-H "Authorization: Bearer &lt;key&gt;"</code>,
cannot be recognised and is logged verbatim. Read the secret from a file or an
<p>unshackle cannot recognise an arbitrary secret in the command line, such as
<code>-H "Authorization: Bearer &lt;key&gt;"</code>, and logs it verbatim. Read the secret from a file or an
environment variable inside your script rather than putting it in the <code>command</code>.</p>
</div>
<h2 id="limitations">Limitations<a class="headerlink" href="#limitations" title="Permanent link">&para;</a></h2>
<ul>
<li>No <code>success</code> hooks run under <code>--no-mux</code> or <code>--skip-dl</code>, because neither writes a muxed
<li>No <code>success</code> hook operates under <code>--no-mux</code> or <code>--skip-dl</code>, because neither writes a muxed
output. A <code>failure</code> hook still runs under <code>--no-mux</code> if the download itself fails.</li>
<li><code>failure</code> hooks only run in <code>file</code> mode.</li>
<li><code>failure</code> hooks only operate in <code>file</code> mode.</li>
<li>There is no webhook sender. Call <code>curl</code> from a script instead.</li>
<li>Script output is not captured. Redirect it inside your own script if you want a log.</li>
</ul>
+31 -30
View File
@@ -2070,18 +2070,18 @@
<p>Per-service configuration, keyed by the canonical service tag (for example <code>EXAMPLE1</code>, <code>EXAMPLE2</code>,
<code>EXAMPLE3</code>). unshackle reads several well-known sub-keys out of each service's block:</p>
<ul>
<li><strong><code>proxy_map</code></strong>: remaps the region query you passed to <code>-p/--proxy</code> for this service. A key is
that query, or <code>"provider:query"</code> when the flag also named a provider; the value is the query
asked of the proxy provider instead. It has no effect when <code>-p</code> was given a full proxy URL.</li>
<li><strong><code>proxy_map</code></strong>: remaps the region query you passed to <code>-p/--proxy</code> for this service.
A config key is that query, or <code>"provider:query"</code> when the flag also named a proxy provider. The value is
the query asked of the proxy provider instead. It has no effect when you give <code>-p</code> a full proxy URL.</li>
<li><strong><code>title_map</code></strong>: an exact-match rename map applied to fetched titles (source name →
desired name), so a service that names a title differently from your library still matches.</li>
<li><strong><code>dl</code></strong>: per-service download defaults, using the same keys as the global
<a href="../download/#dl"><code>dl</code></a> block.</li>
</ul>
<p>Individual services may read any additional keys they define. The merged result (the service's
own <code>config.yaml</code> with this block layered on top) is handed to the service as <code>self.config</code>.</p>
<p>Individual services may read any additional keys they define. unshackle hands the merged result
(the service's own <code>config.yaml</code> with this block layered on top) to the service as <code>self.config</code>.</p>
<p>User- or device-specific values (API keys, account IDs, device attributes) belong in this block
rather than in the service's own <code>config.yaml</code>, which holds shared defaults; see
rather than in the service's own <code>config.yaml</code>, which holds shared defaults. See
<a href="../../../dev/creating-a-service/">creating a service</a>.</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nt">services</span><span class="p">:</span>
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w"> </span><span class="nt">EXAMPLE1</span><span class="p">:</span>
@@ -2097,10 +2097,10 @@ rather than in the service's own <code>config.yaml</code>, which holds shared de
</ul>
<p>Per-service login credentials. Each value is a <code>username:password[:extra]</code> string, the same
data as a <code>[username, password]</code> (or <code>[username, password, extra]</code>) list, or a dict of profile
name to either of those. With the dict form, <code>-p/--profile</code> selects the entry, and the
<code>default</code> key is used when no profile was given or the named profile is missing. These are
parsed into <code>Credential</code> objects; the credential's SHA-1 is also used as an account hash for
cache keys.</p>
name to either of those. With the dict form, <code>-p/--profile</code> selects the entry, and unshackle
uses the <code>default</code> config key when you give no profile, or when the named profile is missing.
unshackle parses these into <code>Credential</code> objects. It also uses the credential's SHA-1 as an
account hash for cache keys.</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">credentials</span><span class="p">:</span>
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="w"> </span><span class="nt">EXAMPLE2</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">user@example.com:hunter2</span>
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="w"> </span><span class="nt">EXAMPLE1</span><span class="p">:</span>
@@ -2109,22 +2109,22 @@ cache keys.</p>
</span></code></pre></div>
<div class="admonition tip">
<p class="admonition-title">Cookies vs credentials</p>
<p>Cookies are stored as files under <a href="../directories/"><code>directories.cookies</code></a>, not in this key.
<p>unshackle stores cookies as files under <a href="../directories/"><code>directories.cookies</code></a>, not in this config key.
A service's <code>authenticate()</code> accepts cookies, credentials, or both.</p>
</div>
<h2 id="firefox_cookies"><code>firefox_cookies</code><a class="headerlink" href="#firefox_cookies" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Type:</strong> <code>dict</code> keyed by service tag &nbsp;·&nbsp; <strong>Default:</strong> <code>{}</code></li>
</ul>
<p>Settings for extracting cookies directly from a local Firefox profile. A service block is
expected to provide <code>hosts</code> (a list of cookie hostnames; entries shorter than 3 characters
are ignored to prevent dumping the whole cookie store) and an optional <code>local_storage</code>
boolean to also pull matching entries from <code>webappsstore.sqlite</code>, which only services that
keep auth tokens in localStorage rather than in HTTP cookies need. Extraction is read-only.</p>
<p>Settings for extracting cookies directly from a local Firefox profile. A service block must give
<code>hosts</code>, a list of cookie hostnames. unshackle ignores an entry shorter than 3 characters, to
prevent a broad match dumping most of the profile. With an optional <code>local_storage</code> boolean,
unshackle also pulls matching entries from <code>webappsstore.sqlite</code>, which only services that keep
auth tokens in localStorage rather than in HTTP cookies need. Extraction is read-only.</p>
<div class="admonition note">
<p class="admonition-title">Firefox does not need to be closed</p>
<p>The extractor copies <strong>both</strong> <code>cookies.sqlite</code> <strong>and</strong> its WAL file into a <code>0700</code> temp
directory, so writes Firefox has not yet flushed to the main DB are included. Extraction
directory, so the copy holds the writes Firefox has not yet flushed to the main DB. Extraction
fails only if Firefox holds an exclusive write lock at the instant of the copy. The live
profile is not modified.</p>
</div>
@@ -2139,19 +2139,19 @@ to the normal file-based cookie path (<code>cookies/&lt;SERVICE&gt;.txt</code> o
<li><strong>Type:</strong> <code>dict</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>{}</code></li>
</ul>
<p>Definitions of remote unshackle service servers, used by the <code>--remote</code> mode. Each entry is
named by you (pick it with <code>--server</code>, or omit that flag when only one is configured) and gives
named by you (pick it with <code>--server</code>, or do not write that flag when you configure only one) and gives
the server's <code>url</code> (required), an optional <code>api_key</code>, an optional <code>auth_headers</code> list, an
optional <code>server_cdm</code> boolean, and an optional <code>services</code> sub-dict of per-service local
overrides such as <code>title_map</code>.</p>
<p><code>auth_headers</code> lists extra header names to send the API key in, tried before the defaults
<code>X-Secret-Key</code> and <code>X-Api-Key</code>, which are always appended as fallbacks. unshackle sends the
first name; if the server answers <code>401</code>, it retries the same request with the next name, and
keeps the one that works for the rest of the session. Names you list keep your spelling and are
not repeated in the fallbacks, so <code>auth_headers: ["Authorization", "x-secret-key"]</code> is tried as
<code>Authorization</code>, <code>x-secret-key</code>, <code>X-Api-Key</code>.</p>
first name. If the server answers <code>401</code>, it retries the same request with the next name, and
keeps the one that works for the rest of the HTTP session. Names you give keep your spelling and
are not repeated in the fallbacks, so unshackle tries
<code>auth_headers: ["Authorization", "x-secret-key"]</code> as <code>Authorization</code>, <code>x-secret-key</code>, <code>X-Api-Key</code>.</p>
<p>In <code>--remote</code> mode unshackle turns the server's service list into synthetic CLI
commands that run against it, falling back to the tags in that <code>services</code> sub-dict when the
list cannot be fetched. Each synthetic command carries the server-side service's options and
commands that operate against it, falling back to the tags in that <code>services</code> sub-dict when
unshackle cannot fetch the list. Each synthetic command carries the server-side service's options and
documentation, so <code>unshackle dl --remote &lt;TAG&gt; -h</code> shows the same help text as it does on the
server. See <a href="../../../dev/rest-api/remote-sessions/">remote sessions</a> for the
full setup.</p>
@@ -2160,7 +2160,7 @@ full setup.</p>
<li><strong>Type:</strong> <code>dict</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>{}</code></li>
</ul>
<p>Configuration for the <code>serve</code> command (the built-in REST API server). The full server guide
is the <a href="../../../dev/rest-api/">REST API</a> section; these are the config keys.</p>
is the <a href="../../../dev/rest-api/">REST API</a> section. These are the config keys.</p>
<table>
<thead>
<tr>
@@ -2251,14 +2251,15 @@ is the <a href="../../../dev/rest-api/">REST API</a> section; these are the conf
</tr>
</tbody>
</table>
<p>Each entry under <code>users</code> is keyed by that user's API key and may set its own <code>services</code>,
<p>Each entry under <code>users</code> uses that user's API key as its name, and can set its own <code>services</code>,
<code>devices</code>, and <code>playready_devices</code> allowlists, narrowing the global ones, plus an optional
<code>username</code> used as the log label for that key (defaults to a truncated form of the key). A
user with no <code>playready_devices</code> key gets no PlayReady access at all, not the global list.</p>
<p><code>server_cdm</code> decides whether the server runs the CDM licensing for that key. It is <code>false</code>
<code>username</code> used as the log label for that API key (defaults to a truncated form of the API key).
A user with no <code>playready_devices</code> config key gets no PlayReady access at all, not the global
list.</p>
<p><code>server_cdm</code> decides whether the server runs the CDM licensing for that API key. It is <code>false</code>
unless the entry sets it, so a remote client configured with <code>server_cdm: true</code> is told to
license with its own local CDM instead, and a client that asks anyway gets a <code>FORBIDDEN</code>
error. Because a download job always licenses with the server's CDM, a key without
error. Because a download job always licenses with the server's CDM, an API key without
<code>server_cdm</code> also cannot submit or retry <code>/api/download</code> jobs. Keys that have no <code>users</code>
entry, such as <code>api_secret</code>, keep server CDM access.</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">serve</span><span class="p">:</span>
+6 -6
View File
@@ -2002,9 +2002,9 @@
<ul>
<li><strong>Type:</strong> <code>list[dict]</code> &nbsp;·&nbsp; <strong>Default:</strong> <code>[]</code></li>
</ul>
<p>An ordered list of key-vault backends. unshackle queries them in order and reuses content
keys instead of re-licensing. Each entry needs a <code>type</code> (the backend module name) and a
<code>name</code>, plus backend-specific keys.</p>
<p>An ordered list of key-vault backends. unshackle queries them in order and reuses the
content keys instead of licensing them again. Each entry needs a <code>type</code> (the backend module
name) and a <code>name</code>, plus backend-specific keys.</p>
<table>
<thead>
<tr>
@@ -2056,12 +2056,12 @@ keys instead of re-licensing. Each entry needs a <code>type</code> (the backend
<div class="admonition note">
<p class="admonition-title">Per-entry options</p>
<ul>
<li><code>no_push: true</code> makes a vault read-only (keys are fetched but never written to it).</li>
<li><code>no_push: true</code> makes a vault read-only (unshackle fetches content keys from it but never writes to it).</li>
<li>A vault of <code>type: API</code> whose <code>name</code> contains <code>decrypt_labs</code> auto-fills its <code>token</code> from
<a href="../misc/#external-api-keys"><code>decrypt_labs_api_key</code></a> when not set inline. Vault <code>type</code> values are
case-sensitive module names.</li>
<li>An all-zero content key (32 zeros) is treated as "no key" everywhere and is never
stored.</li>
<li>unshackle treats an all-zero content key (32 zeros) as "no key" everywhere and never
stores it.</li>
</ul>
</div>
<h2 id="vault_timeout"><code>vault_timeout</code><a class="headerlink" href="#vault_timeout" title="Permanent link">&para;</a></h2>