Deployed a4ce70a with MkDocs version: 1.6.1

dev/rest-api/endpoints/index.html

@@ -3936,7 +3936,7 @@ ignore it safely. See <a href="../../creating-a-service/#split-episodes">Split e
 <td><code>exact_lang</code></td>
 <td>boolean</td>
 <td><code>false</code></td>
-<td>Exact language matching.</td>
+<td>A language tag without a region never falls back to another variant. A tag with a region is always exact.</td>
 </tr>
 <tr>
 <td><code>sub_format</code></td>

guide/cli-reference/index.html

@@ -3146,7 +3146,7 @@
 <tr>
 <td><code>--exact-lang</code></td>
 <td>off</td>
-<td>Exact matching only: <code>-l es-419</code> matches <code>es-419</code>, not <code>es-ES</code>. Applies to selection and to sort order.</td>
+<td>A tag without a region selects only the variant it means and never falls back to another: <code>-l es</code> does not select <code>es-419</code>. A tag with a region, such as <code>es-419</code>, is always exact. Applies to selection and to sort order.</td>
 </tr>
 <tr>
 <td><code>--sub-format</code></td>

guide/downloading/index.html

@@ -3471,9 +3471,9 @@ only exclusions adds them to the ones from <code>-l</code>.</p>
 <ul>
 <li><code>orig</code> becomes the title's own original language, so <code>-sl -orig</code> drops the
   subtitles in that language.</li>
-<li><code>--exact-lang</code> applies to exclusions with the same matching rules as selection:
+<li>An exclusion without a region removes every regional form: <code>-es</code> removes <code>es-419</code>
-  <code>-es</code> removes exactly the tracks that <code>es</code> would select. Without it, <code>-es</code> also
+  and <code>es-ES</code>. An exclusion with a region removes only that variant: <code>-es-419</code> removes
-  removes <code>es-419</code> and <code>es-ES</code>.</li>
+  only <code>es-419</code>. With <code>--exact-lang</code>, <code>-es</code> removes only the variant <code>es</code> means.</li>
 <li>Tracks with no language tag are never excluded.</li>
 <li>unshackle rejects <code>-all</code>. Name the languages you do not want instead.</li>
 <li>The comma form is the documented style. <code>-sl -es</code> also works, but a shell can read
@@ -3495,9 +3495,23 @@ works the same way, but the languages you leave out keep their bitrate and codec
 alphabetical one.</p>
 <p>See <a href="../../reference/configuration/download/#subtitle"><code>subtitle.language_priority</code></a> for the details.</p>
 <h3 id="exact-vs-fuzzy-matching">Exact vs fuzzy matching<a class="headerlink" href="#exact-vs-fuzzy-matching" title="Permanent link">&para;</a></h3>
-<p>By default language matching is fuzzy: <code>-l en</code> also accepts <code>en-US</code>, <code>en-GB</code>, and the
+<p>A tag without a region asks for the variant it means: <code>pt</code> is Brazilian Portuguese, <code>es</code> is
-other regional forms (up to a small distance). Pass <code>--exact-lang</code> when only an exact
+Spanish from Spain, and <code>en</code> is US English. With <code>pt-PT</code> and <code>pt-BR</code> tracks, <code>-l pt</code>
-match is acceptable: with it, <code>-l es-419</code> selects only <code>es-419</code>, not <code>es-ES</code>.</p>
+selects <code>pt-BR</code>. If the title has no such variant, the tag takes every regional form, so
+<code>-l es</code> on a title with only <code>es-419</code> selects <code>es-419</code>.</p>
+<p>A tag with a region asks for that variant only: <code>-l es-419</code> selects <code>es-419</code>, never <code>es-ES</code>
+or <code>es-MX</code>. If the service has no <code>es-419</code> track, unshackle reports <code>es-419 not found</code> and
+stops. With <code>--best-available</code>, it continues with the other languages.</p>
+<p>A track without a region matches only the region its language implies. <code>en</code> is US English
+and <code>pt</code> is Brazilian Portuguese, so <code>-l en-US</code> accepts a track tagged <code>en</code>, but <code>-l en-GB</code>
+and <code>-l pt-PT</code> do not accept <code>en</code> or <code>pt</code>. To take any English track, write <code>en</code>.</p>
+<p><code>--exact-lang</code> turns off that fallback: a tag without a region then selects only the
+variant it means, so <code>-l es</code> does not select <code>es-419</code>.</p>
+<p><code>orig</code> is the title language that the service gives. It selects that exact variant first,
+so a <code>fr-CA</code> title takes <code>fr-CA</code> audio over <code>fr-FR</code>. When the title has no track in that
+variant, <code>orig</code> takes the closest regional form, unless you pass <code>--exact-lang</code>.</p>
+<p>An exclusion without a region removes every regional form: <code>-es</code> drops <code>es-ES</code> and <code>es-419</code>.
+See the <a href="#excluding-languages">exclusion rules</a> for <code>--exact-lang</code>.</p>
 <div class="admonition tip">
 <p class="admonition-title">The <code>all</code> and <code>best</code> tokens</p>
 <p>For audio, the tokens <code>all</code> and <code>best</code> bypass the usual one-track-per-language pick

