Compare commits

...
2 Commits
Author SHA1 Message Date
e95917458e Deployed eeaf16c with MkDocs version: 1.6.1 2026-10-23 15:42:26 +00:00
031946fcde Deployed af69e8a with MkDocs version: 1.6.1 2026-10-23 14:21:08 +00:00
6 changed files with 900 additions and 946 deletions
+5 -3
View File
@@ -5074,8 +5074,9 @@ A slow answer arrives as a <a href="#slow-responses">slow response</a>.</p>
</span><span id="__span-39-9"><a id="__codelineno-39-9" name="__codelineno-39-9" href="#__codelineno-39-9"></a><span class="w"> </span><span class="nt">"track_manifests"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"track_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"s-1"</span><span class="p">,</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"dash"</span><span class="p">,</span><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://..."</span><span class="p">,</span><span class="w"> </span><span class="nt">"data"</span><span class="p">:</span><span class="w"> </span><span class="s2">"&lt;base64 zlib xml&gt;"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">],</span>
</span><span id="__span-39-10"><a id="__codelineno-39-10" name="__codelineno-39-10" href="#__codelineno-39-10"></a><span class="w"> </span><span class="nt">"session_headers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"User-Agent"</span><span class="p">:</span><span class="w"> </span><span class="s2">"..."</span><span class="w"> </span><span class="p">},</span>
</span><span id="__span-39-11"><a id="__codelineno-39-11" name="__codelineno-39-11" href="#__codelineno-39-11"></a><span class="w"> </span><span class="nt">"session_cookies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"sid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"..."</span><span class="w"> </span><span class="p">},</span>
</span><span id="__span-39-12"><a id="__codelineno-39-12" name="__codelineno-39-12" href="#__codelineno-39-12"></a><span class="w"> </span><span class="nt">"server_cdm_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"widevine"</span>
</span><span id="__span-39-13"><a id="__codelineno-39-13" name="__codelineno-39-13" href="#__codelineno-39-13"></a><span class="p">}</span>
</span><span id="__span-39-12"><a id="__codelineno-39-12" name="__codelineno-39-12" href="#__codelineno-39-12"></a><span class="w"> </span><span class="nt">"session_cookie_jar"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sid"</span><span class="p">,</span><span class="w"> </span><span class="nt">"value"</span><span class="p">:</span><span class="w"> </span><span class="s2">"..."</span><span class="p">,</span><span class="w"> </span><span class="nt">"domain"</span><span class="p">:</span><span class="w"> </span><span class="s2">".example.com"</span><span class="p">,</span><span class="w"> </span><span class="nt">"path"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/"</span><span class="p">,</span><span class="w"> </span><span class="nt">"secure"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">],</span>
</span><span id="__span-39-13"><a id="__codelineno-39-13" name="__codelineno-39-13" href="#__codelineno-39-13"></a><span class="w"> </span><span class="nt">"server_cdm_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"widevine"</span>
</span><span id="__span-39-14"><a id="__codelineno-39-14" name="__codelineno-39-14" href="#__codelineno-39-14"></a><span class="p">}</span>
</span></code></pre></div>
</div>
</div>
@@ -5113,13 +5114,14 @@ A slow answer arrives as a <a href="#slow-responses">slow response</a>.</p>
<div class="tabbed-block">
<div class="language-json highlight"><pre><span></span><code><span id="__span-40-1"><a id="__codelineno-40-1" name="__codelineno-40-1" href="#__codelineno-40-1"></a><span class="p">{</span>
</span><span id="__span-40-2"><a id="__codelineno-40-2" name="__codelineno-40-2" href="#__codelineno-40-2"></a><span class="w"> </span><span class="nt">"tracks"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
</span><span id="__span-40-3"><a id="__codelineno-40-3" name="__codelineno-40-3" href="#__codelineno-40-3"></a><span class="w"> </span><span class="nt">"v-1"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"descriptor"</span><span class="p">:</span><span class="w"> </span><span class="s2">"DASH"</span><span class="p">,</span><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://..."</span><span class="p">,</span><span class="w"> </span><span class="nt">"drm"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">],</span><span class="w"> </span><span class="nt">"headers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="nt">"cookies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="nt">"data"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span>
</span><span id="__span-40-3"><a id="__codelineno-40-3" name="__codelineno-40-3" href="#__codelineno-40-3"></a><span class="w"> </span><span class="nt">"v-1"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"descriptor"</span><span class="p">:</span><span class="w"> </span><span class="s2">"DASH"</span><span class="p">,</span><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://..."</span><span class="p">,</span><span class="w"> </span><span class="nt">"drm"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">],</span><span class="w"> </span><span class="nt">"headers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="nt">"cookies"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="nt">"cookie_jar"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">],</span><span class="w"> </span><span class="nt">"data"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span>
</span><span id="__span-40-4"><a id="__codelineno-40-4" name="__codelineno-40-4" href="#__codelineno-40-4"></a><span class="w"> </span><span class="p">}</span>
</span><span id="__span-40-5"><a id="__codelineno-40-5" name="__codelineno-40-5" href="#__codelineno-40-5"></a><span class="p">}</span>
</span></code></pre></div>
</div>
</div>
</div>
<p><code>cookies</code> gives names and values only. <code>cookie_jar</code> gives the same cookies with their domain, path and <code>secure</code> flag, in the <code>session_cookie_jar</code> form of the tracks response.</p>
<table>
<thead>
<tr>
+5 -3
View File
@@ -2629,8 +2629,10 @@ DASH/ISM manifests as compressed XML so the client can re-parse them locally for
downloading. A service can build an AdaptationSet of its own that the served
manifest does not contain. Each such track gets a one-AdaptationSet MPD in
<code>track_manifests</code>, and the client re-parses that instead. Any
<code>session_headers</code> / <code>session_cookies</code> the server used are merged into the
client's local HTTP session.</p>
<code>session_headers</code> and cookies the server used are merged into the
client's local HTTP session. Each cookie in <code>session_cookie_jar</code> keeps its
domain, path and <code>secure</code> flag, so it goes only to its own hosts. <code>session_cookies</code> carries
the same cookies as names and values only, for older clients.</p>
<p>The tracks response repeats the title. A service can rewrite title fields inside
<code>get_tracks</code>, so the client takes this copy in place of the one from the title
list. Each track carries the full local field set. After the manifest re-parse the
@@ -3159,7 +3161,7 @@ remote session API and a good template for any client.</p>
<li><strong>Flow.</strong> <code>authenticate()</code> → <code>create</code> (+ poll <code>prompt</code> every 2s up to a 600s
deadline, answering <code>pending_input</code> prompts. With stdin closed the client logs an
error and raises <code>SystemExit(1)</code> instead of posting an empty answer) → <code>get_titles()</code> → <code>get_tracks()</code>
(merging returned <code>session_headers</code>/<code>session_cookies</code>, re-parsing <code>manifests</code>) →
(merging returned <code>session_headers</code>/<code>session_cookie_jar</code>, re-parsing <code>manifests</code>) →
get the licence in proxy mode or <code>server_cdm</code> mode → <code>close()</code> (<code>DELETE</code>, saving any returned
<code>cache</code>).</li>
<li><strong>Server resolution.</strong> <code>resolve_server()</code> reads <code>config.remote_services.&lt;name&gt;</code>
+20 -21
View File
@@ -2873,12 +2873,18 @@ exact forms each proxy provider accepts.</p>
forwarder for it. See <a href="#control-d">Control D</a>.</p>
<h3 id="provider-load-order">Provider load order<a class="headerlink" href="#provider-load-order" title="Permanent link">&para;</a></h3>
<p>When you do a download without <code>--no-proxy</code>, unshackle instantiates every configured
proxy provider once, in this fixed order. It uses that same order for bare-query
resolution:</p>
<p><strong>Basic → ExpressVPN → NordVPN → Proton VPN → Surfshark → Windscribe → Gluetun → Hola → Control D</strong></p>
<p>So if you have both Basic and NordVPN configured and use <code>--proxy us</code>, a <code>us</code> entry in
your Basic config wins, because unshackle tries Basic first. To skip ahead to a specific
proxy provider, prefix the query (<code>--proxy nordvpn:us</code>).</p>
proxy provider once. It uses that same order for bare-query resolution:</p>
<ol>
<li>Basic is always first, so your own proxies win.</li>
<li>The other proxy providers follow in the order of their keys under <code>proxy_providers</code> in
<code>unshackle.yaml</code>. Proxy providers that load without a config key, such as Hola, come
after the listed ones in this default order:
<strong>ExpressVPN → NordVPN → Proton VPN → Surfshark → Windscribe → Gluetun → Hola</strong></li>
<li>Control D is always last.</li>
</ol>
<p>So if you list <code>windscribevpn</code> above <code>nordvpn</code> and use <code>--proxy us</code>, a <code>us</code> entry in your
Basic config answers first, then Windscribe. To skip ahead to a specific proxy provider,
prefix the query (<code>--proxy nordvpn:us</code>).</p>
<p>If a proxy provider cannot load, for example because its server list cannot be fetched
or its config is not valid, unshackle logs a warning and continues with the other proxy
providers. A bare query skips the proxy provider that did not load. A query that names it,
@@ -3930,21 +3936,14 @@ developer note below.</p>
</div>
<h2 id="developer-notes">Developer notes<a class="headerlink" href="#developer-notes" title="Permanent link">&para;</a></h2>
<div class="admonition note">
<p class="admonition-title">Two resolution paths (developers)</p>
<p>unshackle has <strong>two</strong> proxy-resolution code paths that are intentionally not
identical:</p>
<ul>
<li><code>unshackle/commands/dl.py</code> inlines its own logic and loads <strong>all nine</strong> providers,
including Windscribe and Gluetun.</li>
<li><code>unshackle/core/proxies/resolve.py::initialize_proxy_providers()</code> is the shared
resolver used by the REST API handlers and the remote-service client. It <strong>omits</strong>
Windscribe and Gluetun.</li>
</ul>
<p>Both paths accept the same query grammar (a direct URI, a <code>provider:query</code>, a bare
country query tried against providers in order, or a <code>controld://</code> resolver), but the
set of available providers differs. Keep this in mind when you add a proxy provider:
an entry in <code>dl.py</code> does not make it available over the API, and the opposite is also
true.</p>
<p class="admonition-title">One resolution path (developers)</p>
<p><code>dl</code>, <code>search</code>, the REST API handlers and the remote-service client all load proxy
providers through <code>load_proxy_providers()</code> in <code>unshackle/core/proxies/resolve.py</code>.
The REST API and the remote-service client call it through
<code>initialize_proxy_providers()</code>, which leaves out Gluetun because Gluetun starts a
local Docker container. All paths accept the same query grammar: a direct URI, a
<code>provider:query</code>, a bare query tried against providers in order, or a <code>controld://</code>
resolver.</p>
<p>The remote-service client resolves <code>--proxy</code> with its own
<code>resolve_remote_proxy_arg()</code>. It changes a <code>controld:</code> query to a <code>controld://</code>
resolver for the server with <code>get_remote_proxy()</code>, and it removes Control D from a bare
File diff suppressed because it is too large Load Diff
+5 -2
View File
@@ -2222,8 +2222,11 @@ fingerprint. This block is for cross-service defaults only (for example <code>Ac
<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 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>
block straight to that provider's constructor. A bare <code>--proxy</code> query tries Basic first, then
the other proxy providers in the order of their sub-keys, and Control D last (see
<a href="../../../guide/proxies-and-vpn/#provider-load-order">Provider load order</a>). 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>
File diff suppressed because one or more lines are too long