Deployed e29a5239 with MkDocs version: 1.6.1

2026-11-14 13:05:09 +00:00 · 2026-11-12 11:47:48 +00:00
parent 21da928859
commit 91315d7f79
14 changed files with 264 additions and 63 deletions
@@ -3703,7 +3703,7 @@ ignore it safely. See <a href="../../creating-a-service/#split-episodes">Split e
 </span><span id="__span-8-6"><a id="__codelineno-8-6" name="__codelineno-8-6" href="#__codelineno-8-6"></a><span class="w">      </span><span class="nt">"bitrate"</span><span class="p">:</span><span class="w"> </span><span class="mi">8000</span><span class="p">,</span><span class="w"> </span><span class="nt">"bitrate_bps"</span><span class="p">:</span><span class="w"> </span><span class="mi">8000000</span><span class="p">,</span><span class="w"> </span><span class="nt">"width"</span><span class="p">:</span><span class="w"> </span><span class="mi">3840</span><span class="p">,</span><span class="w"> </span><span class="nt">"height"</span><span class="p">:</span><span class="w"> </span><span class="mi">2160</span><span class="p">,</span>
 </span><span id="__span-8-7"><a id="__codelineno-8-7" name="__codelineno-8-7" href="#__codelineno-8-7"></a><span class="w">      </span><span class="nt">"resolution"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2160p"</span><span class="p">,</span><span class="w"> </span><span class="nt">"fps"</span><span class="p">:</span><span class="w"> </span><span class="s2">"24"</span><span class="p">,</span><span class="w"> </span><span class="nt">"range"</span><span class="p">:</span><span class="w"> </span><span class="s2">"HDR10"</span><span class="p">,</span>
 </span><span id="__span-8-8"><a id="__codelineno-8-8" name="__codelineno-8-8" href="#__codelineno-8-8"></a><span class="w">      </span><span class="nt">"range_display"</span><span class="p">:</span><span class="w"> </span><span class="s2">"HDR"</span><span class="p">,</span><span class="w"> </span><span class="nt">"scan_type"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w"> </span><span class="nt">"closed_captions"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span>
-</span><span id="__span-8-9"><a id="__codelineno-8-9" name="__codelineno-8-9" href="#__codelineno-8-9"></a><span class="w">      </span><span class="nt">"dv_compatible_bitstream"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"> </span><span class="nt">"hdr10plus"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"> </span><span class="nt">"hdr10_base"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"> </span><span class="nt">"language"</span><span class="p">:</span><span class="w"> </span><span class="s2">"en"</span><span class="p">,</span>
+</span><span id="__span-8-9"><a id="__codelineno-8-9" name="__codelineno-8-9" href="#__codelineno-8-9"></a><span class="w">      </span><span class="nt">"dv_compatible_bitstream"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"> </span><span class="nt">"hdr10plus"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"> </span><span class="nt">"hdr10_base"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"> </span><span class="nt">"stereo"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"> </span><span class="nt">"language"</span><span class="p">:</span><span class="w"> </span><span class="s2">"en"</span><span class="p">,</span>
 </span><span id="__span-8-10"><a id="__codelineno-8-10" name="__codelineno-8-10" href="#__codelineno-8-10"></a><span class="w">      </span><span class="nt">"is_original_lang"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
 </span><span id="__span-8-11"><a id="__codelineno-8-11" name="__codelineno-8-11" href="#__codelineno-8-11"></a><span class="w">      </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w"> </span><span class="nt">"track_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"English"</span><span class="p">,</span><span class="w"> </span><span class="nt">"needs_repack"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"> </span><span class="nt">"edition"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span><span class="w"> </span><span class="nt">"note"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w"> </span><span class="nt">"data"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
 </span><span id="__span-8-12"><a id="__codelineno-8-12" name="__codelineno-8-12" href="#__codelineno-8-12"></a><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="nt">"descriptor"</span><span class="p">:</span><span class="w"> </span><span class="s2">"DASH"</span>