guide/output-and-naming/index.html

@@ -2772,7 +2772,7 @@ For an episode with no on-screen name, <code>{episode_name?}</code> and its adja
 </table>
 <div class="admonition note">
 <p class="admonition-title">How <code>language_tags</code> rules match</p>
-<p>unshackle tries the rules in order, but language comparison is <strong>fuzzy</strong>: a rule condition of <code>en</code> matches <code>en-US</code>, <code>en-GB</code>, and any other <code>en-*</code> form. Within a single rule, <strong>all</strong> conditions must match (AND logic) for it to apply. The first rule that fully matches wins. If none match, unshackle removes <code>{lang_tag?}</code> from the filename cleanly.</p>
+<p>unshackle tries the rules in order, and they compare languages with the same <a href="../downloading/#exact-vs-fuzzy-matching">matching rules</a> as <code>-l</code>: a rule condition of <code>en</code> matches <code>en-US</code>, <code>en-GB</code>, and any other <code>en-*</code> form, but <code>es-419</code> matches only <code>es-419</code>. Within a single rule, <strong>all</strong> conditions must match (AND logic) for it to apply. The first rule that fully matches wins. If none match, unshackle removes <code>{lang_tag?}</code> from the filename cleanly.</p>
 </div>
 <h3 id="episode-specific">Episode-specific<a class="headerlink" href="#episode-specific" title="Permanent link">&para;</a></h3>
 <table>

guide/subtitles/index.html

@@ -2597,7 +2597,7 @@ format-appropriate clean-up to make a single, valid file:</p>
 </tr>
 <tr>
 <td><code>--exact-lang</code></td>
-<td>Exact language matching, with no regional variants.</td>
+<td>A tag without a region never falls back to another variant: <code>es</code> does not match <code>es-419</code>.</td>
 </tr>
 <tr>
 <td><code>-S</code>, <code>--subs-only</code></td>
@@ -2622,13 +2622,14 @@ format-appropriate clean-up to make a single, valid file:</p>
 To narrow it down, pass a comma-separated list of language tags:</p>
 <div class="language-shell highlight"><span class="filename">English and Spanish subtitles only</span><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--s-lang<span class="w"> </span>en,es<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
 </span></code></pre></div>
-<p>Language matching is fuzzy by default: <code>en</code> matches <code>en-US</code>, <code>en-GB</code>, and similar
+<p>A tag without a region selects the variant it means, such as <code>en-US</code> for <code>en</code>, and every
-variants. If a requested language is missing but others were found, unshackle continues
+regional form only when the title has no such variant. A tag with a region matches only
-with whatever remains and tells you which languages it dropped.</p>
+that variant:</p>
-<p>For strict matching, where <code>es-419</code> matches only <code>es-419</code> and never <code>es-ES</code>, add
+<div class="language-shell highlight"><span class="filename">Only Latin-American Spanish, no other Spanish variants</span><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--s-lang<span class="w"> </span>es-419<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="s1">'https://www.example.com/...'</span>
-<code>--exact-lang</code>:</p>
-<div class="language-shell highlight"><span class="filename">Only Latin-American Spanish, no other Spanish variants</span><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--s-lang<span class="w"> </span>es-419<span class="w"> </span>--exact-lang<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="s1">'https://www.example.com/...'</span>
 </span></code></pre></div>
+<p>If a requested language is missing, unshackle stops with an error. With <code>--best-available</code>,
+it continues with the languages it found and tells you which ones it dropped. See
+<a href="../downloading/#exact-vs-fuzzy-matching">exact vs fuzzy matching</a> for the full rules.</p>
 <h3 id="requiring-languages-before-downloading">Requiring languages before downloading<a class="headerlink" href="#requiring-languages-before-downloading" title="Permanent link">&para;</a></h3>
 <p><code>--require-subs</code> is a gate rather than a filter. It downloads <strong>all</strong> available
 subtitles, but only if every language you name is present. If any is missing, the title
@@ -2699,10 +2700,11 @@ CCExtractor tool on your <code>PATH</code>.</p>
 can make a clean non-SDH version for you by stripping the hearing-impaired cues:
 sound effects, speaker labels, music notes, and similar. This is on by default and
 controlled by the <a href="#subtitle-configuration"><code>strip_sdh</code></a> config key.</p>
-<p>The check is deliberately loose: if a close-enough plain track already exists (for
+<p>The check uses the same <a href="../downloading/#exact-vs-fuzzy-matching">matching rules</a> as
-example an <code>en-GB</code> non-SDH track when the SDH track is <code>en-US</code>), no stripped copy is
+<code>--s-lang</code>. A plain track covers an SDH track only when it is the same variant: <code>en</code> and
-created. When a stripped copy <em>is</em> created, the original SDH track is kept as well, so
+<code>en-US</code> cover each other, but a plain <code>en-GB</code> track does not stop a stripped <code>en</code> or <code>en-US</code>
-you end up with both.</p>
+copy. When unshackle creates a stripped
+copy, it keeps the original SDH track as well, so you end up with both.</p>
 <p>The <a href="#subtitle-configuration"><code>sdh_method</code></a> config key selects the stripping engine
 itself. The default (<code>auto</code>) prefers the <code>subby</code> cleaner for SRT, falls back to
 SubtitleEdit when you install it, and otherwise uses the built-in <code>filter-subs</code>

reference/api/tracks/index.html

@@ -2848,6 +2848,17 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#unshackle.core.tracks.Tracks.first_match_index" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;first_match_index
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -4057,6 +4068,17 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#unshackle.core.tracks.Tracks.first_match_index" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;first_match_index
+      
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -7693,6 +7715,31 @@ selections) stays unflagged, and the standalone mux loop muxes it alongside the
 <div class="doc doc-object doc-function">
 
 
+<h3 id="unshackle.core.tracks.Tracks.first_match_index" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">first_match_index</span>
+
+
+  <span class="doc doc-labels">
+      <small class="doc doc-label doc-label-staticmethod"><code>staticmethod</code></small>
+  </span>
+
+<a href="#unshackle.core.tracks.Tracks.first_match_index" class="headerlink" title="Permanent link">&para;</a></h3>
+<div class="language-python doc-signature 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="nf">first_match_index</span><span class="p">(</span><span class="n">tracks</span><span class="p">,</span> <span class="n">language</span><span class="p">)</span>
+</span></code></pre></div>
+
+    <div class="doc doc-contents ">
+
+        <p>The index of the first track that <code>language</code> asks for, matched against every track at once.</p>
+<p>Matching the whole list lets the RFC 4647 string preference pick en-US over en.</p>
+
+
+    </div>
+
+</div>
+
+<div class="doc doc-object doc-function">
+
+
 <h3 id="unshackle.core.tracks.Tracks.mux" class="doc doc-heading">
 <code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">mux</span>
 

reference/configuration/download/index.html

@@ -2596,12 +2596,14 @@ controls the order inside each language.</p>
 </tbody>
 </table>
 <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
+<p>Use <code>orig</code> in the list for the title's original language. A base tag puts the variant it
-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
+means first and its other regional forms after it, so <code>en</code> sorts <code>en-US</code> and then
-<code>zh-Hant</code>, which you must name. The sort ignores entries that match no track, and it
+<code>en-GB</code>, but <code>zh</code> does <strong>not</strong> cover <code>zh-Hant</code>, which you must name. A tag with a region sorts only that variant, so
-ignores entries that are not valid language tags.</p>
+<code>[en-US]</code> puts <code>en-US</code> before <code>en-GB</code>. The sort ignores entries that match no track, and
-<p><code>--exact-lang</code> applies here too: with it, <code>en</code> sorts only <code>en</code>, and <code>en-US</code> falls to
+it ignores entries that are not valid language tags.</p>
-the alphabetical tail with the rest. Name each tag you want when you use that flag.</p>
+<p><code>--exact-lang</code> applies here too: with it, <code>en</code> sorts only the variant it means, and
+<code>en-GB</code> falls to the alphabetical tail with the rest. Name each tag you want when you use
+that flag.</p>
 </div>
 <div class="admonition note">
 <p class="admonition-title"><code>type_priority</code> picks the default subtitle only with <code>muxing.default_language</code></p>
@@ -2666,7 +2668,7 @@ bitrate alone, with those same Atmos/descriptive rules still applied.</p>
 <td><code>default_language</code></td>
 <td>dict</td>
 <td><code>{}</code></td>
-<td>Force which language is flagged <em>default</em> per track type, e.g. <code>{audio: en, subtitle: en}</code>.</td>
+<td>Force which language is flagged <em>default</em> per track type, e.g. <code>{audio: en, subtitle: en}</code>. A tag with a region, such as <code>en-US</code>, matches only that variant.</td>
 </tr>
 <tr>
 <td><code>merge_audio</code></td>
@@ -2730,7 +2732,8 @@ bitrate alone, with those same Atmos/descriptive rules still applied.</p>
 </table>
 <p>Each language condition takes one language tag or a list of them. A list matches when <strong>any</strong>
 entry matches, except <code>subs_contain_all</code>, which needs them all. An entry that is not a valid
-language tag (for example <code>japanese</code>) never matches. <code>dual</code>, <code>multi</code> and <code>dubbed</code> take a bare
+language tag (for example <code>japanese</code>) never matches. A tag with a region matches only that
+variant, so <code>audio: es-419</code> does not match <code>es-ES</code> audio. <code>dual</code>, <code>multi</code> and <code>dubbed</code> take a bare
 <code>true</code> or <code>false</code>, not a quoted string. unshackle skips a rule with a condition name it does
 not know, or with any other value in a boolean condition. It logs a warning in each of these
 cases and tries the next rule.</p>

sitemap.xml

@@ -2,154 +2,154 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://docs.unshackle.dev/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/dev/creating-a-service/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/dev/service-architecture/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/dev/rest-api/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/dev/rest-api/authentication/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/dev/rest-api/dashboard/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/dev/rest-api/endpoints/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/dev/rest-api/errors/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/dev/rest-api/job-lifecycle/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/dev/rest-api/quickstart/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/dev/rest-api/remote-sessions/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/getting-started/configuration-file/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/getting-started/installation/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/getting-started/quickstart/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/guide/cli-reference/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/guide/downloading/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/guide/drm-and-cdm/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/guide/output-and-naming/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/guide/proxies-and-vpn/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/guide/subtitles/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/guide/troubleshooting/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/guide/vaults/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/api/config/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/api/drm/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/api/service/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/api/titles/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/api/tracks/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/configuration/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/configuration/directories/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/configuration/download/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/configuration/drm/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/configuration/example/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/configuration/misc/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/configuration/network/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/configuration/output/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/configuration/post-scripts/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/configuration/services/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
     <url>
          <loc>https://docs.unshackle.dev/reference/configuration/vaults/</loc>
-         <lastmod>2026-10-14</lastmod>
+         <lastmod>2026-10-15</lastmod>
     </url>
 </urlset>