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

2088 lines
60 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/ADVANCED_CONFIG/">
<link rel="prev" href="../GLUETUN/">
<link rel="next" href="../API/">
<link rel="icon" href="../assets/favicon.svg">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
<title>Advanced & System - 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="#advanced-system-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">
Advanced & System
</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">
<a href="../DOWNLOAD_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
Download & Processing
</span>
</a>
</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 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">
Advanced & System
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Advanced & System
</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="#serve-dict" class="md-nav__link">
<span class="md-ellipsis">
serve (dict)
</span>
</a>
<nav class="md-nav" aria-label="serve (dict)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#cli-options" class="md-nav__link">
<span class="md-ellipsis">
CLI Options
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#configuration" class="md-nav__link">
<span class="md-ellipsis">
Configuration
</span>
</a>
<nav class="md-nav" aria-label="Configuration">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#server-side-dl-defaults" class="md-nav__link">
<span class="md-ellipsis">
Server-side dl defaults
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#rest-api" class="md-nav__link">
<span class="md-ellipsis">
REST API
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#max_concurrent_downloads-int" class="md-nav__link">
<span class="md-ellipsis">
max_concurrent_downloads (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#download_job_retention_hours-int" class="md-nav__link">
<span class="md-ellipsis">
download_job_retention_hours (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#servehistory_limit-int" class="md-nav__link">
<span class="md-ellipsis">
serve.history_limit (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#debug-bool" class="md-nav__link">
<span class="md-ellipsis">
debug (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#debug_keys-bool" class="md-nav__link">
<span class="md-ellipsis">
debug_keys (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#debug_requests-bool" class="md-nav__link">
<span class="md-ellipsis">
debug_requests (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#set_terminal_bg-bool" class="md-nav__link">
<span class="md-ellipsis">
set_terminal_bg (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#update_checks-bool" class="md-nav__link">
<span class="md-ellipsis">
update_checks (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#update_check_interval-int" class="md-nav__link">
<span class="md-ellipsis">
update_check_interval (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#title_cache_enabled-bool" class="md-nav__link">
<span class="md-ellipsis">
title_cache_enabled (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#title_cache_time-int" class="md-nav__link">
<span class="md-ellipsis">
title_cache_time (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#title_cache_max_retention-int" class="md-nav__link">
<span class="md-ellipsis">
title_cache_max_retention (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#unicode_filenames-bool" class="md-nav__link">
<span class="md-ellipsis">
unicode_filenames (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#ipinfo_api_key-str" class="md-nav__link">
<span class="md-ellipsis">
ipinfo_api_key (str)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#tmdb_api_key-str" class="md-nav__link">
<span class="md-ellipsis">
tmdb_api_key (str)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#simkl_client_id-str" class="md-nav__link">
<span class="md-ellipsis">
simkl_client_id (str)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#decrypt_labs_api_key-str" class="md-nav__link">
<span class="md-ellipsis">
decrypt_labs_api_key (str)
</span>
</a>
</li>
</ul>
</nav>
</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="#serve-dict" class="md-nav__link">
<span class="md-ellipsis">
serve (dict)
</span>
</a>
<nav class="md-nav" aria-label="serve (dict)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#cli-options" class="md-nav__link">
<span class="md-ellipsis">
CLI Options
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#configuration" class="md-nav__link">
<span class="md-ellipsis">
Configuration
</span>
</a>
<nav class="md-nav" aria-label="Configuration">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#server-side-dl-defaults" class="md-nav__link">
<span class="md-ellipsis">
Server-side dl defaults
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#rest-api" class="md-nav__link">
<span class="md-ellipsis">
REST API
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#max_concurrent_downloads-int" class="md-nav__link">
<span class="md-ellipsis">
max_concurrent_downloads (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#download_job_retention_hours-int" class="md-nav__link">
<span class="md-ellipsis">
download_job_retention_hours (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#servehistory_limit-int" class="md-nav__link">
<span class="md-ellipsis">
serve.history_limit (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#debug-bool" class="md-nav__link">
<span class="md-ellipsis">
debug (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#debug_keys-bool" class="md-nav__link">
<span class="md-ellipsis">
debug_keys (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#debug_requests-bool" class="md-nav__link">
<span class="md-ellipsis">
debug_requests (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#set_terminal_bg-bool" class="md-nav__link">
<span class="md-ellipsis">
set_terminal_bg (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#update_checks-bool" class="md-nav__link">
<span class="md-ellipsis">
update_checks (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#update_check_interval-int" class="md-nav__link">
<span class="md-ellipsis">
update_check_interval (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#title_cache_enabled-bool" class="md-nav__link">
<span class="md-ellipsis">
title_cache_enabled (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#title_cache_time-int" class="md-nav__link">
<span class="md-ellipsis">
title_cache_time (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#title_cache_max_retention-int" class="md-nav__link">
<span class="md-ellipsis">
title_cache_max_retention (int)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#unicode_filenames-bool" class="md-nav__link">
<span class="md-ellipsis">
unicode_filenames (bool)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#ipinfo_api_key-str" class="md-nav__link">
<span class="md-ellipsis">
ipinfo_api_key (str)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#tmdb_api_key-str" class="md-nav__link">
<span class="md-ellipsis">
tmdb_api_key (str)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#simkl_client_id-str" class="md-nav__link">
<span class="md-ellipsis">
simkl_client_id (str)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#decrypt_labs_api_key-str" class="md-nav__link">
<span class="md-ellipsis">
decrypt_labs_api_key (str)
</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="advanced-system-configuration">Advanced &amp; System Configuration<a class="headerlink" href="#advanced-system-configuration" title="Permanent link">&para;</a></h1>
<p>This document covers advanced features, debugging, and system-level configuration options.</p>
<h2 id="serve-dict">serve (dict)<a class="headerlink" href="#serve-dict" title="Permanent link">&para;</a></h2>
<p>Configuration for the integrated server that provides CDM endpoints (Widevine/PlayReady) and a REST API for remote downloading.</p>
<p>Start the server with:</p>
<div class="language-bash highlight"><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>serve<span class="w"> </span><span class="c1"># Default: localhost:8786</span>
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>unshackle<span class="w"> </span>serve<span class="w"> </span>-h<span class="w"> </span><span class="m">0</span>.0.0.0<span class="w"> </span>-p<span class="w"> </span><span class="m">8888</span><span class="w"> </span><span class="c1"># Listen on all interfaces</span>
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>unshackle<span class="w"> </span>serve<span class="w"> </span>--no-key<span class="w"> </span><span class="c1"># Disable authentication</span>
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>unshackle<span class="w"> </span>serve<span class="w"> </span>--api-only<span class="w"> </span><span class="c1"># REST API only, no CDM endpoints</span>
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>unshackle<span class="w"> </span>serve<span class="w"> </span>--remote-only<span class="w"> </span><span class="c1"># Only expose remote service session endpoints</span>
</span></code></pre></div>
<h3 id="cli-options">CLI Options<a class="headerlink" href="#cli-options" title="Permanent link">&para;</a></h3>
<table>
<thead>
<tr>
<th>Option</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>-h, --host</code></td>
<td><code>127.0.0.1</code></td>
<td>Host to serve from</td>
</tr>
<tr>
<td><code>-p, --port</code></td>
<td><code>8786</code></td>
<td>Port to serve from</td>
</tr>
<tr>
<td><code>--caddy</code></td>
<td><code>false</code></td>
<td>Also serve with Caddy reverse-proxy for HTTPS</td>
</tr>
<tr>
<td><code>--api-only</code></td>
<td><code>false</code></td>
<td>Serve only the REST API, disable CDM endpoints</td>
</tr>
<tr>
<td><code>--no-widevine</code></td>
<td><code>false</code></td>
<td>Disable Widevine CDM endpoints</td>
</tr>
<tr>
<td><code>--no-playready</code></td>
<td><code>false</code></td>
<td>Disable PlayReady CDM endpoints</td>
</tr>
<tr>
<td><code>--no-key</code></td>
<td><code>false</code></td>
<td>Disable API key authentication (allows all requests)</td>
</tr>
<tr>
<td><code>--debug-api</code></td>
<td><code>false</code></td>
<td>Include tracebacks and stderr in API error responses</td>
</tr>
<tr>
<td><code>--debug</code></td>
<td><code>false</code></td>
<td>Enable debug logging for API operations</td>
</tr>
<tr>
<td><code>--remote-only</code></td>
<td><code>false</code></td>
<td>Only expose remote service session endpoints (health, services, search, session)</td>
</tr>
</tbody>
</table>
<h3 id="configuration">Configuration<a class="headerlink" href="#configuration" title="Permanent link">&para;</a></h3>
<ul>
<li><code>api_secret</code> - Secret key for REST API authentication. Required unless <code>--no-key</code> is used. All API requests must include this key via the <code>X-Secret-Key</code> header.</li>
<li><code>compression_level</code> - Compression level for API payloads (manifests, cache, cookies). <code>0</code>=off, <code>1</code>=fast, <code>6</code>=balanced, <code>9</code>=max. Default: <code>1</code>.</li>
<li><code>session_ttl</code> - Session inactivity timeout in seconds. Each request resets the timer. Default: <code>300</code>.</li>
<li><code>max_sessions</code> - Maximum concurrent sessions before the oldest is evicted. Default: <code>100</code>.</li>
<li><code>services</code> - Optional global service allowlist. Only these service tags are exposed. If omitted, all services are available.</li>
<li><code>devices</code> - List of Widevine device files (.wvd). If not specified, auto-populated from the WVDs directory.</li>
<li><code>playready_devices</code> - List of PlayReady device files (.prd). If not specified, auto-populated from the PRDs directory.</li>
<li><code>users</code> - Dictionary mapping user secret keys to their access configuration:</li>
<li><code>devices</code> - List of Widevine devices this user can access</li>
<li><code>playready_devices</code> - List of PlayReady devices this user can access</li>
<li><code>username</code> - Internal logging name for the user (not visible to users)</li>
<li><code>services</code> - Optional per-user service allowlist. Effective access is the intersection of global and per-user allowlists.</li>
</ul>
<h4 id="server-side-dl-defaults">Server-side <code>dl</code> defaults<a class="headerlink" href="#server-side-dl-defaults" title="Permanent link">&para;</a></h4>
<p>Any key accepted by <code>/api/download</code> (see <code>docs/API.md</code>) can also be declared directly under <code>serve:</code> and the REST API will treat it as a default. Per-request bodies still win. Use this to raise concurrency, force <code>best_available</code>, etc. without each client repeating the values:</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">serve</span><span class="p">:</span>
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="w"> </span><span class="nt">api_secret</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;...&quot;</span>
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="w"> </span><span class="nt">users</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="w"> </span><span class="nv">...</span><span class="w"> </span><span class="p p-Indicator">}</span>
</span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></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 class="w"> </span><span class="c1"># parallel tracks per job</span>
</span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></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 class="w"> </span><span class="c1"># threads per track</span>
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a><span class="w"> </span><span class="nt">best_available</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a><span class="w"> </span><span class="nt">no_proxy_download</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
</span></code></pre></div>
<p>Layering: built-in defaults &lt; <code>serve.*</code> overrides &lt; service-specific defaults &lt; request body.</p>
<p>For example,</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="nt">serve</span><span class="p">:</span>
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="w"> </span><span class="nt">api_secret</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;your-secret-key-here&quot;</span>
</span><span id="__span-2-3"><a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="w"> </span><span class="nt">compression_level</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1</span>
</span><span id="__span-2-4"><a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="w"> </span><span class="nt">session_ttl</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">300</span>
</span><span id="__span-2-5"><a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a><span class="w"> </span><span class="nt">max_sessions</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">100</span>
</span><span id="__span-2-6"><a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a><span class="w"> </span><span class="c1"># services: # global allowlist (optional)</span>
</span><span id="__span-2-7"><a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a><span class="w"> </span><span class="c1"># - EXAMPLE1</span>
</span><span id="__span-2-8"><a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a><span class="w"> </span><span class="c1"># - EXAMPLE2</span>
</span><span id="__span-2-9"><a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a><span class="w"> </span><span class="nt">users</span><span class="p">:</span>
</span><span id="__span-2-10"><a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a><span class="w"> </span><span class="nt">secret_key_for_jane</span><span class="p">:</span><span class="w"> </span><span class="c1"># 32bit hex recommended, case-sensitive</span>
</span><span id="__span-2-11"><a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a><span class="w"> </span><span class="nt">devices</span><span class="p">:</span><span class="w"> </span><span class="c1"># list of allowed Widevine devices for this user</span>
</span><span id="__span-2-12"><a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">generic_nexus_4464_l3</span>
</span><span id="__span-2-13"><a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a><span class="w"> </span><span class="nt">playready_devices</span><span class="p">:</span><span class="w"> </span><span class="c1"># list of allowed PlayReady devices for this user</span>
</span><span id="__span-2-14"><a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">my_playready_device</span>
</span><span id="__span-2-15"><a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a><span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">jane</span><span class="w"> </span><span class="c1"># only for internal logging, users will not see this name</span>
</span><span id="__span-2-16"><a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a><span class="w"> </span><span class="c1"># services: # per-user allowlist (optional)</span>
</span><span id="__span-2-17"><a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a><span class="w"> </span><span class="c1"># - EXAMPLE1</span>
</span><span id="__span-2-18"><a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a><span class="w"> </span><span class="nt">secret_key_for_james</span><span class="p">:</span>
</span><span id="__span-2-19"><a id="__codelineno-2-19" name="__codelineno-2-19" href="#__codelineno-2-19"></a><span class="w"> </span><span class="nt">devices</span><span class="p">:</span>
</span><span id="__span-2-20"><a id="__codelineno-2-20" name="__codelineno-2-20" href="#__codelineno-2-20"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">generic_nexus_4464_l3</span>
</span><span id="__span-2-21"><a id="__codelineno-2-21" name="__codelineno-2-21" href="#__codelineno-2-21"></a><span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">james</span>
</span><span id="__span-2-22"><a id="__codelineno-2-22" name="__codelineno-2-22" href="#__codelineno-2-22"></a><span class="w"> </span><span class="c1"># devices can be manually specified by path if you don&#39;t want to add it to</span>
</span><span id="__span-2-23"><a id="__codelineno-2-23" name="__codelineno-2-23" href="#__codelineno-2-23"></a><span class="w"> </span><span class="c1"># unshackle&#39;s WVDs directory for whatever reason</span>
</span><span id="__span-2-24"><a id="__codelineno-2-24" name="__codelineno-2-24" href="#__codelineno-2-24"></a><span class="w"> </span><span class="c1"># devices:</span>
</span><span id="__span-2-25"><a id="__codelineno-2-25" name="__codelineno-2-25" href="#__codelineno-2-25"></a><span class="w"> </span><span class="c1"># - &#39;C:\Users\john\Devices\test_devices_001.wvd&#39;</span>
</span><span id="__span-2-26"><a id="__codelineno-2-26" name="__codelineno-2-26" href="#__codelineno-2-26"></a><span class="w"> </span><span class="c1"># playready_devices:</span>
</span><span id="__span-2-27"><a id="__codelineno-2-27" name="__codelineno-2-27" href="#__codelineno-2-27"></a><span class="w"> </span><span class="c1"># - &#39;/path/to/device.prd&#39;</span>
</span></code></pre></div>
<h3 id="rest-api">REST API<a class="headerlink" href="#rest-api" title="Permanent link">&para;</a></h3>
<p>When the server is running, interactive API documentation is available at:</p>
<ul>
<li><strong>Swagger UI</strong>: <code>http://localhost:8786/api/docs/</code></li>
</ul>
<p>See <a href="../API/">API.md</a> for full REST API documentation with endpoints, parameters, and examples.</p>
<hr />
<h2 id="max_concurrent_downloads-int">max_concurrent_downloads (int)<a class="headerlink" href="#max_concurrent_downloads-int" title="Permanent link">&para;</a></h2>
<p>Maximum number of <code>/api/download</code> jobs the serve queue manager will execute in parallel. Each job runs the full <code>dl</code> pipeline (authenticate, fetch tracks, decrypt, mux) in its own worker subprocess. This is independent of <code>serve.downloads</code>, which controls parallel tracks <strong>inside</strong> a single job. Default: <code>2</code>.</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="nt">max_concurrent_downloads</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">4</span>
</span></code></pre></div>
<hr />
<h2 id="download_job_retention_hours-int">download_job_retention_hours (int)<a class="headerlink" href="#download_job_retention_hours-int" title="Permanent link">&para;</a></h2>
<p>How long completed, failed, or cancelled download jobs remain queryable via <code>/api/download/jobs/{job_id}</code> before the periodic cleanup loop drops them. Default: <code>24</code>.</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">download_job_retention_hours</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">48</span>
</span></code></pre></div>
<hr />
<h2 id="servehistory_limit-int">serve.history_limit (int)<a class="headerlink" href="#servehistory_limit-int" title="Permanent link">&para;</a></h2>
<p>How many terminal jobs to keep in the persistent history file (<code>api_history.jsonl</code>, stored under the cache directory so it stays out of the config/data tree). Older entries are dropped as new jobs finish. Set to <code>0</code> for unlimited. Default: <code>100</code>.</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">serve</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">history_limit</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">250</span>
</span></code></pre></div>
<hr />
<h2 id="debug-bool">debug (bool)<a class="headerlink" href="#debug-bool" title="Permanent link">&para;</a></h2>
<p>Enables comprehensive debug logging. Default: <code>false</code></p>
<p>When enabled (either via config or the <code>-d</code>/<code>--debug</code> CLI flag):
- Sets console log level to DEBUG for verbose output
- Creates JSON Lines (<code>.jsonl</code>) debug log files with structured logging
- Logs detailed information about sessions, service configuration, DRM operations, and errors with full stack traces</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">debug</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</span></code></pre></div>
<hr />
<h2 id="debug_keys-bool">debug_keys (bool)<a class="headerlink" href="#debug_keys-bool" title="Permanent link">&para;</a></h2>
<p>Controls whether actual decryption keys (CEKs) are included in debug logs. Default: <code>false</code></p>
<p>When enabled:
- Content encryption keys are logged in debug output
- Only affects <code>content_key</code> and <code>key</code> fields (the actual CEKs)
- Key metadata (<code>kid</code>, <code>keys_count</code>, <code>key_id</code>) is always logged regardless of this setting
- Passwords, tokens, cookies, and session tokens remain redacted even when enabled</p>
<p>For example,</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">debug_keys</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</span></code></pre></div>
<hr />
<h2 id="debug_requests-bool">debug_requests (bool)<a class="headerlink" href="#debug_requests-bool" title="Permanent link">&para;</a></h2>
<p>Controls whether HTTP-library logs are shown during <code>--debug</code> sessions. Default: <code>false</code></p>
<p>When <code>--debug</code> is active and this is <code>false</code>, unshackle silences the noisy per-request logs emitted by <code>urllib3</code>, <code>requests</code>, <code>rnet</code>, <code>httpx</code>, and related libraries (e.g. <code>GET ...seg-001.m4s 200</code>) so that unshackle's own structured DEBUG output stays readable. Set to <code>true</code> to see every individual HTTP request, including per-segment downloads.</p>
<p>Has no effect when <code>--debug</code> is not active.</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">debug_requests</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</span></code></pre></div>
<hr />
<h2 id="set_terminal_bg-bool">set_terminal_bg (bool)<a class="headerlink" href="#set_terminal_bg-bool" title="Permanent link">&para;</a></h2>
<p>Controls whether unshackle applies its theme background color to the terminal. Default: <code>false</code></p>
<p>When enabled, the Rich console theme's background color is appended to the foreground styles for both the general color scheme and the ASCII art banner, so the full color palette renders correctly on terminals whose default background differs from the theme. Set to <code>true</code> if the banner or colored output looks off on your terminal.</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">set_terminal_bg</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</span></code></pre></div>
<hr />
<h2 id="update_checks-bool">update_checks (bool)<a class="headerlink" href="#update_checks-bool" title="Permanent link">&para;</a></h2>
<p>Check for updates from the GitHub repository on startup. Default: <code>true</code>.</p>
<hr />
<h2 id="update_check_interval-int">update_check_interval (int)<a class="headerlink" href="#update_check_interval-int" title="Permanent link">&para;</a></h2>
<p>How often to check for updates, in hours. Default: <code>24</code>.</p>
<hr />
<h2 id="title_cache_enabled-bool">title_cache_enabled (bool)<a class="headerlink" href="#title_cache_enabled-bool" title="Permanent link">&para;</a></h2>
<p>Enable or disable title metadata caching globally. Default: <code>true</code>.</p>
<hr />
<h2 id="title_cache_time-int">title_cache_time (int)<a class="headerlink" href="#title_cache_time-int" title="Permanent link">&para;</a></h2>
<p>Title cache duration in seconds. Default: <code>1800</code> (30 minutes).</p>
<hr />
<h2 id="title_cache_max_retention-int">title_cache_max_retention (int)<a class="headerlink" href="#title_cache_max_retention-int" title="Permanent link">&para;</a></h2>
<p>Maximum cache retention in seconds, used as fallback when the upstream API fails. Default: <code>86400</code> (24 hours).</p>
<hr />
<h2 id="unicode_filenames-bool">unicode_filenames (bool)<a class="headerlink" href="#unicode_filenames-bool" title="Permanent link">&para;</a></h2>
<p>When <code>false</code>, replaces non-ASCII characters in output filenames with ASCII equivalents. Default: <code>false</code>.</p>
<hr />
<h2 id="ipinfo_api_key-str">ipinfo_api_key (str)<a class="headerlink" href="#ipinfo_api_key-str" title="Permanent link">&para;</a></h2>
<p>Optional ipinfo.io token. When set, unshackle uses the ipinfo.io Lite endpoint for IP/geolocation lookups instead of the unauthenticated fallback.</p>
<hr />
<h2 id="tmdb_api_key-str">tmdb_api_key (str)<a class="headerlink" href="#tmdb_api_key-str" title="Permanent link">&para;</a></h2>
<p>Optional TMDB API key, used for metadata enrichment and IMDb/TMDb tagging.</p>
<hr />
<h2 id="simkl_client_id-str">simkl_client_id (str)<a class="headerlink" href="#simkl_client_id-str" title="Permanent link">&para;</a></h2>
<p>Optional Simkl client ID for metadata lookups.</p>
<hr />
<h2 id="decrypt_labs_api_key-str">decrypt_labs_api_key (str)<a class="headerlink" href="#decrypt_labs_api_key-str" title="Permanent link">&para;</a></h2>
<p>Optional Decrypt Labs API key, used by services that integrate with the service.</p>
<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="../GLUETUN/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Gluetun VPN">
<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">
Gluetun VPN
</div>
</div>
</a>
<a href="../API/" class="md-footer__link md-footer__link--next" aria-label="Next: Overview">
<div class="md-footer__title">
<span class="md-footer__direction">
Next
</span>
<div class="md-ellipsis">
Overview
</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>