@@ -3234,6 +3234,7 @@ the API surface.</p>
 HLS and DASH streams that carry a valid DV RPU but advertise plain HEVC, with DV only in the
 supplemental codecs (<code>dv_compatible_bitstream</code>). <code>--list</code> shows such a track as <code>HDR10+DV</code> or <code>HDR10P+DV</code>.
 A service sets <code>hdr10_base</code> on a DV track that has an HDR10 base layer (DV profile 8.1), and <code>--list</code> shows it as <code>DV+HDR10</code>.
+The HLS and DASH parsers set <code>stereo</code> on a stereoscopic 3D (MV-HEVC) track: an HLS <code>REQ-VIDEO-LAYOUT</code> that names <code>CH-STEREO</code>, or a DV profile 20 codec. <code>--list</code> shows it as <code>3D</code>.
 <strong>Hybrid</strong> processing (<code>Video.Range.HYBRID</code>) selects an HDR10(+) base and a DV donor,
 extracts the RPU with <code>dovi_tool</code>, and injects it onto the base layer, to make a single
 track that carries both HDR10 metadata and the DV RPU. Both are automatic once the
@@ -2703,7 +2703,7 @@ download. For example, <code>dovi_tool</code> only matters if you download Dolby
 <tr>
 <td>MP4Box (GPAC)</td>
 <td><code>MP4Box</code></td>
-<td>Muxing DTS:X Profile 2 (DTS-UHD) and MPEG-H audio</td>
+<td>Muxing DTS:X Profile 2 (DTS-UHD) and MPEG-H audio, and 3D video</td>
 </tr>
 <tr>
 <td>dovi_tool</td>
@@ -2758,9 +2758,9 @@ download. For example, <code>dovi_tool</code> only matters if you download Dolby
 </tbody>
 </table>
 <div class="admonition info">
-<p class="admonition-title">MP4Box is only used for DTS:X Profile 2 and MPEG-H</p>
-<p>Titles with DTS:X Profile 2 (DTS-UHD) or MPEG-H audio mux to MP4; everything else muxes to MKV
-with <code>mkvmerge</code>. Install with <code>apt install gpac</code>.</p>
+<p class="admonition-title">MP4Box is only used for DTS:X Profile 2, MPEG-H and 3D video</p>
+<p>Titles with DTS:X Profile 2 (DTS-UHD) or MPEG-H audio, or a stereoscopic 3D video track, mux to
+MP4; everything else muxes to MKV with <code>mkvmerge</code>. Install with <code>apt install gpac</code>.</p>
 </div>
 <div class="admonition tip">
 <p class="admonition-title">SubtitleEdit specifics</p>
@@ -3415,6 +3415,9 @@ alone, so unshackle selects it only when you ask for it with <code>-v LCEVC</cod
 </tbody>
 </table>
 <p>The output file of a track with a Dolby Vision profile 8 RPU plays as Dolby Vision on a DV screen.</p>
+<p><code>--list</code> adds <code>3D</code> to a stereoscopic 3D (MV-HEVC) track, for example <code>[H.265, DV, 3D]</code>. When a title
+has a 2D and a 3D track at the same resolution, unshackle selects the 2D track. A 3D title muxes to
+MP4, see <a href="../output-and-naming/#3d-output">3D output</a>.</p>
 <div class="admonition warning">
 <p class="admonition-title">HYBRID requires dovi_tool</p>
 <p><code>-r HYBRID</code> makes a single hybrid track by injecting the Dolby Vision RPU
@@ -1077,6 +1077,17 @@
    </span>
  </a>
  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#3d-output" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        3D output
+      
+    </span>
+  </a>
+  
 </li>
        
      </ul>
@@ -2484,6 +2495,17 @@
    </span>
  </a>
  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#3d-output" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        3D output
+      
+    </span>
+  </a>
+  
 </li>
        
      </ul>
