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

docs: cover the TVDB provider, episode ordering and provider order

Browse Source 
Document tvdb_api_key, tvdb_pin, tvdb_order and metadata_providers, the
--tvdb and --tvdb-order flags with their behaviour when an order does
not cover a whole series, the new REST API parameters, and the Matroska
TVDB2 tag prefixes.
This commit is contained in:
imSp4rky
2026-08-02 10:48:39 -06:00
parent 4ac34069ec
commit 786309ea5c
7 changed files with 73 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guide/cli-reference.md
+15 -1
View File
@@ -145,8 +145,22 @@ Keep only certain track types, or skip certain track types. Attachments are alwa
|---|---|
| `--tmdb` | TMDB ID (integer). |
| `--imdb` | IMDb ID, e.g. `tt1375666`. |
| `--animeapi` | AnimeAPI ID, e.g. `mal:12345` or `anilist:98765` (defaults to MAL). Back-fills TMDB/IMDb. |
| `--tvdb` | TVDB ID (integer). Skips the series lookup that `--tvdb-order` would otherwise do. |
| `--animeapi` | AnimeAPI ID, e.g. `mal:12345` or `anilist:98765` (defaults to MAL). Back-fills TMDB/IMDb/TVDB. |
| `--enrich` | Override show title/year from the external source. **Requires** one of `--tmdb`, `--imdb`, or `--animeapi`. |
| `--tvdb-order` | Renumber episodes to a TVDB season order: `official` (aired), `dvd`, `absolute`, `alternate`, or `regional`. Needs `tvdb_api_key`. |
#### Episode ordering
A service does not always number a series the way TVDB's aired order does. Some services list
Futurama in TVDB's `alternate` (Streaming) order, for example. `--tvdb-order` works out which
order the service used, then renumbers the episodes into the order you asked for.
!!! note "Orders that do not cover the whole series"
An order can omit episodes the service carries; TVDB's `dvd` order for Futurama leaves out
the four movies. Those episodes keep their original numbering. If that would give two
episodes the same season/episode slot, and so the same filename, unshackle logs an error
and keeps the service's numbering unchanged. Pick an order that covers the whole series.
### DRM, keys & decryption
docs/guide/downloading.md
+24 -1
View File
@@ -519,13 +519,35 @@ tagging and naming:
| --- | --- | --- |
| `--tmdb` | `--tmdb 27205` | Use this TMDB ID instead of automatic lookup. |
| `--imdb` | `--imdb tt1375666` | Use this IMDb ID. |
| `--tvdb` | `--tvdb 73871` | Use this TVDB ID instead of looking the series up. |
| `--animeapi` | `--animeapi mal:12345` | Resolve via AnimeAPI (`mal:`/`anilist:` prefix; defaults to MAL). |
| `--enrich` | - | Override the show title and year from an external source. **Requires** one of `--tmdb`, `--imdb`, or `--animeapi`. |
| `--tvdb-order` | `--tvdb-order dvd` | Renumber episodes to a TVDB season order. Needs `tvdb_api_key`. |
```shell title="Force the right IMDb match and enrich the title"
unshackle dl --imdb tt1375666 --enrich EXAMPLE 81234567
```
### Episode ordering
A service does not always number a series the way TVDB's aired order does. Some services list
Futurama in TVDB's `alternate` (Streaming) order, for example, while TVDB's `official` order
holds back four season-one episodes to the start of season two. `--tvdb-order` works out which
order the service used, then renumbers the episodes into the order you asked for:
```shell title="Download Futurama in DVD order"
unshackle dl --tvdb-order dvd EXAMPLE 81234567
```
Available orders are `official` (aired), `dvd`, `absolute`, `alternate`, and `regional`. Set
`tvdb_order` in your config to apply one by default.
!!! warning "Orders that do not cover the whole series"
An order can leave out episodes the service carries. TVDB's `dvd` order does not list
Futurama's four movies. Those episodes keep their original numbering. If that would give
two episodes the same season/episode slot, and so the same filename, unshackle logs an
error and leaves the numbering untouched. Pick an order that covers the whole series.
## Configuration defaults
Every flag on this page can be set as a default in your configuration file so you don't
@@ -571,4 +593,5 @@ authoritative list.
| `--list` / `--list-titles` / `--skip-dl` | | Dry runs. |
| `--cdm-only` / `--vaults-only` | | Key source control. |
| `--export` | | Export track info and keys to JSON. |
| `--tmdb` / `--imdb` / `--animeapi` / `--enrich` | | Metadata overrides. |
| `--tmdb` / `--imdb` / `--tvdb` / `--animeapi` / `--enrich` | | Metadata overrides. |
| `--tvdb-order` | | Renumber episodes to a TVDB season order. |
docs/guide/output-and-naming.md
+5 -1
View File
@@ -245,7 +245,11 @@ tag_imdb_tmdb: true
|---|---|---|---|
| `tag` | str | `""` | The release-group tag used for `{tag}`. |
| `tag_group_name` | bool | `true` | Write the group name (`config.tag`) into the MKV `Group` metadata tag. |
| `tag_imdb_tmdb` | bool | `true` | Look up and embed IMDb / TMDB / TVDB external-ID tags in the MKV metadata (uses `tmdb_api_key` / `simkl_client_id` when available). |
| `tag_imdb_tmdb` | bool | `true` | Look up and embed IMDb / TMDB / TVDB external-ID tags in the MKV metadata (uses `tmdb_api_key` / `tvdb_api_key` / `simkl_client_id` when available). |
The IDs are written as the Matroska `IMDB`, `TMDB`, and `TVDB2` tags. `TVDB2` values carry the
entity prefix the [Matroska tagging spec](https://www.matroska.org/technical/tagging.html)
requires: `series/73871` for a show, `movies/113` for a film.
You can override the tag per run without editing config: