Files
unshackle/DOWNLOAD_CONFIG/index.html
T
2026-07-02 15:20:50 +00:00

2090 lines
59 KiB
HTML

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="Configuration reference for unshackle">
<link rel="canonical" href="https://docs.unshackle.dev/DOWNLOAD_CONFIG/">
<link rel="prev" href="../SERVICE_CONFIG/">
<link rel="next" href="../OUTPUT_CONFIG/">
<link rel="icon" href="../assets/favicon.svg">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
<title>Download & Processing - unshackle</title>
<link rel="stylesheet" href="../assets/stylesheets/main.484c7ddc.min.css">
<link rel="stylesheet" href="../assets/stylesheets/palette.ab4e12ef.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#download-processing-configuration" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href=".." title="unshackle" class="md-header__button md-logo" aria-label="unshackle" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="m800-274-80-80v-206H514l-80-80h166v-80q0-50-34.5-85T481-840q-50 0-84 34.5T363-720v9l-73-73q22-61 75-98.5T481-920q83 0 141 58.5T680-720v80h40q33 0 56.5 23.5T800-560v286Zm20 246-62-62q-11 5-20 7.5T720-80H240q-33 0-56.5-23.5T160-160v-400q0-25 14.5-46t37.5-30L28-820l56-56L876-84l-56 56ZM686-160 539-309q-11 11-25.5 17t-31.5 6q-33 0-56.5-23.5T402-366q0-17 6-31.5t17-25.5L286-560h-46v400h446ZM486-360Zm131-97Z"/></svg>
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
unshackle
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Download & Processing
</span>
</div>
</div>
</div>
<form class="md-header__option" data-md-component="palette">
<input class="md-option" data-md-color-media="(prefers-color-scheme)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to light mode" type="radio" name="__palette" id="__palette_0">
<label class="md-header__button md-icon" title="Switch to light mode" for="__palette_1" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7a5 5 0 0 0-5 5 5 5 0 0 0 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1M8 13h8v-2H8zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4a5 5 0 0 0 5-5 5 5 0 0 0-5-5"/></svg>
</label>
<input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_1">
<label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17 7H7a5 5 0 0 0-5 5 5 5 0 0 0 5 5h10a5 5 0 0 0 5-5 5 5 0 0 0-5-5m0 8a3 3 0 0 1-3-3 3 3 0 0 1 3-3 3 3 0 0 1 3 3 3 3 0 0 1-3 3"/></svg>
</label>
<input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="black" data-md-color-accent="indigo" aria-label="Switch to system preference" type="radio" name="__palette" id="__palette_2">
<label class="md-header__button md-icon" title="Switch to system preference" for="__palette_0" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17 7H7a5 5 0 0 0-5 5 5 5 0 0 0 5 5h10a5 5 0 0 0 5-5 5 5 0 0 0-5-5M7 15a3 3 0 0 1-3-3 3 3 0 0 1 3-3 3 3 0 0 1 3 3 3 3 0 0 1-3 3"/></svg>
</label>
</form>
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<a href="javascript:void(0)" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"/></svg>
</a>
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
</button>
</nav>
<div class="md-search__suggest" data-md-component="search-suggest"></div>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://github.com/unshackle-dl/unshackle" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
</div>
<div class="md-source__repository">
GitHub
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
<div class="md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href=".." class="md-tabs__link">
Home
</a>
</li>
<li class="md-tabs__item">
<a href="../CREATING_A_SERVICE/" class="md-tabs__link">
Creating a Service
</a>
</li>
<li class="md-tabs__item md-tabs__item--active">
<a href="../SERVICE_CONFIG/" class="md-tabs__link">
Configuration
</a>
</li>
<li class="md-tabs__item">
<a href="../API/" class="md-tabs__link">
REST API
</a>
</li>
<li class="md-tabs__item">
<a href="../DEBUG_LOGGING/" class="md-tabs__link">
Reference
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href=".." title="unshackle" class="md-nav__button md-logo" aria-label="unshackle" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="m800-274-80-80v-206H514l-80-80h166v-80q0-50-34.5-85T481-840q-50 0-84 34.5T363-720v9l-73-73q22-61 75-98.5T481-920q83 0 141 58.5T680-720v80h40q33 0 56.5 23.5T800-560v286Zm20 246-62-62q-11 5-20 7.5T720-80H240q-33 0-56.5-23.5T160-160v-400q0-25 14.5-46t37.5-30L28-820l56-56L876-84l-56 56ZM686-160 539-309q-11 11-25.5 17t-31.5 6q-33 0-56.5-23.5T402-366q0-17 6-31.5t17-25.5L286-560h-46v400h446ZM486-360Zm131-97Z"/></svg>
</a>
unshackle
</label>
<div class="md-nav__source">
<a href="https://github.com/unshackle-dl/unshackle" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
</div>
<div class="md-source__repository">
GitHub
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href=".." class="md-nav__link">
<span class="md-ellipsis">
Home
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../CREATING_A_SERVICE/" class="md-nav__link">
<span class="md-ellipsis">
Creating a Service
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked>
<label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="">
<span class="md-ellipsis">
Configuration
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3">
<span class="md-nav__icon md-icon"></span>
Configuration
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../SERVICE_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
Service Integration & Auth
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Download & Processing
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Download & Processing
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#downloader" class="md-nav__link">
<span class="md-ellipsis">
downloader
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#dl-dict" class="md-nav__link">
<span class="md-ellipsis">
dl (dict)
</span>
</a>
<nav class="md-nav" aria-label="dl (dict)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#all-available-dl-keys" class="md-nav__link">
<span class="md-ellipsis">
All Available dl Keys
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#real-bitrate-probing" class="md-nav__link">
<span class="md-ellipsis">
Real bitrate probing
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#audio-dict" class="md-nav__link">
<span class="md-ellipsis">
audio (dict)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#subtitle-dict" class="md-nav__link">
<span class="md-ellipsis">
subtitle (dict)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#decryption-str-dict" class="md-nav__link">
<span class="md-ellipsis">
decryption (str | dict)
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../OUTPUT_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
Output & Naming
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../SUBTITLE_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
Subtitles
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../DRM_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
DRM & CDM
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../NETWORK_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
Network & Proxy
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../GLUETUN/" class="md-nav__link">
<span class="md-ellipsis">
Gluetun VPN
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../ADVANCED_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
Advanced & System
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
<label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
<span class="md-ellipsis">
REST API
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_4">
<span class="md-nav__icon md-icon"></span>
REST API
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../API/" class="md-nav__link">
<span class="md-ellipsis">
Overview
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/quick-start/" class="md-nav__link">
<span class="md-ellipsis">
Quick Start
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/authentication/" class="md-nav__link">
<span class="md-ellipsis">
Authentication
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/endpoints/" class="md-nav__link">
<span class="md-ellipsis">
Endpoints
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/endpoint-map/" class="md-nav__link">
<span class="md-ellipsis">
Endpoint Map
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/download-job-lifecycle/" class="md-nav__link">
<span class="md-ellipsis">
Download Job Lifecycle
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/remote-service-sessions/" class="md-nav__link">
<span class="md-ellipsis">
Remote Service Sessions
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/client-configuration/" class="md-nav__link">
<span class="md-ellipsis">
Client Configuration
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/error-responses/" class="md-nav__link">
<span class="md-ellipsis">
Error Responses
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" >
<label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0">
<span class="md-ellipsis">
Reference
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5">
<span class="md-nav__icon md-icon"></span>
Reference
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../DEBUG_LOGGING/" class="md-nav__link">
<span class="md-ellipsis">
Debug Logging
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#downloader" class="md-nav__link">
<span class="md-ellipsis">
downloader
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#dl-dict" class="md-nav__link">
<span class="md-ellipsis">
dl (dict)
</span>
</a>
<nav class="md-nav" aria-label="dl (dict)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#all-available-dl-keys" class="md-nav__link">
<span class="md-ellipsis">
All Available dl Keys
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#real-bitrate-probing" class="md-nav__link">
<span class="md-ellipsis">
Real bitrate probing
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#audio-dict" class="md-nav__link">
<span class="md-ellipsis">
audio (dict)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#subtitle-dict" class="md-nav__link">
<span class="md-ellipsis">
subtitle (dict)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#decryption-str-dict" class="md-nav__link">
<span class="md-ellipsis">
decryption (str | dict)
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1 id="download-processing-configuration">Download &amp; Processing Configuration<a class="headerlink" href="#download-processing-configuration" title="Permanent link">&para;</a></h1>
<p>This document covers configuration options related to downloading and processing media content.</p>
<h2 id="downloader">downloader<a class="headerlink" href="#downloader" title="Permanent link">&para;</a></h2>
<p>unshackle ships a single unified downloader at <code>unshackle/core/downloaders/requests.py</code>. The legacy
<code>aria2c</code>, <code>curl_impersonate</code>, and <code>n_m3u8dl_re</code> backends have been removed; their config blocks no
longer have any effect.</p>
<p>The unified downloader:</p>
<ul>
<li>Works with both a standard <code>requests.Session</code> and <code>RnetSession</code> (rnet/BoringSSL TLS impersonation,
which replaces the previous <code>curl_cffi</code> backend). When a service exposes its own session via
<code>self.session</code>, TLS fingerprinting is preserved on every segment.</li>
<li>Uses adaptive chunk sizing between <strong>512 KB and 4 MB</strong>, picked from the response <code>Content-Length</code>.</li>
<li>Spawns <strong>up to <code>min(16, cpu_count + 4)</code> worker threads</strong> by default for segmented downloads
(override via <code>--workers</code> / <code>dl.workers</code>).</li>
<li>Resumes interrupted downloads via HTTP <code>Range</code> requests (a sibling <code>&lt;file&gt;.!dev</code> control file
marks an in-progress download).</li>
<li>Has a single-URL fast path: if the server supports byte ranges and the file is at least 64 MB,
the file is split into 16 MB parts and downloaded in parallel into a pre-allocated file.</li>
<li>Is selected per-track via <code>track.downloader</code>, which defaults to this unified <code>requests</code> downloader.</li>
</ul>
<p>There is no <code>downloader:</code> config key to set anymore. Setting one to a legacy value will emit a
<code>DeprecationWarning</code> and otherwise be ignored.</p>
<hr />
<h2 id="dl-dict">dl (dict)<a class="headerlink" href="#dl-dict" title="Permanent link">&para;</a></h2>
<p>Pre-define default options and switches of the <code>dl</code> command.
The values will be ignored if explicitly set in the CLI call.</p>
<p>The Key is the option name with dashes as underscores (<code>--v-lang</code> -&gt; <code>v_lang</code>). <code>range</code> and <code>list</code>
work as-is; their internal Python names (<code>range_</code>, <code>list_</code>, suffixed to avoid the builtins) are
also accepted.</p>
<p>For example to set the default primary language to download to German,</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">lang</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">de</span>
</span></code></pre></div>
<p>You can also set multiple preferred languages using a list, e.g.,</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">lang</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="l l-Scalar l-Scalar-Plain">en</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">fr</span>
</span></code></pre></div>
<p>to set how many tracks to download concurrently to 4 and download threads to 16,</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">downloads</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">4</span>
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="nt">workers</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">16</span>
</span></code></pre></div>
<p>to set <code>--bitrate=CVBR</code> for a specific 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">lang</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">de</span>
</span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="nt">EXAMPLE</span><span class="p">:</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">bitrate</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">CVBR</span>
</span></code></pre></div>
<p>or to change the output subtitle format from the default (original format) to WebVTT,</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">sub_format</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">vtt</span>
</span></code></pre></div>
<h3 id="all-available-dl-keys">All Available <code>dl</code> Keys<a class="headerlink" href="#all-available-dl-keys" title="Permanent link">&para;</a></h3>
<p>Below is a comprehensive list of keys that can be pre-defined in the <code>dl</code> section. Each corresponds
to a CLI option on the <code>dl</code> command. CLI arguments always take priority over config values.</p>
<p><strong>Quality and codec:</strong></p>
<table>
<thead>
<tr>
<th>Key</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>quality</code></td>
<td>int or list</td>
<td>best</td>
<td>Resolution(s) to download (e.g., <code>1080</code>, <code>[1080, 2160]</code>)</td>
</tr>
<tr>
<td><code>vcodec</code></td>
<td>str or list</td>
<td>any</td>
<td>Video codec(s): <code>H264</code>, <code>H265</code>, <code>VP9</code>, <code>AV1</code>, <code>VC1</code></td>
</tr>
<tr>
<td><code>acodec</code></td>
<td>str or list</td>
<td>any</td>
<td>Audio codec(s): <code>AAC</code>, <code>AC3</code>, <code>EC3</code>, <code>AC4</code>, <code>OPUS</code>, <code>FLAC</code>, <code>ALAC</code>, <code>DTS</code></td>
</tr>
<tr>
<td><code>vbitrate</code></td>
<td>int</td>
<td>highest</td>
<td>Video bitrate in kbps</td>
</tr>
<tr>
<td><code>abitrate</code></td>
<td>int</td>
<td>highest</td>
<td>Audio bitrate in kbps</td>
</tr>
<tr>
<td><code>vbitrate_range</code></td>
<td>str</td>
<td>none</td>
<td>Video bitrate window in kbps, format <code>MIN-MAX</code> (e.g., <code>6000-7000</code>)</td>
</tr>
<tr>
<td><code>abitrate_range</code></td>
<td>str</td>
<td>none</td>
<td>Audio bitrate window in kbps, format <code>MIN-MAX</code></td>
</tr>
<tr>
<td><code>real_video_bitrate</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Probe actual media size to compute true video bitrates, overriding the manifest's declared value (<code>-rvb</code>). See <a href="#real-bitrate-probing">Real bitrate probing</a></td>
</tr>
<tr>
<td><code>real_audio_bitrate</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Same as above for audio tracks (<code>-rab</code>). Slower than video (more renditions)</td>
</tr>
<tr>
<td><code>range</code> (or <code>range_</code>)</td>
<td>str or list</td>
<td><code>SDR</code></td>
<td>Color range(s): <code>SDR</code>, <code>HDR10</code>, <code>HDR10+</code>, <code>HLG</code>, <code>DV</code>, <code>HYBRID</code></td>
</tr>
<tr>
<td><code>channels</code></td>
<td>float</td>
<td>any</td>
<td>Audio channels (e.g., <code>5.1</code>, <code>7.1</code>)</td>
</tr>
<tr>
<td><code>worst</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Select the lowest bitrate track within the specified quality. Requires <code>quality</code></td>
</tr>
<tr>
<td><code>best_available</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Continue if requested quality is unavailable</td>
</tr>
</tbody>
</table>
<p><strong>Language:</strong></p>
<table>
<thead>
<tr>
<th>Key</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>lang</code></td>
<td>str or list</td>
<td><code>orig</code></td>
<td>Language for video and audio (<code>orig</code> = original language)</td>
</tr>
<tr>
<td><code>v_lang</code></td>
<td>list</td>
<td><code>[]</code></td>
<td>Language override for video tracks only</td>
</tr>
<tr>
<td><code>a_lang</code></td>
<td>list</td>
<td><code>[]</code></td>
<td>Language override for audio tracks only</td>
</tr>
<tr>
<td><code>s_lang</code></td>
<td>list</td>
<td><code>["all"]</code></td>
<td>Language for subtitles</td>
</tr>
<tr>
<td><code>require_subs</code></td>
<td>list</td>
<td><code>[]</code></td>
<td>Required subtitle languages (skip title if missing)</td>
</tr>
<tr>
<td><code>forced_subs</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Include forced subtitle tracks</td>
</tr>
<tr>
<td><code>exact_lang</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Exact language matching (no regional variants)</td>
</tr>
<tr>
<td><code>latest_episode</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Download only the single most recent episode of a series</td>
</tr>
</tbody>
</table>
<p><strong>Track selection:</strong></p>
<table>
<thead>
<tr>
<th>Key</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>video_only</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Only download video tracks</td>
</tr>
<tr>
<td><code>audio_only</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Only download audio tracks</td>
</tr>
<tr>
<td><code>subs_only</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Only download subtitle tracks</td>
</tr>
<tr>
<td><code>chapters_only</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Only download chapters</td>
</tr>
<tr>
<td><code>no_video</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Skip video tracks</td>
</tr>
<tr>
<td><code>no_audio</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Skip audio tracks</td>
</tr>
<tr>
<td><code>no_subs</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Skip subtitle tracks</td>
</tr>
<tr>
<td><code>no_chapters</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Skip chapters</td>
</tr>
<tr>
<td><code>no_atmos</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Exclude Dolby Atmos audio tracks</td>
</tr>
<tr>
<td><code>audio_description</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Include audio description tracks</td>
</tr>
</tbody>
</table>
<p><strong>Output and tagging:</strong></p>
<table>
<thead>
<tr>
<th>Key</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>tag</code></td>
<td>str</td>
<td>config default</td>
<td>Override group tag</td>
</tr>
<tr>
<td><code>repack</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Add REPACK tag to output filename</td>
</tr>
<tr>
<td><code>sub_format</code></td>
<td>str</td>
<td>original</td>
<td>Output subtitle format: <code>srt</code>, <code>vtt</code>, <code>ass</code>, <code>ssa</code>, <code>ttml</code></td>
</tr>
<tr>
<td><code>no_folder</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Disable folder creation for TV shows</td>
</tr>
<tr>
<td><code>no_source</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Remove source tag from filename</td>
</tr>
<tr>
<td><code>no_mux</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Do not mux tracks into a container file</td>
</tr>
<tr>
<td><code>split_audio</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Create separate output files per audio codec</td>
</tr>
<tr>
<td><code>export</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Write a JSON sidecar with manifest URLs, subtitles, per-track KID:KEY, codec/track info</td>
</tr>
</tbody>
</table>
<p><strong>Metadata enrichment:</strong></p>
<table>
<thead>
<tr>
<th>Key</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>tmdb_id</code></td>
<td>int</td>
<td><code>null</code></td>
<td>Use specific TMDB ID for tagging</td>
</tr>
<tr>
<td><code>imdb_id</code></td>
<td>str</td>
<td><code>null</code></td>
<td>Use specific IMDB ID (e.g., <code>tt1375666</code>)</td>
</tr>
<tr>
<td><code>animeapi_id</code></td>
<td>str</td>
<td><code>null</code></td>
<td>Anime database ID via AnimeAPI (e.g., <code>mal:12345</code>, <code>anilist:98765</code>)</td>
</tr>
<tr>
<td><code>enrich</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Override show title and year from external source. Requires <code>tmdb_id</code>, <code>imdb_id</code>, or <code>animeapi_id</code></td>
</tr>
</tbody>
</table>
<p><strong>Download behavior:</strong></p>
<table>
<thead>
<tr>
<th>Key</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>downloads</code></td>
<td>int</td>
<td><code>1</code></td>
<td>Concurrent track downloads</td>
</tr>
<tr>
<td><code>workers</code></td>
<td>int</td>
<td><code>min(16, cpu_count + 4)</code></td>
<td>Max threads per track download (segments / ranged parts)</td>
</tr>
<tr>
<td><code>slow</code></td>
<td>bool or <code>MIN-MAX</code></td>
<td><code>false</code></td>
<td>Randomized delay between titles. <code>true</code> uses 60-120s; pass <code>MIN-MAX</code> (e.g., <code>20-40</code>) for a custom range</td>
</tr>
<tr>
<td><code>no_proxy_download</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Bypass proxy for segment downloads only. Manifest, license, and auth still use proxy</td>
</tr>
<tr>
<td><code>skip_dl</code></td>
<td>bool</td>
<td><code>false</code></td>
<td>Skip download, only get decryption keys</td>
</tr>
<tr>
<td><code>cdm_only</code></td>
<td>bool</td>
<td><code>null</code></td>
<td>Only use CDM (<code>true</code>) or only vaults (<code>false</code>)</td>
</tr>
</tbody>
</table>
<h3 id="real-bitrate-probing">Real bitrate probing<a class="headerlink" href="#real-bitrate-probing" title="Permanent link">&para;</a></h3>
<p>Some services declare inaccurate <code>bandwidth</code>/<code>BANDWIDTH</code> in their manifests — often
a peak or nominal figure that is far from the real average. Because <code>track.bitrate</code>
drives the track listing, sorting, and <code>--vbitrate</code> / <code>--vbitrate-range</code> selection,
a wrong value picks the wrong track.</p>
<p><code>-rvb</code> / <code>--real-video-bitrate</code> (and <code>-rab</code> / <code>--real-audio-bitrate</code> for audio)
probe the actual media size and overwrite <code>track.bitrate</code> with the measured value
(<code>bytes * 8 / duration</code>) before listing and selection. So <code>-rvb --list</code> shows the
true numbers, and <code>-rvb --vbitrate-range 6000-7000</code> selects against them. Without
the flag, behaviour is unchanged (the manifest value is used).</p>
<p>How it works:</p>
<ul>
<li><strong>Single-file tracks</strong> (one whole file per rendition — e.g. DASH <code>SegmentBase</code>
or services that collapse to a <code>BaseURL</code>) are measured <strong>exactly</strong>: the whole
file size over the track duration.</li>
<li><strong>Multi-segment tracks</strong> (most HLS) are a <strong>sampled estimate</strong> — a spread of
segments is probed and extrapolated, typically within a few percent. Segment
bytes include container overhead, so MPEG-TS HLS reads a few percent above the
demuxed stream (this is the real <em>delivered</em> size).</li>
<li>Only the top renditions per quality tier are probed (video grouped by
codec + range, audio by codec + channels + language), in parallel, then extended
downward only as far as needed to keep ranking correct. This keeps the pass fast
even when a service exposes dozens of renditions.</li>
<li>Tracks whose duration cannot be determined fall back to <code>ffprobe</code>; probe failures
are non-fatal and leave the manifest bitrate in place.</li>
</ul>
<p>Per-track before→after values are logged at debug level (run with <code>-d</code>); the
corrected values always appear in the Available Tracks panel.</p>
<p>You can also set per-service <code>dl</code> overrides under the <code>services</code> section (see
<a href="../SERVICE_CONFIG/">Service Integration &amp; Authentication Configuration</a>). Per-service values beat the
global <code>dl:</code> section; explicit CLI arguments beat both:</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">dl</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">lang</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">en</span>
</span><span id="__span-5-3"><a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></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">4</span>
</span><span id="__span-5-4"><a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="w"> </span><span class="nt">workers</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">16</span>
</span><span id="__span-5-5"><a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a>
</span><span id="__span-5-6"><a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a><span class="nt">services</span><span class="p">:</span>
</span><span id="__span-5-7"><a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a><span class="w"> </span><span class="nt">EXAMPLE</span><span class="p">:</span>
</span><span id="__span-5-8"><a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a><span class="w"> </span><span class="nt">dl</span><span class="p">:</span>
</span><span id="__span-5-9"><a id="__codelineno-5-9" name="__codelineno-5-9" href="#__codelineno-5-9"></a><span class="w"> </span><span class="nt">v_lang</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">en</span><span class="p p-Indicator">]</span>
</span><span id="__span-5-10"><a id="__codelineno-5-10" name="__codelineno-5-10" href="#__codelineno-5-10"></a><span class="w"> </span><span class="nt">quality</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1080</span>
</span></code></pre></div>
<hr />
<h2 id="audio-dict">audio (dict)<a class="headerlink" href="#audio-dict" title="Permanent link">&para;</a></h2>
<p>Configuration for audio track selection.</p>
<ul>
<li><code>codec_priority</code>
Optional list of audio codec names defining the preferred order when multiple audio
tracks share the same bitrate and language. Listed codecs are ranked in the order given.
Codecs not in the list retain their bitrate-based ordering and are placed after all
listed codecs (i.e. soft priority — nothing is dropped).</li>
</ul>
<p>Atmos tracks still take precedence over codec priority, and audio description tracks
are still moved to the end.</p>
<p>Valid codec names: <code>AAC</code>, <code>AC3</code>, <code>EC3</code>, <code>AC4</code>, <code>OPUS</code>, <code>OGG</code>, <code>DTS</code>, <code>ALAC</code>, <code>FLAC</code>.</p>
<p>For example,</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="nt">audio</span><span class="p">:</span>
</span><span id="__span-6-2"><a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a><span class="w"> </span><span class="nt">codec_priority</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">FLAC</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">ALAC</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">AC4</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">EC3</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">DTS</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">AC3</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">OPUS</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">AAC</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">OGG</span><span class="p p-Indicator">]</span>
</span></code></pre></div>
<p>Or to only prefer a subset (e.g. surround codecs first, everything else falls back to
bitrate order):</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="nt">audio</span><span class="p">:</span>
</span><span id="__span-7-2"><a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="w"> </span><span class="nt">codec_priority</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EC3</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">DTS</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">AC3</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">AAC</span><span class="p p-Indicator">]</span>
</span></code></pre></div>
<p>When unset, audio tracks are sorted by bitrate alone (with Atmos/descriptive rules still
applied).</p>
<hr />
<h2 id="subtitle-dict">subtitle (dict)<a class="headerlink" href="#subtitle-dict" title="Permanent link">&para;</a></h2>
<p>Configuration for subtitle processing and conversion.</p>
<ul>
<li><code>conversion_method</code>
Method to use for converting subtitles between formats. Default: <code>"auto"</code></li>
<li><code>"auto"</code> — Smart routing: uses subby for WebVTT/SAMI, pycaption for others.</li>
<li><code>"subby"</code> — Always use subby with advanced processing.</li>
<li><code>"pycaption"</code> — Use only pycaption library (no SubtitleEdit, no subby).</li>
<li><code>"subtitleedit"</code> — Prefer SubtitleEdit when available, fall back to pycaption.</li>
<li><code>"pysubs2"</code> — Use pysubs2 library (supports SRT/SSA/ASS/WebVTT/TTML/SAMI/MicroDVD/MPL2/TMP).</li>
<li><code>sdh_method</code>
Method to use for SDH (hearing impaired) stripping. Default: <code>"auto"</code></li>
<li><code>"auto"</code> — Try subby (SRT only), then SubtitleEdit (if available), then subtitle-filter.</li>
<li><code>"subby"</code> — Use subby library (SRT only).</li>
<li><code>"subtitleedit"</code> — Use SubtitleEdit tool (Windows only, falls back to subtitle-filter).</li>
<li><code>"filter-subs"</code> — Use subtitle-filter library directly.</li>
<li><code>strip_sdh</code>
Automatically create stripped (non-SDH) versions of SDH subtitles. Default: <code>true</code></li>
<li><code>convert_before_strip</code>
Auto-convert VTT/other formats to SRT before using subtitle-filter for SDH stripping.
Ensures compatibility when subtitle-filter is used as fallback. Default: <code>true</code></li>
<li><code>preserve_formatting</code>
Preserve original subtitle formatting (tags, positioning, styling).
When <code>true</code>, skips pycaption processing for WebVTT files to keep tags like <code>&lt;i&gt;</code>, <code>&lt;b&gt;</code>,
positioning intact. Combined with no <code>sub_format</code> setting, ensures subtitles remain in
their original format. Default: <code>true</code></li>
<li><code>output_mode</code>
Output mode for subtitles. Default: <code>"mux"</code></li>
<li><code>"mux"</code> — Embed subtitles in MKV container only.</li>
<li><code>"sidecar"</code> — Save subtitles as separate files only.</li>
<li><code>"both"</code> — Embed in MKV and save as sidecar files.</li>
<li><code>sidecar_format</code>
Format for sidecar subtitle files when <code>output_mode</code> is <code>"sidecar"</code> or <code>"both"</code>. Default: <code>"srt"</code>
Options: <code>srt</code>, <code>vtt</code>, <code>ass</code>, <code>original</code> (keep current format).</li>
</ul>
<p>For example,</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="nt">subtitle</span><span class="p">:</span>
</span><span id="__span-8-2"><a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a><span class="w"> </span><span class="nt">conversion_method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">auto</span>
</span><span id="__span-8-3"><a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a><span class="w"> </span><span class="nt">sdh_method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">auto</span>
</span><span id="__span-8-4"><a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a><span class="w"> </span><span class="nt">strip_sdh</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</span><span id="__span-8-5"><a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a><span class="w"> </span><span class="nt">convert_before_strip</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</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">preserve_formatting</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</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">output_mode</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mux</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">sidecar_format</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">srt</span>
</span></code></pre></div>
<hr />
<h2 id="decryption-str-dict">decryption (str | dict)<a class="headerlink" href="#decryption-str-dict" title="Permanent link">&para;</a></h2>
<p>Choose what software to use to decrypt DRM-protected content throughout unshackle where needed.
You may provide a single decryption method globally or a mapping of service tags to
decryption methods.</p>
<p>Options:</p>
<ul>
<li><code>shaka</code> (default) - Shaka Packager - <a href="https://github.com/shaka-project/shaka-packager">https://github.com/shaka-project/shaka-packager</a></li>
<li><code>mp4decrypt</code> - mp4decrypt from Bento4 - <a href="https://github.com/axiomatic-systems/Bento4">https://github.com/axiomatic-systems/Bento4</a></li>
</ul>
<p>Note that Shaka Packager is the traditional method and works with most services. mp4decrypt
is an alternative that may work better with certain services that have specific encryption formats.</p>
<p>Example mapping:</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="nt">decryption</span><span class="p">:</span>
</span><span id="__span-9-2"><a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a><span class="w"> </span><span class="nt">EXAMPLE</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mp4decrypt</span>
</span><span id="__span-9-3"><a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></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">shaka</span>
</span><span id="__span-9-4"><a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></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">shaka</span>
</span></code></pre></div>
<p>The <code>default</code> entry is optional. If omitted, <code>shaka</code> will be used for services not listed.</p>
<p>Simple configuration (single method for all services):</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="nt">decryption</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mp4decrypt</span>
</span></code></pre></div>
<hr />
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
<button type="button" class="md-top md-icon" data-md-component="top" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
Back to top
</button>
</main>
<footer class="md-footer">
<nav class="md-footer__inner md-grid" aria-label="Footer" >
<a href="../SERVICE_CONFIG/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Service Integration &amp; Auth">
<div class="md-footer__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</div>
<div class="md-footer__title">
<span class="md-footer__direction">
Previous
</span>
<div class="md-ellipsis">
Service Integration & Auth
</div>
</div>
</a>
<a href="../OUTPUT_CONFIG/" class="md-footer__link md-footer__link--next" aria-label="Next: Output &amp; Naming">
<div class="md-footer__title">
<span class="md-footer__direction">
Next
</span>
<div class="md-ellipsis">
Output & Naming
</div>
</div>
<div class="md-footer__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg>
</div>
</a>
</nav>
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"annotate": null, "base": "..", "features": ["content.code.annotate", "content.code.copy", "content.tooltips", "navigation.footer", "navigation.indexes", "navigation.sections", "navigation.tabs", "navigation.top", "navigation.tracking", "search.highlight", "search.share", "search.suggest", "toc.follow"], "search": "../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../assets/javascripts/bundle.79ae519e.min.js"></script>
</body>
</html>