@@ -2627,7 +2649,7 @@
 <li><strong>Output directory</strong>: <code>directories.downloads</code> from your config, or whatever you pass to <code>-o/--output</code> on the command line for a single run.</li>
 <li><strong>Folder template</strong>: an optional per-title subfolder. unshackle <strong>always</strong> puts TV episodes and songs in a folder. Movies only get one if you define a <code>movies</code> folder template, or a single-string <code>folder</code> template that applies to all title kinds (see <a href="#folder-templates">Folder templates</a>).</li>
 <li><strong>Filename template</strong>: the <code>output_template</code> for the title kind (movie, series, or song).</li>
-<li><strong>Extension</strong>: chosen by the muxer for a movie or an episode: <code>.mkv</code> for video, <code>.mka</code> for audio-only, <code>.mks</code> for subtitle-only, <code>.mp4</code> for <a href="#dtsx-profile-2-and-mpeg-h-output">DTS:X Profile 2 and MPEG-H audio</a>. unshackle does not mux a song. It remuxes a song into the container of its codec, such as <code>.flac</code>, <code>.opus</code>, or <code>.m4a</code>. Read <a href="#music-output-files">Music output files</a>.</li>
+<li><strong>Extension</strong>: chosen by the muxer for a movie or an episode: <code>.mkv</code> for video, <code>.mka</code> for audio-only, <code>.mks</code> for subtitle-only, <code>.mp4</code> for <a href="#dtsx-profile-2-and-mpeg-h-output">DTS:X Profile 2 and MPEG-H audio</a> and <a href="#3d-output">3D video</a>. unshackle does not mux a song. It remuxes a song into the container of its codec, such as <code>.flac</code>, <code>.opus</code>, or <code>.m4a</code>. Read <a href="#music-output-files">Music output files</a>.</li>
 </ul>
 <div class="admonition example">
 <p class="admonition-title">A typical episode path</p>
@@ -2793,6 +2815,11 @@ For an episode with no on-screen name, <code>{episode_name?}</code> and its adja
 <td><code>HFR</code></td>
 </tr>
 <tr>
+<td><code>3d</code></td>
+<td>Stereoscopic 3D marker (MV-HEVC video)</td>
+<td><code>3D</code></td>
+</tr>
+<tr>
 <td><code>edition</code></td>
 <td>Edition label from the track, if any</td>
 <td><code>Directors Cut</code></td>
@@ -3290,6 +3317,21 @@ Without MP4Box installed the mux stops.</p>
 <li>SubStation Alpha (<code>.ass</code>) subtitles</li>
 <li>container tags (<code>mkvpropedit</code>)</li>
 </ul>
+<h3 id="3d-output">3D output<a class="headerlink" href="#3d-output" title="Permanent link">&para;</a></h3>
+<p>A stereoscopic 3D (MV-HEVC) video track also muxes to MP4 with MP4Box, because Matroska has no
+mapping for its second view and <code>mkvmerge</code> drops it. There is no 3D Matroska output. unshackle
+finds a 3D track from the manifest, or from a second video layer in the downloaded file. The MP4
+title loses the same items as above. For a 3D title, unshackle also:</p>
+<ul>
+<li>decrypts the track with mp4decrypt, whatever <a href="../../reference/configuration/drm/#decryption"><code>decryption</code></a> selects</li>
+<li>writes QuickTime chapters</li>
+<li>keeps the whole downloaded segments of a <code>--sample</code> run, because the MP4Box cut removes the 3D signalling</li>
+<li>does not repack the track or rewrite its colour metadata with FFmpeg</li>
+<li>writes no <code>--include-sample</code> sample, because <code>mkvmerge</code> cuts only Matroska files</li>
+<li>never uses the track in a <code>HYBRID</code> merge</li>
+</ul>
+<p>A Dolby Vision profile 20 track has no HDR10 base layer, so a player without Dolby Vision shows
+wrong colours.</p>
 <p>You configure muxing (the combination of video, audio, subtitle, chapter and attachment tracks into a single Matroska file with <code>mkvmerge</code>) under the <code>muxing</code> config key. unshackle muxes only movies and episodes. Read <a href="#music-output-files">Music output files</a> for what a music download does instead.</p>
 <div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-17-1"><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a><span class="nt">muxing</span><span class="p">:</span>
 </span><span id="__span-17-2"><a id="__codelineno-17-2" name="__codelineno-17-2" href="#__codelineno-17-2"></a><span class="w">  </span><span class="nt">set_title</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
