kenzuya/unshackle
1
0
Fork 2
mirror of https://github.com/unshackle-dl/unshackle.git synced 2026-11-14 04:55:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: apply simplified technical english across docs and docstrings.

Browse Source
This commit is contained in:
imSp4rky
2026-08-19 16:31:06 -06:00
parent 4177cb2267
commit 66971230c3
135 changed files with 2651 additions and 2570 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started/configuration-file.md
+25 -25
View File
@@ -1,13 +1,13 @@
# The Configuration File
Almost everything about how unshackle behaves is controlled by a single YAML file named `unshackle.yaml`: where it saves downloads, which CDM it uses, your credentials, proxies, filename templates, and more. This page covers where that file lives, how unshackle finds it, the shape of its contents, the directory layout unshackle builds around it, and how to edit values from the command line.
A single configuration file named `unshackle.yaml` controls almost everything about how unshackle behaves. It sets where unshackle saves downloads, which CDM it uses, your credentials, proxies, filename templates, and more. This page gives where that file lives, how unshackle finds it, and the shape of its contents. It also gives the directory layout unshackle makes around it, and how to edit values from the command line.
!!! note "Where the exhaustive key list lives"
This page is an overview. For the complete, key-by-key breakdown of every setting, its type, and its default, see the [Configuration Reference](../reference/configuration/index.md).
## The config filename
The main configuration file is always named `unshackle.yaml`. It is a plain YAML file. You can open and edit it in any text editor, or manage individual values with the [`unshackle cfg`](#editing-the-config-with-unshackle-cfg) command.
The main configuration file is always named `unshackle.yaml`. It uses plain YAML. You can open and edit it in any text editor, or manage individual values with the [`unshackle cfg`](#editing-the-config-with-unshackle-cfg) command.
If you have never created one, that is fine: unshackle runs entirely on built-in defaults when no config file exists. The file only needs to contain the keys you want to change from their defaults.
@@ -42,13 +42,13 @@ The third location, your per-user config directory, is the recommended place for
```
!!! tip "Not sure which file is being used?"
Run `unshackle env info`. It prints the path the config was loaded from (or tells you none was found), along with every directory unshackle is currently using.
Operate `unshackle env info`. It prints the path unshackle loaded the config from, or tells you that it found none. It also prints every directory unshackle currently uses.
The config is read exactly once, when unshackle starts. If you edit the file, the change takes effect on the next command you run.
The config is read exactly once, when unshackle starts. If you edit the file, the change takes effect on the next command.
## Top-level structure
`unshackle.yaml` is a flat map of top-level keys. Each key configures one area of the program. You only include the keys you want to change; everything else falls back to its default.
`unshackle.yaml` is a flat map of top-level config keys. Each config key configures one area of the program. You include only the config keys you want to change. Everything else falls back to its default.
Here is a small, realistic example that sets a download location, a release tag, a default CDM, and one service's credentials:
@@ -93,14 +93,14 @@ The top-level keys group loosely into these areas:
For the full list with types and defaults, see the [Configuration Reference](../reference/configuration/index.md).
!!! warning "Unknown keys are silently ignored"
unshackle does not validate your config against a schema. If you misspell a key, it is simply skipped and the default is used. You will not get an error. Double-check key names (and their nesting) if a setting does not seem to apply.
unshackle does not validate your config against a schema. If you misspell a config key, unshackle skips it and uses the default. You will not get an error. Examine the config key names (and their nesting) if a setting does not seem to apply.
## Setting download defaults (`dl:`)
If you always pass the same `dl` flags (a language, a resolution, a codec), put them under a
`dl:` key once and unshackle applies them to every download. Any flag from
[Downloading](../guide/downloading.md) works here; the key is the flag's long name with dashes
turned into underscores (`--best-available` → `best_available`).
`dl:` config key once and unshackle applies them to every download. Any flag from
[Downloading](../guide/downloading.md) works here. The config key is the flag's long name with
dashes turned into underscores (`--best-available` → `best_available`).
```yaml title="unshackle.yaml"
dl:
@@ -111,7 +111,7 @@ dl:
downloads: 2 # two tracks at once
```
You can still override any of these on the command line for a one-off; an explicit flag
You can still override any of these on the command line for a one-off. An explicit flag
always beats the config default. You can also scope defaults to a single service by nesting a
`dl:` block under it:
@@ -128,11 +128,11 @@ services:
Most keys are obvious, but set these exact ones: `range` (`-r`), `list` (`--list`),
`tmdb_id` (`--tmdb`), `imdb_id` (`--imdb`), `tvdb_id` (`--tvdb`), `no_atmos` (`--noatmos`), and `output_dir`
(`-o`). The [Configuration Reference](../reference/configuration/download.md#dl) has the full list
and every available key.
and every available config key.
## The directory layout
The `directories` key controls where unshackle reads and writes its various files. Each directory has a sensible default, and you can override most of them by giving a new path. Paths support `~` for your home directory.
The `directories` config key controls where unshackle reads and writes its various files. Each directory has a sensible default, and you can override most of them by giving a new path. A path can use `~` for your home directory.
```yaml title="unshackle.yaml"
directories:
@@ -160,11 +160,11 @@ The directories unshackle uses:
| `fonts` | Bundled fonts | Yes |
!!! note "Some directories cannot be moved"
unshackle protects five internal entries: `app_dirs`, `core_dir`, `namespace_dir`, `user_configs`, and `data`. If you list any of them under `directories`, unshackle ignores the override. This is intentional; those paths are tied to where the package is installed.
unshackle protects five internal entries: `app_dirs`, `core_dir`, `namespace_dir`, `user_configs`, and `data`. If you write any of them under `directories`, unshackle ignores the override. This is intentional. Those paths come from the package location and your OS user directories.
### The `services` directory is special
Unlike the other entries, `services` is a **list**, and each entry can be either a local folder or a remote repository. This lets you mix your own local service code with services pulled from Git:
Unlike the other entries, `services` is a **list**, and each entry can be either a local folder or a remote repository. This lets you mix your own local services with services pulled from Git:
```yaml title="unshackle.yaml"
directories:
@@ -174,31 +174,31 @@ directories:
- ~/code/local-services # a local folder
```
unshackle searches entries in the order listed, and **the first source to define a given service tag wins**, so put local folders last if you want them to act as fallbacks rather than overrides. unshackle clones remote repositories on first use and refreshes them at most once a day. See [Creating a Service](../dev/creating-a-service.md) for how service discovery and repositories work.
unshackle examines the entries in the order you wrote them, and **the first source to define a given service tag wins**. Put local folders last if you want them to act as fallbacks and not overrides. unshackle clones remote repositories on first use and refreshes them at most once a day. See [Creating a Service](../dev/creating-a-service.md) for how service discovery and repositories work.
## The `filenames` key
## The `filenames` config key
Alongside `directories`, the `filenames` key lets you override the templates unshackle uses when naming its own working and log files (for example the log filename or the temporary chapters file). Most users never need to touch this. The available names and their default templates are listed in the [Configuration Reference](../reference/configuration/directories.md#filenames).
Alongside `directories`, the `filenames` config key lets you override the templates unshackle uses when it names its own working and log files. Two examples are the log filename and the temporary chapters file. Most users never need to touch this. The [Configuration Reference](../reference/configuration/directories.md#filenames) gives the available names and their default templates.
## Editing the config with `unshackle cfg`
You do not have to edit `unshackle.yaml` by hand. The `unshackle cfg` command reads and writes individual values for you, creating the config file (and its parent directory) if it does not exist yet.
**Read a single value** by passing its key. Nested keys use dot notation:
**Read a single value** by passing its config key. Nested config keys use dot notation:
```console
$ unshackle cfg tag
$ unshackle cfg cdm.default
```
**Set a value** by passing a key and a value:
**Set a value** by passing a config key and a value:
```console
$ unshackle cfg tag MYGRP
$ unshackle cfg cdm.default my_device_l3
```
unshackle parses the value as a Python literal, so write booleans as `True`/`False` and quote the strings inside a list (`"['en']"`). Anything that is not valid Python literal syntax is stored as a plain string:
unshackle parses the value as a Python literal, so write booleans as `True`/`False` and quote the strings inside a list (`"['en']"`). unshackle stores anything that is not valid Python literal syntax as a plain string:
```console
$ unshackle cfg update_checks False
@@ -211,19 +211,19 @@ $ unshackle cfg vault_timeout 30
$ unshackle cfg cdm.default --unset
```
**List everything** currently set with `--list`:
**Show everything** currently set with `--list`:
```console
$ unshackle cfg --list
```
When it writes, `unshackle cfg` targets the config file that was loaded. If none exists yet, it creates `unshackle.yaml` inside the `unshackle` package folder (search location 1), not your OS user-config directory. To keep the config outside the package, create the file at the user-config path yourself first, then `unshackle cfg` writes to it.
When it writes, `unshackle cfg` targets the config file that unshackle loaded. If none exists yet, it makes `unshackle.yaml` inside the `unshackle` package folder (location 1 above), not your OS user-config directory. To keep the config outside the package, make the file at the user-config path yourself first, then `unshackle cfg` writes to it.
!!! warning "Editing with `cfg` strips comments"
Because `unshackle cfg` rewrites the whole file when it saves, any comments in `unshackle.yaml` are removed by a write. If you keep important notes as comments, edit the file by hand instead, or keep those notes elsewhere.
Because `unshackle cfg` rewrites the whole file when it saves, a write removes any comments in `unshackle.yaml`. If you keep important notes as comments, edit the file by hand instead, or keep those notes elsewhere.
## Next steps
- Browse the [Configuration Reference](../reference/configuration/index.md) for every key and default.
- Browse the [Configuration Reference](../reference/configuration/index.md) for every config key and default.
- Set up your first download in [Downloading](../guide/downloading.md).
- Learn how services are discovered and updated in [Creating a Service](../dev/creating-a-service.md).
- Learn how unshackle discovers and updates services in [Creating a Service](../dev/creating-a-service.md).