@@ -3365,7 +3407,8 @@ Without MP4Box installed the mux stops.</p>
 <h2 id="sample-files">Sample files<a class="headerlink" href="#sample-files" title="Permanent link">&para;</a></h2>
 <p><a href="../cli-reference/#output-muxing-files"><code>--sample</code></a> and <code>--include-sample</code> write a sample into a
 <code>Sample</code> folder inside the output folder of the title. The sample keeps the filename of the
-title, with a <code>SAMPLE</code> tag at the end. The tag uses the separator of the output template.</p>
+title, with a <code>SAMPLE</code> tag at the end. The tag uses the separator of the output template.
+<code>--include-sample</code> cuts the sample with <code>mkvmerge</code>, so a title that muxes to MP4 gets no sample.</p>
 <div class="language-text highlight"><span class="filename">A movie with --include-sample</span><pre><span></span><code><span id="__span-18-1"><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a>Some.Movie.2026.1080p.EXAMPLE.WEB-DL.H.264-TAG/
 </span><span id="__span-18-2"><a id="__codelineno-18-2" name="__codelineno-18-2" href="#__codelineno-18-2"></a>├── Some.Movie.2026.1080p.EXAMPLE.WEB-DL.H.264-TAG.mkv
 </span><span id="__span-18-3"><a id="__codelineno-18-3" name="__codelineno-18-3" href="#__codelineno-18-3"></a>└── Sample/
@@ -4499,7 +4499,7 @@ directly, and a WASM module extracts the content keys locally.</p>
      <tbody>
          <tr class="doc-section-item">
            <td>
-                  <code><span title="TicketNotFound">TicketNotFound</span></code>
+                  <code>TicketNotFound</code>
            </td>
            <td>
              <div class="doc-md-description">
@@ -4509,7 +4509,7 @@ directly, and a WASM module extracts the content keys locally.</p>
          </tr>
          <tr class="doc-section-item">
            <td>
-                  <code><span title="KeyExtractionFailed">KeyExtractionFailed</span></code>
+                  <code>KeyExtractionFailed</code>
            </td>
            <td>
              <div class="doc-md-description">
@@ -5955,7 +5955,7 @@ and more.</p>
      <tbody>
          <tr class="doc-section-item">
            <td>
-                  <code><span title="PSSHNotFound">PSSHNotFound</span></code>
+                  <code>PSSHNotFound</code>
            </td>
            <td>
              <div class="doc-md-description">
@@ -5965,7 +5965,7 @@ and more.</p>
          </tr>
          <tr class="doc-section-item">
            <td>
-                  <code><span title="KIDNotFound">KIDNotFound</span></code>
+                  <code>KIDNotFound</code>
            </td>
            <td>
              <div class="doc-md-description">
@@ -6014,7 +6014,7 @@ It is <em>rare</em> to need to use this.</p>
      <tbody>
          <tr class="doc-section-item">
            <td>
-                  <code><span title="PSSHNotFound">PSSHNotFound</span></code>
+                  <code>PSSHNotFound</code>
            </td>
            <td>
              <div class="doc-md-description">
@@ -6024,7 +6024,7 @@ It is <em>rare</em> to need to use this.</p>
          </tr>
          <tr class="doc-section-item">
            <td>
-                  <code><span title="KIDNotFound">KIDNotFound</span></code>
+                  <code>KIDNotFound</code>
            </td>
            <td>
              <div class="doc-md-description">
@@ -3245,6 +3245,17 @@
    </span>
  </a>
  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#unshackle.core.tracks.Video.is_stereo" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;is_stereo
+      
+    </span>
+  </a>
+  
 </li>
        
          <li class="md-nav__item">
@@ -3267,6 +3278,28 @@
    </span>
  </a>
  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#unshackle.core.tracks.Video.download" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;download
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#unshackle.core.tracks.Video.repackage" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;repackage
+      
+    </span>
+  </a>
+  
 </li>
        
          <li class="md-nav__item">
@@ -4817,6 +4850,17 @@
    </span>
  </a>
  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#unshackle.core.tracks.Video.is_stereo" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;is_stereo
+      
+    </span>
+  </a>
+  
 </li>
        
          <li class="md-nav__item">
@@ -4839,6 +4883,28 @@
    </span>
  </a>
  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#unshackle.core.tracks.Video.download" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;download
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#unshackle.core.tracks.Video.repackage" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;repackage
+      
+    </span>
+  </a>
+  
 </li>
        
          <li class="md-nav__item">
@@ -8361,7 +8427,7 @@ of <code>get_init_segment</code> to find the Key ID.</p>
                <code>service</code>
            </td>
            <td>
-                  <code><span title="Service">Service</span> | None</code>
+                  <code>Service | None</code>
            </td>
            <td>
              <div class="doc-md-description">
@@ -8755,7 +8821,8 @@ A subtitle in an unlisted codec is always kept.</p>

    <div class="doc doc-contents ">

-        <p>Sort video tracks by resolution then bitrate, and optionally language.</p>
+        <p>Sort video tracks by resolution, 2D before 3D, then bitrate, and optionally language.</p>
+<p>A 3D track carries two views, so its higher bitrate would otherwise rank it over the 2D one.</p>


    </div>
@@ -8905,7 +8972,7 @@ track twice.</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>
+HDR10+. A 3D track is never an ingredient: dovi_tool does not handle a second view.</p>


    </div>
@@ -9213,8 +9280,9 @@ share a video list must pass distinct paths to avoid clobbering each other.</p>
 </span><span id="__span-0-11"><a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="n">dv_compatible_bitstream</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
 </span><span id="__span-0-12"><a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">hdr10plus</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
 </span><span id="__span-0-13"><a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">hdr10_base</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
-</span><span id="__span-0-14"><a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="o">**</span><span class="n">kwargs</span><span class="p">,</span>
-</span><span id="__span-0-15"><a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a><span class="p">)</span>
+</span><span id="__span-0-14"><a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">stereo</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
+</span><span id="__span-0-15"><a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="o">**</span><span class="n">kwargs</span><span class="p">,</span>
+</span><span id="__span-0-16"><a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a><span class="p">)</span>
 </span></code></pre></div>

    <div class="doc doc-contents ">
@@ -9371,6 +9439,22 @@ All strings will be cast to either a number or float.</p>
                  <code>False</code>
            </td>
          </tr>
+          <tr class="doc-section-item">
+            <td>
+                <code>stereo</code>
+            </td>
+            <td>
+                  <code><span title="bool">bool</span></code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>The track is stereoscopic 3D (MV-HEVC), with a second view for the other eye.</p>
+              </div>
+            </td>
+            <td>
+                  <code>False</code>
+            </td>
+          </tr>
      </tbody>
    </table>
        <p>Note: If codec, bitrate, width, height, or fps is not specified, unshackle can
@@ -9606,6 +9690,32 @@ FFmpeg's AVColorPrimaries/AVColorTransferCharacteristic enums.</p>
 <div class="doc doc-object doc-function">


+<h3 id="unshackle.core.tracks.Video.is_stereo" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">is_stereo</span>
+
+
+  <span class="doc doc-labels">
+      <small class="doc doc-label doc-label-staticmethod"><code>staticmethod</code></small>
+  </span>
+
+<a href="#unshackle.core.tracks.Video.is_stereo" 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">is_stereo</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="n">codecs</span><span class="p">,</span> <span class="n">supplemental_codecs</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">video_layout</span><span class="o">=</span><span class="kc">None</span>
+</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="p">)</span>
+</span></code></pre></div>
+
+    <div class="doc doc-contents ">
+
+        <p>Whether a track is stereoscopic 3D: the HLS REQ-VIDEO-LAYOUT names CH-STEREO, or a codec is DV profile 20.</p>
+
+
+    </div>
+
+</div>
+
+<div class="doc doc-object doc-function">
+
+
 <h3 id="unshackle.core.tracks.Video.is_dv_composite" class="doc doc-heading">
 <code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">is_dv_composite</span>

@@ -9650,6 +9760,46 @@ FFmpeg's AVColorPrimaries/AVColorTransferCharacteristic enums.</p>
 <div class="doc doc-object doc-function">


+<h3 id="unshackle.core.tracks.Video.download" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">download</span>
+
+
+<a href="#unshackle.core.tracks.Video.download" 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">download</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
+</span></code></pre></div>
+
+    <div class="doc doc-contents ">
+
+        <p>Download the track and mark it 3D when the file holds a second view; a 3D track is never repacked.</p>
+
+
+    </div>
+
+</div>
+
+<div class="doc doc-object doc-function">
+
+
+<h3 id="unshackle.core.tracks.Video.repackage" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">repackage</span>
+
+
+<a href="#unshackle.core.tracks.Video.repackage" 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">repackage</span><span class="p">(</span><span class="n">bsf_v</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
+</span></code></pre></div>
+
+    <div class="doc doc-contents ">
+
+        <p>Remux with FFmpeg, except a 3D track: an FFmpeg remux rewrites its stereo and DV boxes.</p>
+
+
+    </div>
+
+</div>
+
+<div class="doc doc-object doc-function">
+
+
 <h3 id="unshackle.core.tracks.Video.vui_bsf" class="doc doc-heading">
 <code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">vui_bsf</span>

@@ -9661,8 +9811,9 @@ FFmpeg's AVColorPrimaries/AVColorTransferCharacteristic enums.</p>
    <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 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
+<p>Returns None when a rewrite is not necessary or not safe: SDR/DV/HYBRID ranges, non-AVC/HEVC
+codecs, a 3D track (an FFmpeg remux rewrites its stereo and DV boxes), 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>


@@ -2386,6 +2386,9 @@ case-insensitively. <code>"mp4decrypt"</code> selects Bento4's mp4decrypt, and <
 (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>
+<p>unshackle decrypts a stereoscopic 3D (MV-HEVC) track with mp4decrypt whatever this setting says.
+shaka-packager refuses its Dolby Vision configuration (version 3), and before v3.5.0 it also drops
+the boxes of the second view.</p>
 <p>mp4decrypt finds a content key by the KID in the first <code>sinf</code> box of the track. When that box
 has no CENC <code>tenc</code> (for example, a PIFF <code>sinf</code> before the CENC one), unshackle also gives
 mp4decrypt the content key of that KID by track ID. When mp4decrypt copies a track through
@@ -2143,7 +2143,7 @@ folder-kind keys.</p>
 <code>absolute</code>, <code>date</code>, <code>quality</code>, <code>resolution</code>, <code>source</code>, <code>tag</code>, <code>track_number</code>, <code>artist</code>,
 <code>album_artist</code>, <code>album</code>, <code>disc</code>, <code>track_total</code>, <code>disc_total</code>, <code>release_type</code>, <code>genre</code>,
 <code>explicit</code>, <code>isrc</code>, <code>upc</code>, <code>label</code>, <code>audio</code>, <code>audio_channels</code>, <code>audio_full</code>, <code>atmos</code>,
-<code>dual</code>, <code>multi</code>, <code>dubbed</code>, <code>video</code>, <code>hdr</code>, <code>hfr</code>, <code>edition</code>, <code>repack</code>, <code>lang_tag</code>,
+<code>dual</code>, <code>multi</code>, <code>dubbed</code>, <code>video</code>, <code>hdr</code>, <code>hfr</code>, <code>3d</code>, <code>edition</code>, <code>repack</code>, <code>lang_tag</code>,
 <code>title_type</code>.</p>
 </details>
 <div class="admonition warning">
@@ -2261,7 +2261,7 @@ order and the first match wins. If no rule matches, the global <code>tag</code>
 <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 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>title_type</code>, <code>quality</code>, <code>resolution</code>, <code>source</code>, <code>video</code>, <code>hdr</code>, <code>hfr</code>, <code>3d</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. 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
@@ -2516,7 +2516,7 @@ values.</p>
 <td>As in the filename template: <code>{season_episode}</code> keeps the part suffix (<code>S01E05.Part.1</code>) while <code>{episode}</code> drops it</td>
 </tr>
 <tr>
-<td><code>{quality}</code> <code>{resolution}</code> <code>{hdr}</code> <code>{hfr}</code> <code>{vcodec}</code> <code>{acodec}</code> <code>{edition}</code> <code>{tag}</code> <code>{lang_tag}</code></td>
+<td><code>{quality}</code> <code>{resolution}</code> <code>{hdr}</code> <code>{hfr}</code> <code>{3d}</code> <code>{vcodec}</code> <code>{acodec}</code> <code>{edition}</code> <code>{tag}</code> <code>{lang_tag}</code></td>
 <td>As in the filename template, for this file</td>
 </tr>
 <tr>
@@ -2543,7 +2543,7 @@ string as absent. Write your script to accept an empty value for every variable.
  music has none of them.</li>
 <li><strong>The naming context renders it empty on purpose.</strong> <code>{hdr}</code> is empty for an SDR
  file, because SDR is the absence of an HDR tag in a filename rather than a tag that
-  reads <code>SDR</code>. <code>{edition}</code>, <code>{atmos}</code>, <code>{multi}</code>, <code>{dual}</code> and <code>{hfr}</code> behave the same
+  reads <code>SDR</code>. <code>{edition}</code>, <code>{atmos}</code>, <code>{multi}</code>, <code>{dual}</code>, <code>{hfr}</code> and <code>{3d}</code> behave the same
  way. If your script needs the word <code>SDR</code>, derive it from an empty <code>{hdr}</code> yourself.</li>
 <li>The post-script is a <code>failure</code> one. A failed download has no output file to read metadata
  from, so everything that comes from the output file is empty. See
@@ -2,154 +2,154 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
         <loc>https://docs.unshackle.dev/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/dev/creating-a-service/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/dev/service-architecture/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/dev/rest-api/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/dev/rest-api/authentication/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/dev/rest-api/dashboard/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/dev/rest-api/endpoints/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/dev/rest-api/errors/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/dev/rest-api/job-lifecycle/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/dev/rest-api/quickstart/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/dev/rest-api/remote-sessions/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/getting-started/configuration-file/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/getting-started/installation/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/getting-started/quickstart/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/guide/cli-reference/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/guide/downloading/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/guide/drm-and-cdm/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/guide/output-and-naming/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/guide/proxies-and-vpn/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/guide/subtitles/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/guide/troubleshooting/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/guide/vaults/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/api/config/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/api/drm/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/api/service/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/api/titles/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/api/tracks/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/configuration/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/configuration/directories/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/configuration/download/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/configuration/drm/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/configuration/example/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/configuration/misc/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/configuration/network/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/configuration/output/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/configuration/post-scripts/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/configuration/services/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
    <url>
         <loc>https://docs.unshackle.dev/reference/configuration/vaults/</loc>
-         <lastmod>2026-11-11</lastmod>
+         <lastmod>2026-11-12</lastmod>
    </url>
 </urlset>