mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-11-15 21:45:10 +00:00
Merge branch 'dev' into feat/downloader-speed
# Conflicts: # unshackle/core/api/download_manager.py # unshackle/core/downloaders/requests.py # unshackle/core/manifests/dash.py # unshackle/core/session.py # unshackle/core/utils/webvtt.py
This commit is contained in:
@@ -99,6 +99,8 @@ Declared at class level to configure framework behaviour:
|
||||
| `VAULT_TAG` | `Optional[str]` | Overrides the key-vault namespace so sibling services can share one vault. Default `None` (use the service's own tag). |
|
||||
| `AUTH_METHODS` | `Optional[tuple[str, ...]]` | Auth methods accepted (`"cookies"` / `"credentials"`). When `None`, the REST `/services` endpoint infers them from `authenticate()`. |
|
||||
| `NO_SUBTITLES` | `bool` | Set `True` on a service with no subtitle tracks to skip subtitle handling entirely. |
|
||||
| `ANIME` | `bool` | Set `True` when the catalog is anime, so metadata lookups prefer AniList. A title's own `anime` flag overrides it. |
|
||||
| `DAILY` | `bool` | Set `True` when the catalog is daily/date-based (talk shows, news, sports), so episodes are named by air date. A title's own `daily` flag overrides it. |
|
||||
|
||||
!!! note "`NO_SUBTITLES` is a convention, not a base-class attribute"
|
||||
`NO_SUBTITLES` is checked by `dl.py` via `hasattr` and is deliberately **not**
|
||||
@@ -240,7 +242,7 @@ use `self.request_input(prompt)`, never a bare `input()`. Under `serve` mode
|
||||
there is no local terminal, so a bare `input()` would hang the server waiting on
|
||||
stdin that never arrives; `request_input` instead relays the prompt to the
|
||||
remote client through the attached `InputBridge`. Locally it routes through the
|
||||
shared Rich console (`console.input`) so the prompt renders correctly alongside
|
||||
shared Rich console (`prompt_user`) so the prompt renders correctly alongside
|
||||
progress and log output.
|
||||
|
||||
!!! warning "Key token caches by whatever varies per session"
|
||||
@@ -427,22 +429,22 @@ Each exposes `from_url(url, session=...)` (or `from_text(text, url)`) and then
|
||||
token.
|
||||
|
||||
Some services deliver a **separate manifest per codec/range**. The base class
|
||||
provides `_get_tracks_for_variants(title, fetch_fn)` to fan out over every
|
||||
provides `get_tracks_for_variants(title, fetch_fn)` to fan out over every
|
||||
codec×range in the `TrackRequest`, including `HYBRID` (fetch HDR10 + DV and
|
||||
merge) and `--best-available` skip-on-error handling:
|
||||
|
||||
```python
|
||||
def get_tracks(self, title: Title_T) -> Tracks:
|
||||
def _fetch_variant(title, codec, range_) -> Tracks:
|
||||
def fetch_variant(title, codec, range_) -> Tracks:
|
||||
vcodec = "H265" if codec == Video.Codec.HEVC else "H264"
|
||||
return self._fetch_dash_manifest(title, vcodec=vcodec, range_=range_)
|
||||
return self._get_tracks_for_variants(title, _fetch_variant)
|
||||
return self.fetch_dash_manifest(title, vcodec=vcodec, range_=range_)
|
||||
return self.get_tracks_for_variants(title, fetch_variant)
|
||||
```
|
||||
|
||||
After parsing, you may **correct** track metadata the manifest gets wrong:
|
||||
stamp the real `video.range`, fix odd audio channel counts, mark descriptive
|
||||
audio, add hand-built subtitles or an `Attachment` (e.g. cover art). Do *not*
|
||||
filter for resolution/bitrate. See `_fetch_dash_manifest` in the EXAMPLE service
|
||||
filter for resolution/bitrate. See `fetch_dash_manifest` in the EXAMPLE service
|
||||
for a thorough demonstration.
|
||||
|
||||
!!! note "Flip HDR10 → HDR10+ by hand when you know the platform embeds it"
|
||||
|
||||
@@ -108,6 +108,17 @@ X-Secret-Key: <your-secret>
|
||||
|
||||
The value must exactly match one of the configured keys (`api_secret`, or one of the keys under `users`). There is no login step, no session cookie, and no token exchange for API access. The same static key is sent on each request.
|
||||
|
||||
!!! info "One route also accepts the key as a query parameter"
|
||||
The job event stream, `GET /api/download/jobs/{job_id}/events`, also accepts the key in a `secret_key` query parameter. This is for browsers: the `EventSource` API cannot set request headers. The exception applies to that one route only, and it works in both server modes.
|
||||
|
||||
```javascript
|
||||
new EventSource(`http://127.0.0.1:8786/api/download/jobs/${jobId}/events?secret_key=${key}`);
|
||||
```
|
||||
|
||||
The header always wins. If the request has an `X-Secret-Key` header, the server checks that header and ignores the query parameter, so a wrong header is rejected even when the query parameter holds a valid key.
|
||||
|
||||
A key in a URL is easier to leak than a key in a header, because proxies and browser history can record it. Use the header wherever your client can set one.
|
||||
|
||||
=== "curl"
|
||||
|
||||
```bash
|
||||
@@ -269,6 +280,7 @@ With `--caddy`, unshackle also starts `caddy run` using the `Caddyfile` located
|
||||
| Item | Value |
|
||||
|---|---|
|
||||
| Auth header | `X-Secret-Key` |
|
||||
| Query-parameter alternative | `?secret_key=` on `GET /api/download/jobs/{job_id}/events` only |
|
||||
| Default bind address | `127.0.0.1:8786` |
|
||||
| Exempt endpoint | `GET /api/health` |
|
||||
| Failure status | `401 Unauthorized` |
|
||||
@@ -287,12 +299,14 @@ With `--caddy`, unshackle also starts `caddy run` using the `Caddyfile` located
|
||||
|
||||
The header and config are identical between modes, but the code that enforces them differs:
|
||||
|
||||
- **API-only server** (`--api-only`, or `--remote-only` which forces API-only). An `api_key_authentication` middleware runs on every request. It lets `GET /api/health` through unconditionally, then reads `X-Secret-Key`. An empty header returns the *"Secret Key is Empty."* body; a header that is not a configured user returns *"Secret Key is Invalid."*. In this mode the accepted-keys map contains exactly one entry: your `api_secret` (labelled `api_user`, with no devices). With `--no-key`, this middleware is simply not installed and the users map is empty.
|
||||
- **API-only server** (`--api-only`, or `--remote-only` which forces API-only). An `api_key_authentication` middleware runs on every request. It lets `GET /api/health` through unconditionally, then reads `X-Secret-Key`. An empty header returns the *"Secret Key is Empty."* body; a header that is not a configured user returns *"Secret Key is Invalid."*. In this mode the accepted-keys map holds your `api_secret` (labelled `api_user`, with no devices) plus every key under `serve.users`, so a per-user key authenticates here exactly as it does on the integrated server, and that user's `services` allowlist applies as usual. With `--no-key`, this middleware is simply not installed and the users map is empty.
|
||||
|
||||
- **Integrated server** (default). A `serve_authentication` middleware wraps pywidevine's authentication (and pyplayready's for `/playready*` paths), and the REST routes live in the same application, guarded by the same check. Here the accepted-keys map is your full `serve` config: `api_secret` (auto-added with access to all loaded devices) plus every entry under `users`, each with its declared `devices` / `playready_devices`.
|
||||
|
||||
Because the API-only middleware guards *all* non-health paths, the Swagger UI at `/api/docs/` is also behind `X-Secret-Key` there. In `--remote-only` mode the Swagger UI is not mounted at all.
|
||||
|
||||
Both middlewares read the caller's key through the shared `request_secret_key()` helper in `unshackle/core/api/handlers.py`, which returns the `X-Secret-Key` header and falls back to the `secret_key` query parameter only when the matched route is the job event stream. The integrated server needs one extra branch for this: pywidevine's `authentication` is header-only, so `serve_authentication` compares the query-parameter key itself when the header is absent, and delegates to pywidevine in every other case. That is why a present-but-wrong header is rejected in both modes.
|
||||
|
||||
### CORS and the `Authorization` header
|
||||
|
||||
A `cors_middleware` runs on every response in both modes (and answers `OPTIONS` preflight requests with an empty response). It emits:
|
||||
|
||||
@@ -223,6 +223,16 @@ Service-specific CLI options may also be passed as additional keys.
|
||||
|
||||
Each serialized title carries `type` (`"episode"`, `"movie"`, or `"other"`), `name`, `id`, `language`, `description`, `date`, and `cover_url`. Episodes and movies add `year`; episodes additionally add `series_title`, `season`, and `number`.
|
||||
|
||||
These keys are sent only when the title carries them, so a title without them serializes exactly as before:
|
||||
|
||||
| Key | Type | On | Meaning |
|
||||
| --- | --- | --- | --- |
|
||||
| `part` | integer | episode | Part index of a [split episode](../creating-a-service.md#split-episodes), counting from 1. |
|
||||
| `air_date` | string | episode | ISO air date of [dated content](../../guide/downloading.md#daily-and-date-based-content). unshackle names the episode by date instead of `SxxExx`. |
|
||||
| `absolute` | integer | episode | Absolute episode number across all seasons. |
|
||||
| `daily` | boolean | episode | The episode is daily/date-based. Set from the title, or from the service's `DAILY` class attribute. |
|
||||
| `anime` | boolean | episode, movie | The title is anime, so metadata lookups prefer AniList. Set from the title, or from the service's `ANIME` class attribute. |
|
||||
|
||||
!!! info "`part` on a split episode"
|
||||
A service that splits one episode into several separately playable videos reports each
|
||||
one as its own episode. Those titles share a `season` and `number` and add a `part`
|
||||
@@ -368,7 +378,7 @@ Create a download job. Requires `service` and `title_id`; every other field is a
|
||||
| `range` | string[] | `["SDR"]` | Dynamic range(s). |
|
||||
| `channels` | number | `null` | Audio channel count. |
|
||||
| `no_atmos` | boolean | `false` | Exclude Atmos tracks. |
|
||||
| `wanted` | string[] | `[]` | Episode/season selectors. Accepts the part form, `"S01E01.2"`. |
|
||||
| `wanted` | string[] | `[]` | Episode/season selectors. Accepts the part form, `"S01E01.2"`, and the air-date form, `"2026-08-11"` or `"2026-08-01:2026-08-31"`. |
|
||||
| `latest_episode` | boolean | `false` | Only the newest episode. |
|
||||
| `lang` / `v_lang` / `a_lang` / `s_lang` | string[] | `["orig"]` / `[]` / `[]` / `["all"]` | Language filters. |
|
||||
| `require_subs` | string[] | `[]` | Required subtitle languages. |
|
||||
@@ -392,9 +402,10 @@ Create a download job. Requires `service` and `title_id`; every other field is a
|
||||
| `best_available` | boolean | `false` | Fall back to best available. |
|
||||
| `repack` | boolean | `false` | Add REPACK tag. |
|
||||
| `tag` | string | `null` | Release group tag. |
|
||||
| `tmdb_id` / `imdb_id` / `tvdb_id` / `animeapi_id` | - | `null` | External ID overrides for tagging. |
|
||||
| `tmdb_id` / `imdb_id` / `tvdb_id` / `anilist_id` | - | `null` | External ID overrides. Each resolves its metadata directly instead of by a title search, and is used for tagging. Set `enrich` to also take the title, year and original language. Give at most one of `tmdb_id`, `imdb_id` and `tvdb_id`, since unshackle resolves the others from it. Sending two returns `400`. `anilist_id` still combines with one of them. `tmdb_id` and `tvdb_id` must be positive integers, `imdb_id` must look like `tt1375666`, and `anilist_id` must be a positive integer or a string like `mal:12345`, or the request returns `400`. An ID whose provider is unconfigured, such as `tmdb_id` with no `tmdb_api_key`, fails the job rather than returning `400`. `anilist_id` needs no key. |
|
||||
| `tvdb_order` | `official`, `dvd`, `absolute`, `alternate`, `regional` | `null` | Renumber episodes to a TVDB season order. Falls back to the `tvdb_order` config option. |
|
||||
| `enrich` | boolean | `false` | Override title/year from external source. |
|
||||
| `enrich` | boolean | `false` | Overwrite title, year and original language with the external source's. Needs one of `tmdb_id`, `imdb_id`, `tvdb_id` or `anilist_id`. Without one the job fails instead of returning `400`. |
|
||||
| `daily` | boolean | `false` | Treat the title as daily/date-based content and fill missing episode air dates from TVDB. The fill needs `enrich` and a TVDB ID. An air date the service already set is kept. |
|
||||
| `output_dir` | string | `null` | Override output directory. |
|
||||
| `no_cache` / `reset_cache` | boolean | `false` | Title cache controls. |
|
||||
|
||||
@@ -481,6 +492,73 @@ Fetch a single job with full details (equivalent to a `full=true` list entry).
|
||||
| `200` | - | Job returned. |
|
||||
| `404` | `JOB_NOT_FOUND` | No such job. |
|
||||
|
||||
### `GET /api/download/jobs/{job_id}/events`
|
||||
|
||||
Stream the job's progress as [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). Use this instead of polling `GET /api/download/jobs/{job_id}`.
|
||||
|
||||
The response has the content type `text/event-stream`. Each event has this format:
|
||||
|
||||
```
|
||||
event: <name>
|
||||
data: <job JSON>
|
||||
|
||||
```
|
||||
|
||||
The `data` field of every event is the same job object that `GET /api/download/jobs/{job_id}` returns.
|
||||
|
||||
| Event | When it is sent |
|
||||
| --- | --- |
|
||||
| `snapshot` | Immediately, as the first event. Gives the job's current state. |
|
||||
| `status` | The job leaves the queue and starts to download. |
|
||||
| `progress` | The worker's progress record changed. The server reads that record every 0.5 seconds, so you get at most two of these events each second, and none while the record stays the same. |
|
||||
| `completed` | The job finished. The server then closes the stream. |
|
||||
| `failed` | The job failed. The server then closes the stream. |
|
||||
| `cancelled` | The job was cancelled. The server then closes the stream. |
|
||||
|
||||
The server sends a `: keep-alive` comment each 15 seconds while the job is quiet, to keep proxies from closing an idle connection. Ignore these lines.
|
||||
|
||||
If the job is already in a terminal state, the server sends the `snapshot` event, then the terminal event, and closes the stream immediately.
|
||||
|
||||
!!! tip "Authentication from a browser"
|
||||
`EventSource` cannot set headers. For this endpoint only, the server also accepts the key in the `secret_key` query parameter. This works in both server modes, the default integrated server and `--api-only`:
|
||||
|
||||
```javascript
|
||||
const events = new EventSource(
|
||||
`http://127.0.0.1:8786/api/download/jobs/${jobId}/events?secret_key=${key}`
|
||||
);
|
||||
events.addEventListener("progress", (e) => console.log(JSON.parse(e.data).progress));
|
||||
events.addEventListener("completed", () => events.close());
|
||||
```
|
||||
|
||||
The header always wins. Send the key in the query parameter *or* in the header, not both: if an `X-Secret-Key` header is present, the server checks that header and ignores the query parameter. See [Authentication](authentication.md#how-clients-present-credentials).
|
||||
|
||||
=== "Request"
|
||||
|
||||
```bash
|
||||
curl -N -H "X-Secret-Key: $KEY" \
|
||||
"http://127.0.0.1:8786/api/download/jobs/b0f7c8e2-.../events"
|
||||
```
|
||||
|
||||
=== "Response `200`"
|
||||
|
||||
```
|
||||
event: snapshot
|
||||
data: {"job_id":"b0f7c8e2-...","status":"downloading","progress":42.5,...}
|
||||
|
||||
event: progress
|
||||
data: {"job_id":"b0f7c8e2-...","status":"downloading","progress":48.0,...}
|
||||
|
||||
: keep-alive
|
||||
|
||||
event: completed
|
||||
data: {"job_id":"b0f7c8e2-...","status":"completed","progress":100.0,...}
|
||||
```
|
||||
|
||||
| Status | Error code | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `200` | - | Event stream started. |
|
||||
| `404` | `JOB_NOT_FOUND` | No such job. |
|
||||
|
||||
### `DELETE /api/download/jobs/{job_id}`
|
||||
|
||||
Cancel or remove a job. The behaviour depends on the job's current state:
|
||||
|
||||
@@ -22,8 +22,9 @@ calls you can script against:
|
||||
|
||||
- **Discovery**: list the services available on the server, run a service's search,
|
||||
and enumerate the titles and tracks behind a title ID.
|
||||
- **Downloading**: submit a download as a background *job*, then poll its status and
|
||||
live progress, cancel it, retry it, or bump it to the front of the queue.
|
||||
- **Downloading**: submit a download as a background *job*, then follow its status and
|
||||
live progress (by polling, or by subscribing to its Server-Sent Events stream),
|
||||
cancel it, retry it, or bump it to the front of the queue.
|
||||
- **History and housekeeping**: read the log of finished jobs, inspect the server's
|
||||
effective (redacted) configuration, check external tool versions, and clear caches
|
||||
or temp files.
|
||||
@@ -161,6 +162,7 @@ request and response in full.
|
||||
| `GET` | `/api/download/jobs` | List jobs, with filtering and sorting. |
|
||||
| `POST` | `/api/download/jobs/clear-finished` | Remove all finished jobs. |
|
||||
| `GET` | `/api/download/jobs/{job_id}` | Full detail for one job. |
|
||||
| `GET` | `/api/download/jobs/{job_id}/events` | Stream one job's progress as Server-Sent Events. |
|
||||
| `DELETE` | `/api/download/jobs/{job_id}` | Cancel a running job, or remove a finished one. |
|
||||
| `POST` | `/api/download/jobs/{job_id}/retry` | Re-queue a finished job's parameters as a new job. |
|
||||
| `POST` | `/api/download/jobs/{job_id}/priority` | Move a queued job to the front. |
|
||||
|
||||
@@ -177,6 +177,11 @@ The full detail adds `started_time`, `completed_time`, `output_files`, the redac
|
||||
done
|
||||
```
|
||||
|
||||
!!! tip "Or subscribe instead of polling"
|
||||
`GET /api/download/jobs/{job_id}/events` pushes the same job object as Server-Sent
|
||||
Events, and closes the stream when the job ends. See
|
||||
[Endpoints](endpoints.md#get-apidownloadjobsjob_idevents).
|
||||
|
||||
!!! note "What the percentage means"
|
||||
`progress` climbs from `0` toward `90` while tracks download, then the final stretch
|
||||
to `100` covers post-download work such as decryption cleanup, repackaging, and
|
||||
|
||||
@@ -310,7 +310,15 @@ done
|
||||
```
|
||||
|
||||
!!! tip "Polling cadence"
|
||||
A few seconds between polls is plenty. The server writes progress updates roughly twice a second internally, but there is no push/streaming channel; you read the current snapshot each time you ask.
|
||||
A few seconds between polls is plenty. The server updates a job's progress roughly twice a second internally, and each poll reads the current snapshot.
|
||||
|
||||
!!! tip "Or let the server push the updates"
|
||||
`GET /api/download/jobs/{job_id}/events` streams the same job record as Server-Sent Events, and closes the stream when the job ends. It removes the polling loop above. See [Endpoints](endpoints.md#get-apidownloadjobsjob_idevents).
|
||||
|
||||
```bash
|
||||
curl -N "$BASE/api/download/jobs/$JOB/events" \
|
||||
-H "X-Secret-Key: $SECRET"
|
||||
```
|
||||
|
||||
If a job ends in `failed`, the full record includes `error_message`, `error_code`, and (when the server was started with `--debug-api`) `error_traceback` and `worker_stderr` to help you diagnose it. Sensitive values in these fields are scrubbed before they are returned.
|
||||
|
||||
|
||||
@@ -391,14 +391,15 @@ and base64-encoding, **excluding** `titles_*` files) and returns them under a
|
||||
Source: `unshackle/core/remote_service.py`. This is the canonical consumer of the
|
||||
session API and a good template for any client.
|
||||
|
||||
- **`RemoteClient._request`** sets `X-Secret-Key` and `User-Agent: unshackle/<version>`,
|
||||
- **`RemoteClient.request`** sets `X-Secret-Key` and `User-Agent: unshackle/<version>`,
|
||||
uses a 120s timeout for `POST` and 30s for `GET`/`DELETE`, and treats any
|
||||
`status_code >= 400` as fatal: it logs `Server error [<error_code>]: <message>`
|
||||
and raises `SystemExit(1)`.
|
||||
- **Retries.** The download-side HTTP session mounts an adapter with
|
||||
`Retry(total=5, backoff_factor=0.2, status_forcelist=[429, 500, 502, 503, 504])`.
|
||||
- **Flow.** `authenticate()` → `create` (+ poll `prompt` every 2s up to a 600s
|
||||
deadline, answering `pending_input` prompts) → `get_titles()` → `get_tracks()`
|
||||
deadline, answering `pending_input` prompts; with stdin closed the client logs an
|
||||
error and raises `SystemExit(1)` instead of posting an empty answer) → `get_titles()` → `get_tracks()`
|
||||
(merging returned `session_headers`/`session_cookies`, re-parsing `manifests`) →
|
||||
license via proxy or `server_cdm` → `close()` (`DELETE`, saving any returned
|
||||
`cache`).
|
||||
|
||||
@@ -64,6 +64,8 @@ Declared at the top of your service class, these are static descriptors:
|
||||
| `GEOFENCE` | `tuple[str, ...]` | ISO region codes the service requires; empty means no geofence. The first entry is treated as the "main region" for automatic proxy selection. |
|
||||
| `VAULT_TAG` | `Optional[str]` | Overrides the key-vault namespace; defaults to the service's own tag. |
|
||||
| `AUTH_METHODS` | `Optional[tuple[str, ...]]` | Accepted auth methods (`"cookies"` / `"credentials"`). When `None`, the REST `/services` endpoint infers them from `authenticate()`. |
|
||||
| `ANIME` | `bool` | The catalog is anime, so metadata lookups prefer AniList. A title's own `anime` flag overrides it. |
|
||||
| `DAILY` | `bool` | The catalog is daily/date-based, so episodes are named by air date. A title's own `daily` flag overrides it. |
|
||||
|
||||
### Required methods
|
||||
|
||||
|
||||
+29
-12
@@ -90,13 +90,13 @@ unshackle dl [OPTIONS] SERVICE [SERVICE ARGS...]
|
||||
|
||||
| Flag | Default | Description |
|
||||
|---|---|---|
|
||||
| `-l`, `--lang` | `orig` | Language(s) for **both** video and audio. `orig` = the title's original language; e.g. `orig,en`. |
|
||||
| `-vl`, `--v-lang` | - | Video-only language (overrides `-l` for video). |
|
||||
| `-al`, `--a-lang` | - | Audio-only language (overrides `-l` for audio). |
|
||||
| `-sl`, `--s-lang` | `all` | Subtitle language(s). |
|
||||
| `-l`, `--lang` | `orig` | Language(s) for **both** video and audio. `orig` = the title's original language; e.g. `orig,en`. A `-` prefix excludes, e.g. `all,-es`. |
|
||||
| `-vl`, `--v-lang` | - | Video-only language (overrides `-l` for video). A `-` prefix excludes. |
|
||||
| `-al`, `--a-lang` | - | Audio-only language (overrides `-l` for audio). A `-` prefix excludes. |
|
||||
| `-sl`, `--s-lang` | `all` | Subtitle language(s). A `-` prefix excludes, e.g. `all,-es`. |
|
||||
| `--require-subs` | - | Required subtitle langs; keeps **all** subs only if these exist. **Cannot combine with `--s-lang`.** |
|
||||
| `-fs`, `--forced-subs` | off | Include forced subtitle tracks. |
|
||||
| `-fsl`, `--forced-s-lang` | none | Language(s) wanted for forced subtitles; implies `-fs`. |
|
||||
| `-fsl`, `--forced-s-lang` | none | Language(s) wanted for forced subtitles; implies `-fs`. A `-` prefix excludes. |
|
||||
| `--exact-lang` | off | Exact matching only: `-l es-419` matches `es-419`, not `es-ES`. Applies to selection and to sort order. |
|
||||
| `--sub-format` | - | Output subtitle format (`SRT`/`srt`, `VTT`/`webvtt`, `ASS`/`ssa`, `TTML`, `SMI`, ...), or `original` to keep the source format. |
|
||||
|
||||
@@ -112,7 +112,7 @@ The special language tokens `orig`, `all`, and `best` are honoured everywhere a
|
||||
|
||||
| Flag | Description |
|
||||
|---|---|
|
||||
| `-w`, `--wanted` | Wanted episodes, e.g. `S01-S05,S07`, `S01E01-S02E03`. Supports exclusions with a leading `-` (e.g. `-S03`). For a [split episode](downloading.md#split-episodes), `.N` picks one part (`S01E01.2`), a range must stay inside the episode (`S01E01.1-S01E01.3`), and `S01E01` on its own takes every part. |
|
||||
| `-w`, `--wanted` | Wanted episodes, e.g. `S01-S05,S07`, `S01E01-S02E03`. Supports exclusions with a leading `-` (e.g. `-S03`). For a [split episode](downloading.md#split-episodes), `.N` picks one part (`S01E01.2`), a range must stay inside the episode (`S01E01.1-S01E01.3`), and `S01E01` on its own takes every part. For [dated content](downloading.md#daily-and-date-based-content), a token can also be an ISO air date (`2026-08-11`) or a date range with a colon (`2026-08-01:2026-08-31`). |
|
||||
| `--select-titles` | Interactively select what to download: episodes of a series, or films when a title has more than one. **Cannot combine with `-w`.** |
|
||||
| `--latest-episode` | Download only the single most recent episode. |
|
||||
| `--list-titles` | List titles only; do not download. |
|
||||
@@ -150,13 +150,21 @@ Keep only certain track types, or skip certain track types. Attachments are alwa
|
||||
|
||||
| Flag | Description |
|
||||
|---|---|
|
||||
| `--tmdb` | TMDB ID (integer). |
|
||||
| `--imdb` | IMDb ID, e.g. `tt1375666`. |
|
||||
| `--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`. |
|
||||
| `--tmdb` | TMDB ID (integer). Used for the tags. Skips the title search. `--enrich` reads it too. Needs `tmdb_api_key`. |
|
||||
| `--imdb` | IMDb ID, e.g. `tt1375666`. Used for the tags. Skips the title search. `--enrich` reads it too. Needs no key. |
|
||||
| `--tvdb` | TVDB ID (integer). Used for the tags. Skips the series lookup that `--tvdb-order` would otherwise do. `--enrich` reads it too. Needs `tvdb_api_key`. |
|
||||
| `--anilist` | AniList ID (integer), e.g. `--anilist 21`. A MyAnimeList ID is accepted as `mal:12345` and resolved to the AniList entry. Used for the tags. Skips the title search. `--enrich` reads it too. Needs no key. |
|
||||
| `--enrich` | Overwrite show title, year and original language with the external source's. **Requires** one of `--tmdb`, `--imdb`, `--tvdb`, or `--anilist`. |
|
||||
| `--daily` | Treat the title as daily/date-based content and fill missing episode air dates from TVDB. The fill needs `--enrich` and a TVDB ID. See [Daily and date-based content](downloading.md#daily-and-date-based-content). |
|
||||
| `--tvdb-order` | Renumber episodes to a TVDB season order: `official` (aired), `dvd`, `absolute`, `alternate`, or `regional`. Needs `tvdb_api_key`. |
|
||||
|
||||
!!! note "One ID at a time"
|
||||
`--tmdb`, `--imdb` and `--tvdb` cannot be combined. Give one and unshackle resolves the
|
||||
others from it, writing all three to the tags. `--anilist` is outside that rule and pairs
|
||||
with one of them, which is how you attach a western ID to an anime title.
|
||||
An ID with no provider that can resolve it, such as `--tmdb` with no `tmdb_api_key`, fails
|
||||
before the download starts. `--anilist` needs no key, so it never fails this check.
|
||||
|
||||
#### Episode ordering
|
||||
|
||||
A service does not always number a series the way TVDB's aired order does. Some services list
|
||||
@@ -300,7 +308,7 @@ Prints a dependency table (Category / Tool / Status / Required / Purpose) showin
|
||||
| Category | Tools |
|
||||
|---|---|
|
||||
| Core | FFmpeg*, FFprobe*, MKVToolNix*, mkvpropedit* |
|
||||
| DRM | shaka-packager*, mp4decrypt, ML-Worker |
|
||||
| DRM | shaka-packager*, mp4decrypt |
|
||||
| HDR | dovi_tool, HDR10Plus_tool |
|
||||
| Subtitle | SubtitleEdit, CCExtractor |
|
||||
| Player | FFplay, MPV |
|
||||
@@ -316,6 +324,14 @@ unshackle env info
|
||||
|
||||
Shows where the config was loaded from (or lists the candidate config locations if none was found) and prints a table of every configured directory (downloads, temp, cache, cookies, logs, exports, WVDs, PRDs, services, and more).
|
||||
|
||||
### `env theme`
|
||||
|
||||
```
|
||||
unshackle env theme
|
||||
```
|
||||
|
||||
Prints a sample of every available CLI theme: colour swatches, help text with option rows, a track listing with video/audio/subtitle entries, log lines, a progress bar, and the gradient pulse bar. The active theme is marked and each theme's aliases are listed. Set your choice with the [`theme`](../reference/configuration/misc.md#appearance) config key.
|
||||
|
||||
### `env clear`
|
||||
|
||||
Clear an environment directory. The directory is emptied and recreated, and the number of files and bytes freed is reported.
|
||||
@@ -329,6 +345,7 @@ Clear an environment directory. The directory is emptied and recreated, and the
|
||||
```shell
|
||||
unshackle env check
|
||||
unshackle env info
|
||||
unshackle env theme
|
||||
unshackle env clear cache
|
||||
unshackle env clear cache EXAMPLE # one service only
|
||||
unshackle env clear temp
|
||||
|
||||
+176
-15
@@ -254,6 +254,47 @@ it is used. You can override each stream type independently:
|
||||
unshackle dl -al en EXAMPLE 81234567
|
||||
```
|
||||
|
||||
### Excluding languages
|
||||
|
||||
Put a `-` in front of a language to remove it from the selection. This works on `-l`,
|
||||
`-vl`, `-al`, `-sl`, and `-fsl`, in the same way as it works on `-w` / `--wanted`.
|
||||
|
||||
```shell title="Every subtitle language except Spanish"
|
||||
unshackle dl -sl all,-es EXAMPLE 81234567
|
||||
```
|
||||
|
||||
The exclusions are subtracted from the languages the flag would otherwise select, and the
|
||||
order of the values does not matter. If you give only exclusions, the flag keeps its own
|
||||
default: `-sl -es` is the same as `-sl all,-es`, and `-l -es` is the same as `-l orig,-es`.
|
||||
|
||||
```shell title="Only exclusions"
|
||||
# every subtitle language except Spanish and French
|
||||
unshackle dl -sl -es,-fr EXAMPLE 81234567
|
||||
|
||||
# the original audio language, unless it is Spanish
|
||||
unshackle dl -l -es EXAMPLE 81234567
|
||||
```
|
||||
|
||||
`-vl` and `-al` have no default of their own: they cascade to `-l`. An override that names
|
||||
a language replaces `-l` for that stream type, exclusions included. An override that gives
|
||||
only exclusions adds them to the ones from `-l`.
|
||||
|
||||
```shell title="Cascade"
|
||||
# video keeps the Japanese track; only the audio drops Spanish
|
||||
unshackle dl -l en,-es -vl ja EXAMPLE 81234567
|
||||
```
|
||||
|
||||
!!! note "Rules for exclusion tokens"
|
||||
- `orig` is resolved per title, so `-sl -orig` drops the subtitles in the title's
|
||||
original language.
|
||||
- `--exact-lang` applies to exclusions with the same matching rules as selection:
|
||||
`-es` removes exactly the tracks that `es` would select. Without it, `-es` also
|
||||
removes `es-419` and `es-ES`.
|
||||
- Tracks with no language tag are never excluded.
|
||||
- `-all` is rejected. Name the languages you do not want instead.
|
||||
- The comma form is the documented style. `-sl -es` also works, but a shell can read
|
||||
a lone `-es` as another option.
|
||||
|
||||
### Sort order
|
||||
|
||||
`-l` and `-sl` **select** languages: naming some removes the rest. To keep every language
|
||||
@@ -296,6 +337,10 @@ every available subtitle language is downloaded.
|
||||
unshackle dl -sl en,es EXAMPLE 81234567
|
||||
```
|
||||
|
||||
To keep the default and drop one language, use the `-` prefix described in
|
||||
[Excluding languages](#excluding-languages). `-sl all,-es` keeps every subtitle language
|
||||
except Spanish, forced Spanish subtitles included.
|
||||
|
||||
### Requiring subtitles
|
||||
|
||||
`--require-subs` takes a list of languages that **must** exist. If they all exist, *all*
|
||||
@@ -311,7 +356,8 @@ download on the presence of a specific subtitle track.
|
||||
Without this flag, forced subs are dropped from selection.
|
||||
- `-fsl` / `--forced-s-lang`: keep forced subtitles only in these languages (implies
|
||||
`-fs`). Works independently of `--s-lang`, so `-sl all -fsl en` grabs every full
|
||||
subtitle but only the English forced track.
|
||||
subtitle but only the English forced track. It accepts exclusions too: `-fsl all,-es`
|
||||
keeps every forced subtitle except the Spanish one, and `-fsl -es` means the same.
|
||||
- `--sub-format`: set the output subtitle format, converting only when necessary.
|
||||
Accepts codec names/values and common aliases (`srt`, `vtt`, `ass`, `ssa`, `ttml`,
|
||||
etc.), or the literal `original` to keep the source format.
|
||||
@@ -381,6 +427,43 @@ with `-` to exclude it.
|
||||
unshackle dl -w S01,-S01E01.2 EXAMPLE 81234567
|
||||
```
|
||||
|
||||
=== "Air dates"
|
||||
|
||||
```shell
|
||||
# One day
|
||||
unshackle dl -w 2026-08-11 EXAMPLE 81234567
|
||||
|
||||
# A range of days, colon separated
|
||||
unshackle dl -w 2026-08-01:2026-08-31 EXAMPLE 81234567
|
||||
|
||||
# August, but not the 15th
|
||||
unshackle dl -w 2026-08-01:2026-08-31,-2026-08-15 EXAMPLE 81234567
|
||||
```
|
||||
|
||||
### Daily and date-based content
|
||||
|
||||
Talk shows, news and sports have no official episode numbering, so unshackle names them
|
||||
by air date. An episode that carries an air date is written as `Show.YYYY.MM.DD` instead of
|
||||
`SxxExx`, the `{date}` token holds the ISO date, and the season folder becomes the year.
|
||||
|
||||
A service that only carries this kind of content sets `DAILY = True` on its class, and a
|
||||
service can set `air_date` on each episode itself. Add `--daily` to mark any other title
|
||||
as date-based:
|
||||
|
||||
```shell
|
||||
unshackle dl --daily --tvdb 73871 --enrich EXAMPLE 81234567
|
||||
```
|
||||
|
||||
With `--enrich` and a TVDB ID, `--daily` fills in the air date of every episode that has
|
||||
none. An air date the service already set is kept. Dates before 1970 and dates in the
|
||||
future are skipped, because TVDB carries placeholder schedule dates for episodes that
|
||||
have not aired. Without `--enrich` unshackle has no source to fill from, and says so.
|
||||
|
||||
A dated episode answers to its air date in `-w`, as well as to its `SxxExx` key. A date
|
||||
token is a plain ISO date (`2026-08-11`). A date range uses a colon (`2026-08-01:2026-08-31`),
|
||||
because the dashes in a date are part of the date. A range cannot span more than 1000 days.
|
||||
Date tokens and `SxxExx` tokens can be mixed in one `-w`.
|
||||
|
||||
### Split episodes
|
||||
|
||||
A few services split one episode into several separately playable videos. Where a service
|
||||
@@ -577,21 +660,98 @@ unshackle dl --skip-dl --export EXAMPLE 81234567
|
||||
## Metadata and tagging
|
||||
|
||||
unshackle looks up metadata automatically, but you can override the identifiers used for
|
||||
tagging and naming:
|
||||
tagging and naming. An ID you give is authoritative: unshackle looks it up directly instead of
|
||||
searching by title, and the ID stays in the tags. An ID only settles *which* title this is.
|
||||
To also take that source's title, year and original language, add `--enrich`. Give at most one
|
||||
of `--tmdb`, `--imdb` and `--tvdb`; unshackle works the rest out from it. To stop the automatic
|
||||
lookups but keep the IDs you give, set
|
||||
[`disable_metadata`](../reference/configuration/misc.md#external-api-keys) in your config.
|
||||
|
||||
| Flag | Example | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `--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`. |
|
||||
| `--tmdb` | `--tmdb 27205` | Use this TMDB ID instead of an automatic search. Needs `tmdb_api_key`. |
|
||||
| `--imdb` | `--imdb tt1375666` | Use this IMDb ID instead of an automatic search. Needs no key. |
|
||||
| `--tvdb` | `--tvdb 73871` | Use this TVDB ID instead of looking the series up. Needs `tvdb_api_key`. |
|
||||
| `--anilist` | `--anilist 21` | Use this AniList ID instead of an automatic search. `mal:12345` is also accepted. Needs no key. |
|
||||
| `--enrich` | - | Overwrite the show title, year and original language with the external source's. **Requires** one of `--tmdb`, `--imdb`, `--tvdb`, or `--anilist`. |
|
||||
| `--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"
|
||||
```shell title="Force the right IMDb match, and keep the service's own naming"
|
||||
unshackle dl --imdb tt1375666 EXAMPLE 81234567
|
||||
```
|
||||
|
||||
```shell title="Force the match and take IMDb's title, year and language too"
|
||||
unshackle dl --imdb tt1375666 --enrich EXAMPLE 81234567
|
||||
```
|
||||
|
||||
### What each metadata provider supplies
|
||||
|
||||
Providers differ in what they answer with, so the fields `--enrich` can replace depend on
|
||||
which ID you gave. Every provider except `imdb` only runs when its key is configured:
|
||||
|
||||
| Provider | Config key | Title and year | Original language | External IDs it returns |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| TMDB | `tmdb_api_key` | yes | yes, alpha-2 such as `ko` | IMDb, TMDB, TVDB |
|
||||
| TVDB | `tvdb_api_key` | yes | yes, alpha-3 such as `kor` | TMDB, TVDB, sometimes IMDb |
|
||||
| OMDb | `omdb_api_key` | yes | yes, as an English name such as `Korean` | IMDb |
|
||||
| IMDb | *(no key needed)* | yes | yes, alpha-2 such as `ko` | IMDb |
|
||||
| SIMKL | `simkl_client_id` | yes | no, it publishes a country and no language | IMDb, TMDB, TVDB |
|
||||
| AniList | *(no key needed)* | yes | yes, worked out from the country of origin, such as `ja` | AniList |
|
||||
|
||||
Whatever the tag looks like, unshackle normalises it before use, so `ko`, `kor` and `Korean`
|
||||
all end up as the same language.
|
||||
|
||||
!!! note "AniList only answers for anime"
|
||||
It is last in the default provider order and returns nothing for a title that is not
|
||||
anime. The only cost is one search that misses. Put `anilist` earlier in
|
||||
[`metadata_providers`](../reference/configuration/misc.md#external-api-keys) if you mostly
|
||||
download anime. Which of the three AniList title variants is used is set by
|
||||
[`anilist_title_language`](../reference/configuration/misc.md#external-api-keys).
|
||||
|
||||
A service can also mark its titles as anime. For those titles unshackle tries AniList
|
||||
first. When AniList has no match, it falls through to the normal order.
|
||||
|
||||
Each ID goes to the providers that read that kind of ID, in
|
||||
[`metadata_providers`](../reference/configuration/misc.md#external-api-keys) order:
|
||||
|
||||
- `--tmdb` reads TMDB.
|
||||
- `--imdb` reads IMDb, then falls back to OMDb. IMDb needs no key, so this path works out of
|
||||
the box, and an OMDb key only matters when IMDb has no answer.
|
||||
- `--tvdb` reads TVDB. It needs `tvdb_api_key`.
|
||||
- `--anilist` reads AniList, which needs no key. It supplies the title, the year and the
|
||||
original language, and writes an AniList tag. It knows no TMDB, IMDB or TVDB ID, so pair it
|
||||
with `--tmdb`, `--imdb` or `--tvdb` when you want those tags as well.
|
||||
|
||||
Give **one** of `--tmdb`, `--imdb` and `--tvdb`. They cannot be combined, because one ID does
|
||||
the job on its own: unshackle resolves the other two from it and writes all three to the tags.
|
||||
Passing two is an error rather than a silent choice between them. `--anilist` is the exception
|
||||
and still pairs with one of the three, which is how you tag an anime title with a western ID.
|
||||
|
||||
The ID you give must have a provider that can actually resolve it, so unshackle checks that
|
||||
before it downloads anything. `--tmdb` without `tmdb_api_key`, or an ID whose providers your
|
||||
`metadata_providers` list leaves out, fails immediately with a message naming what to set.
|
||||
`--imdb` needs no key, since the `imdb` provider is keyless and in the default order.
|
||||
|
||||
With `--enrich`, the title, year and original language are all replaced with the external
|
||||
source's values, whether or not the service already filled them in. A field the source does
|
||||
not answer with is left alone, and unshackle logs which fields those were, so a provider with
|
||||
a thin record cannot blank out what the service told you.
|
||||
|
||||
`--enrich` also fills in the absolute episode number of each episode from TVDB's absolute
|
||||
order, for any series that has one and where the service did not supply it. Anime is the
|
||||
usual beneficiary, but no part of this is limited to anime. This only adds the
|
||||
[`{absolute}`](../reference/configuration/output.md#output_template) naming variable. The
|
||||
season and episode numbers are never changed.
|
||||
|
||||
With `--daily`, `--enrich` also fills in the air date of each episode from TVDB. See
|
||||
[Daily and date-based content](#daily-and-date-based-content).
|
||||
|
||||
!!! warning "`--enrich` replaces the original language, which affects more than the filename"
|
||||
Track selection reads the original language, so replacing it changes which audio is
|
||||
treated as the original. That is the point when a service mislabels it, but it means a
|
||||
wrong ID can pick the wrong audio track and not only write a wrong name. Without
|
||||
`--enrich` the service's own value is kept and track selection is untouched.
|
||||
|
||||
### Episode ordering
|
||||
|
||||
A service does not always number a series the way TVDB's aired order does. Some services list
|
||||
@@ -637,14 +797,15 @@ authoritative list.
|
||||
| `--range` | `-r` | Color range(s); default `SDR`. |
|
||||
| `--channels` | `-c` | Audio channel layout. |
|
||||
| `--noatmos` | `-naa` | Exclude Atmos audio. |
|
||||
| `--lang` | `-l` | Video + audio language(s); default `orig`. |
|
||||
| `--a-lang` | `-al` | Audio-only language override. |
|
||||
| `--v-lang` | `-vl` | Video-only language override. |
|
||||
| `--s-lang` | `-sl` | Subtitle language(s); default `all`. |
|
||||
| `--lang` | `-l` | Video + audio language(s); default `orig`. `-` excludes, e.g. `all,-es`. |
|
||||
| `--a-lang` | `-al` | Audio-only language override. `-` excludes. |
|
||||
| `--v-lang` | `-vl` | Video-only language override. `-` excludes. |
|
||||
| `--s-lang` | `-sl` | Subtitle language(s); default `all`. `-` excludes, e.g. `all,-es`. |
|
||||
| `--forced-subs` | `-fs` | Include forced subtitles. |
|
||||
| `--forced-s-lang` | `-fsl` | Forced subtitle language(s); implies `-fs`. |
|
||||
| `--forced-s-lang` | `-fsl` | Forced subtitle language(s); implies `-fs`. `-` excludes. |
|
||||
| `--sub-format` | | Output subtitle format. |
|
||||
| `--wanted` | `-w` | Episode/season range. |
|
||||
| `--wanted` | `-w` | Episode/season range, or an air date. |
|
||||
| `--daily` | | Fill missing air dates from TVDB during `--enrich`. |
|
||||
| `--select-titles` | | Interactively pick episodes or films. |
|
||||
| `--latest-episode` | | Only the newest episode. |
|
||||
| `--video-only` / `--audio-only` / `--subs-only` | `-V` / `-A` / `-S` | Restrict track types. |
|
||||
@@ -658,5 +819,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` / `--tvdb` / `--animeapi` / `--enrich` | | Metadata overrides. |
|
||||
| `--tmdb` / `--imdb` / `--tvdb` / `--anilist` / `--enrich` | | Metadata overrides. |
|
||||
| `--tvdb-order` | | Renumber episodes to a TVDB season order. |
|
||||
|
||||
@@ -127,6 +127,7 @@ Every variable below is valid in both output and folder templates. Values are de
|
||||
| `season_episode` | Combined | `S01E05` |
|
||||
| `episode_name` | Episode title | `Pilot` |
|
||||
| `part` | Part index of a [split episode](#split-episodes), empty otherwise | `2` |
|
||||
| `absolute` | Absolute episode number, zero-padded to 3 digits, empty when unknown | `007` |
|
||||
| `date` | ISO air date for daily/dated content | `2024-06-01` |
|
||||
|
||||
!!! note "Daily & sports content"
|
||||
|
||||
@@ -67,10 +67,10 @@ Subtitle selection happens through `dl` flags. The most important is language se
|
||||
|
||||
| Flag | Purpose |
|
||||
| --- | --- |
|
||||
| `-sl`, `--s-lang` | Language(s) wanted for subtitles. Defaults to `all`. |
|
||||
| `-sl`, `--s-lang` | Language(s) wanted for subtitles. Defaults to `all`. A `-` prefix excludes, e.g. `all,-es`. |
|
||||
| `--require-subs` | Require these languages to exist; if present, download **all** subtitles. Cannot be combined with `--s-lang`. |
|
||||
| `-fs`, `--forced-subs` | Include forced subtitle tracks (excluded by default). |
|
||||
| `-fsl`, `--forced-s-lang` | Language(s) wanted for forced subtitles; implies `-fs`. |
|
||||
| `-fsl`, `--forced-s-lang` | Language(s) wanted for forced subtitles; implies `-fs`. A `-` prefix excludes. |
|
||||
| `--exact-lang` | Exact language matching, with no regional variants. |
|
||||
| `-S`, `--subs-only` | Download only subtitle tracks. |
|
||||
| `-ns`, `--no-subs` | Do not download subtitle tracks at all. |
|
||||
|
||||
@@ -18,7 +18,7 @@ after the flag's internal destination rather than its visible name; set these ex
|
||||
| `--list` | `list` |
|
||||
| `--tmdb` | `tmdb_id` |
|
||||
| `--imdb` | `imdb_id` |
|
||||
| `--animeapi` | `animeapi_id` |
|
||||
| `--anilist` | `anilist_id` |
|
||||
| `-naa` / `--noatmos` | `no_atmos` |
|
||||
| `-o` / `--output` | `output_dir` |
|
||||
| `--cdm-only` / `--vaults-only` | `cdm_only` |
|
||||
@@ -31,9 +31,9 @@ Common keys (a useful subset; every `dl` flag works):
|
||||
|
||||
| Key | Type | Default | Sets |
|
||||
|-----|------|---------|------|
|
||||
| `lang` | list | `["orig"]` | Video/audio language(s); `orig` = original language. |
|
||||
| `a_lang` / `v_lang` | list | `[]` | Audio- / video-only language override. |
|
||||
| `s_lang` | list | `["all"]` | Subtitle language(s). |
|
||||
| `lang` | list | `["orig"]` | Video/audio language(s); `orig` = original language. A `-` prefix excludes, e.g. `[all, -es]`. |
|
||||
| `a_lang` / `v_lang` | list | `[]` | Audio- / video-only language override. A `-` prefix excludes. |
|
||||
| `s_lang` | list | `["all"]` | Subtitle language(s). A `-` prefix excludes, e.g. `[all, -es]`. |
|
||||
| `quality` | list | `[]` (best) | Resolution(s), e.g. `[1080]`. |
|
||||
| `vcodec` | list | `[]` (any) | Video codec(s), e.g. `[H265]`. |
|
||||
| `acodec` | list | `[]` (any) | Audio codec(s), e.g. `[EC3]`. |
|
||||
@@ -41,7 +41,7 @@ Common keys (a useful subset; every `dl` flag works):
|
||||
| `channels` | float | *(unset)* | Audio channels, e.g. `6` for 5.1. |
|
||||
| `sub_format` | str | *(unset)* | Convert subtitles to this format (`srt`, `vtt`, `original`, ...). |
|
||||
| `forced_subs` | bool | `false` | Include forced subtitle tracks. |
|
||||
| `forced_s_lang` | list | `[]` | Forced subtitle language(s); implies `forced_subs`. |
|
||||
| `forced_s_lang` | list | `[]` | Forced subtitle language(s); implies `forced_subs`. A `-` prefix excludes. |
|
||||
| `no_subs` / `no_audio` / `no_chapters` | bool | `false` | Skip that track type. |
|
||||
| `downloads` | int | `1` | Tracks downloaded concurrently. |
|
||||
| `workers` | int | *(downloader default)* | Threads per track. |
|
||||
@@ -61,6 +61,18 @@ dl:
|
||||
downloads: 2
|
||||
```
|
||||
|
||||
!!! note "Language exclusions in YAML"
|
||||
The language keys accept the same `-` exclusion tokens as the command line. Give them
|
||||
as a list or as one comma-separated string.
|
||||
|
||||
```yaml
|
||||
dl:
|
||||
s_lang: [all, -es]
|
||||
a_lang: "orig,-es"
|
||||
```
|
||||
|
||||
See [Excluding languages](../../guide/downloading.md#excluding-languages) for the rules.
|
||||
|
||||
!!! note "Per-service overrides"
|
||||
A `dl` block nested under a service in [`services`](services.md) takes the same keys and
|
||||
applies to that service only.
|
||||
|
||||
@@ -36,7 +36,8 @@ Where the file lives, how unshackle discovers it, and how to edit it:
|
||||
| [DRM & CDM](drm.md) | `cdm`, `remote_cdm`, `decryption` |
|
||||
| [Network & proxy](network.md) | `network`, `headers`, `proxy_providers` |
|
||||
| [Key vaults](vaults.md) | `key_vaults`, `vault_timeout` |
|
||||
| [External API keys](misc.md#external-api-keys) | `imdb_api_enabled`, `omdb_api_key`, `tmdb_api_key`, `tvdb_api_key`, `tvdb_pin`, `tvdb_order`, `simkl_client_id`, `metadata_providers`, `decrypt_labs_api_key`, `ipinfo_api_key` |
|
||||
| [External API keys](misc.md#external-api-keys) | `omdb_api_key`, `tmdb_api_key`, `tvdb_api_key`, `tvdb_pin`, `tvdb_order`, `simkl_client_id`, `metadata_providers`, `anilist_title_language`, `disable_metadata`, `decrypt_labs_api_key`, `ipinfo_api_key` |
|
||||
| [Caching & updates](misc.md#caching-updates) | `title_cache_enabled`, `title_cache_time`, `title_cache_max_retention`, `update_checks`, `update_check_interval` |
|
||||
| [Appearance](misc.md#appearance) | `theme` |
|
||||
| [Logging, privacy & debug](misc.md#logging-privacy-debug) | `redact_paths`, `debug`, `debug_keys`, `debug_requests`, `set_terminal_bg` |
|
||||
| [Deprecated & removed](misc.md#deprecated-removed-keys) | `curl_impersonate`, `downloader`, `scene_naming` |
|
||||
|
||||
@@ -4,18 +4,21 @@ Smaller configuration areas: external metadata API keys, caching and update chec
|
||||
|
||||
## External API keys { #external-api-keys }
|
||||
|
||||
All are unset by default and enable optional metadata/geolocation features.
|
||||
All are unset by default and enable optional metadata/geolocation features. For which fields
|
||||
each metadata provider can actually answer with, see
|
||||
[What each metadata provider supplies](../../guide/downloading.md#what-each-metadata-provider-supplies).
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `imdb_api_enabled` | bool | `false` | Use the free IMDxAPI (api.tiffara.com) metadata provider, which needs no API key. Off by default since the site has been unreliable. |
|
||||
| `omdb_api_key` | str | `""` | [OMDb](https://www.omdbapi.com/) API key for IMDb metadata lookups; a more reliable alternative to IMDxAPI. Free keys are available on the OMDb site. |
|
||||
| `omdb_api_key` | str | `""` | [OMDb](https://www.omdbapi.com/) API key for IMDb metadata lookups; a fallback for when the keyless `imdb` provider has no answer. Free keys are available on the OMDb site. |
|
||||
| `tmdb_api_key` | str | `""` | TMDB API key for metadata enrichment and external-ID tags. |
|
||||
| `simkl_client_id` | str | `""` | SIMKL client ID for metadata lookups; an alternative/fallback source to TMDB. |
|
||||
| `tvdb_api_key` | str | `""` | [TheTVDB v4](https://thetvdb.com/api-information) API key; a fallback source to TMDB, strongest on TV series. Free keys are available on the TVDB site. |
|
||||
| `tvdb_api_key` | str | `""` | [TheTVDB v4](https://thetvdb.com/api-information) API key; a fallback source to TMDB, strongest on TV series. Also the source `--enrich --tvdb` reads. Free keys are available on the TVDB site. |
|
||||
| `tvdb_pin` | str | `""` | Subscriber PIN, only needed for a user-supported TVDB key. Leave empty for a normal project key. |
|
||||
| `tvdb_order` | str | `""` | Default for `--tvdb-order`: renumber episodes to a TVDB season order (`official`, `dvd`, `absolute`, `alternate`, `regional`). Empty keeps the numbering the service gives. |
|
||||
| `metadata_providers` | list | *(see below)* | Metadata providers to use, in the order they are tried. |
|
||||
| `metadata_providers` | list or map | *(see below)* | Metadata providers to use, in the order they are tried. |
|
||||
| `anilist_title_language` | str | `english` | Which AniList title variant to use: `english`, `romaji`, or `native`. |
|
||||
| `disable_metadata` | bool | `false` | Set to `true` to stop all automatic metadata lookups. An ID you give yourself is still looked up. |
|
||||
| `decrypt_labs_api_key` | str | `""` | Global Decrypt Labs API key (used by remote CDM / vault). |
|
||||
| `ipinfo_api_key` | str | `""` | ipinfo.io API key for IP/region lookups. |
|
||||
|
||||
@@ -31,12 +34,77 @@ All are unset by default and enable optional metadata/geolocation features.
|
||||
ignored with a warning. Leave it unset for the default order:
|
||||
|
||||
```yaml
|
||||
metadata_providers: [imdbapi, omdb, simkl, tmdb, tvdb]
|
||||
metadata_providers: [imdb, omdb, simkl, tmdb, tvdb, anilist]
|
||||
```
|
||||
|
||||
Whatever the order, a provider is skipped when its API key is missing (or, for
|
||||
`imdbapi`, when `imdb_api_enabled` is `false`). Available names are
|
||||
`imdbapi`, `omdb`, `simkl`, `tmdb`, and `tvdb`.
|
||||
Whatever the order, unshackle skips a provider that has no API key. `imdb` and
|
||||
`anilist` need no key, so they are always available. Available names are `imdb`, `omdb`,
|
||||
`simkl`, `tmdb`, `tvdb`, and `anilist`. The old name `imdbapi` still works and is read as
|
||||
`imdb`.
|
||||
|
||||
`anilist` is last in the default order. It only answers for anime and returns nothing for
|
||||
anything else, so it is harmless there. Move it earlier if you mostly download anime.
|
||||
|
||||
The order applies to a title search and to a direct lookup of an ID you give with
|
||||
`--tmdb`, `--imdb`, `--tvdb`, or `--anilist`. A supplied ID always goes to the providers
|
||||
that read that kind of ID, and it never falls back to a title search.
|
||||
|
||||
!!! note "Which AniList title `anilist_title_language` picks"
|
||||
AniList holds up to three titles for a work: the English one, the romaji transliteration,
|
||||
and the native one. This option says which of them unshackle uses:
|
||||
|
||||
```yaml
|
||||
anilist_title_language: romaji
|
||||
```
|
||||
|
||||
A work does not always have all three. When the one you asked for is unset on AniList's
|
||||
side, unshackle falls back in the order english → romaji → native. It takes the first one
|
||||
that is set, so you always get a title.
|
||||
|
||||
!!! note "What `disable_metadata` turns off"
|
||||
With `disable_metadata: true`, unshackle never contacts a metadata provider on its own.
|
||||
The title search is dead, and that includes the keyless `imdb` provider. Titles, years and
|
||||
languages then come only from the service.
|
||||
|
||||
```yaml
|
||||
disable_metadata: true
|
||||
```
|
||||
|
||||
An ID you give with `--tmdb`, `--imdb`, `--tvdb`, or `--anilist` is your permission to use
|
||||
that ID. That lookup still works. unshackle looks the ID up directly, cross references the other
|
||||
IDs from it, and `--enrich` still reads that source. Only the lookups you did not ask for
|
||||
are stopped.
|
||||
|
||||
!!! note "The `imdb` provider needs no key"
|
||||
It replaces the earlier `imdbapi` provider, which read a third-party mirror
|
||||
(api.tiffara.com) and needed the `imdb_api_enabled` switch. That option is gone: delete it
|
||||
from your config, where it is now ignored.
|
||||
|
||||
!!! tip "A different order per title kind"
|
||||
Give a map instead of one list when the best source differs by kind. TVDB is strongest on
|
||||
series, TMDB on films. There are two kinds, `tv` and `movie`, and this example sets both
|
||||
of them and names every provider, so nothing is left to the default:
|
||||
|
||||
```yaml
|
||||
metadata_providers:
|
||||
tv: [tvdb, tmdb, simkl, imdb, omdb]
|
||||
movie: [tmdb, imdb, omdb, simkl, tvdb]
|
||||
```
|
||||
|
||||
Each list is independent: it both orders and filters that kind on its own, so a provider
|
||||
you leave out of `tv` is still used for `movie`. Here TVDB is tried first for a series and
|
||||
last for a film.
|
||||
|
||||
You do not need to give both keys, or a full list in each. A kind you leave out uses the
|
||||
default order:
|
||||
|
||||
```yaml
|
||||
metadata_providers:
|
||||
tv: [tvdb, tmdb] # movies keep the default order
|
||||
```
|
||||
|
||||
`tv` covers every episode and `movie` covers every film. unshackle only looks up
|
||||
metadata for those two kinds, so any other key, such as `anime` or `music`, is ignored.
|
||||
|
||||
!!! note "`ipinfo_api_key` never touches your service sessions"
|
||||
The token is only ever sent to `api.ipinfo.io` as a per-request `Authorization` header; it
|
||||
@@ -73,6 +141,14 @@ calls.
|
||||
|
||||
---
|
||||
|
||||
## Appearance { #appearance }
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `theme` | str | `catppuccin-mocha` | Named colour theme for all CLI output: banner, logs, progress bars, and help screens. One of `catppuccin-mocha` (aliases `default`, `catppuccin`, `mocha`), `dracula`, `nord`, `gruvbox`, `one-dark` (alias `onedark`), `tokyo-night` (alias `tokyonight`), `monokai`, `flexoki`, `solarized-dark` (alias `solarized`). Case-insensitive; underscores work in place of hyphens. Unknown names fall back to the default with a warning. Preview them all with `unshackle env theme`. |
|
||||
|
||||
---
|
||||
|
||||
## Logging, privacy & debug { #logging-privacy-debug }
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
@@ -107,3 +183,4 @@ calls.
|
||||
| `curl_impersonate` | **Deprecated** → use [`network`](network.md) | Emits a `DeprecationWarning`; still honoured only if `network` is absent. |
|
||||
| `downloader` | **Deprecated** | Any value other than `"requests"` emits a `DeprecationWarning`; the value is otherwise ignored (the unified requests downloader is always used). |
|
||||
| `scene_naming` | **Removed** | If set to any non-null value, unshackle exits with an error directing you to configure [`output_template`](output.md) instead. |
|
||||
| `imdb_api_enabled` | **Removed** | Ignored. It gated the old `imdbapi` provider, which the keyless [`imdb`](#external-api-keys) provider replaces. Safe to delete from your config. |
|
||||
|
||||
@@ -35,7 +35,7 @@ folder-kind keys.
|
||||
|
||||
??? example "All valid template variables"
|
||||
`title`, `year`, `season`, `episode`, `season_episode`, `episode_name`, `part`,
|
||||
`date`, `quality`, `resolution`, `source`, `tag`, `track_number`, `artist`,
|
||||
`absolute`, `date`, `quality`, `resolution`, `source`, `tag`, `track_number`, `artist`,
|
||||
`album_artist`, `album`, `disc`, `track_total`, `disc_total`, `release_type`, `genre`,
|
||||
`explicit`, `isrc`, `upc`, `label`, `audio`, `audio_channels`, `audio_full`, `atmos`,
|
||||
`dual`, `multi`, `dubbed`, `video`, `hdr`, `hfr`, `edition`, `repack`, `lang_tag`,
|
||||
@@ -51,6 +51,14 @@ folder-kind keys.
|
||||
`{season_episode}`, and note that it is always empty in a folder template, since
|
||||
folders do not carry the part.
|
||||
|
||||
!!! tip "`{absolute}` counts episodes across seasons"
|
||||
`absolute` holds the absolute episode number, zero-padded to 3 digits (`007`), and is
|
||||
empty on titles that have none. It is added to the name and never replaces `{season}`
|
||||
or `{episode}`. Any series with a TVDB absolute order can use it, anime most often.
|
||||
Services can supply it, and
|
||||
[`--enrich`](../../guide/downloading.md#metadata-and-tagging) fills it in from TVDB.
|
||||
Use `{absolute?}` so the name stays clean when it is unknown.
|
||||
|
||||
## Tagging & naming keys
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|
||||
@@ -82,11 +82,22 @@ keep auth tokens in localStorage rather than in HTTP cookies need. Extraction is
|
||||
|
||||
Definitions of remote unshackle service servers, used by the `--remote` mode. Each entry is
|
||||
named by you (pick it with `--server`, or omit that flag when only one is configured) and gives
|
||||
the server's `url` (required), an optional `api_key` sent as `X-Secret-Key`, an optional
|
||||
`server_cdm` boolean, and an optional `services` sub-dict of per-service local overrides such
|
||||
as `title_map`. In `--remote` mode unshackle turns the server's service list into synthetic CLI
|
||||
the server's `url` (required), an optional `api_key`, an optional `auth_headers` list, an
|
||||
optional `server_cdm` boolean, and an optional `services` sub-dict of per-service local
|
||||
overrides such as `title_map`.
|
||||
|
||||
`auth_headers` lists extra header names to send the API key in, tried before the defaults
|
||||
`X-Secret-Key` and `X-Api-Key`, which are always appended as fallbacks. unshackle sends the
|
||||
first name; if the server answers `401`, it retries the same request with the next name, and
|
||||
keeps the one that works for the rest of the session. Names you list keep your spelling and are
|
||||
not repeated in the fallbacks, so `auth_headers: ["Authorization", "x-secret-key"]` is tried as
|
||||
`Authorization`, `x-secret-key`, `X-Api-Key`.
|
||||
|
||||
In `--remote` mode unshackle turns the server's service list into synthetic CLI
|
||||
commands that run against it, falling back to the tags in that `services` sub-dict when the
|
||||
list cannot be fetched. See [remote sessions](../../dev/rest-api/remote-sessions.md) for the
|
||||
list cannot be fetched. Each synthetic command carries the server-side service's options and
|
||||
documentation, so `unshackle dl --remote <TAG> -h` shows the same help text as it does on the
|
||||
server. See [remote sessions](../../dev/rest-api/remote-sessions.md) for the
|
||||
full setup.
|
||||
|
||||
## `serve`
|
||||
@@ -117,6 +128,13 @@ Each entry under `users` is keyed by that user's API key and may set its own `se
|
||||
`username` used as the log label for that key (defaults to a truncated form of the key). A
|
||||
user with no `playready_devices` key gets no PlayReady access at all, not the global list.
|
||||
|
||||
`server_cdm` decides whether the server runs the CDM licensing for that key. It is `false`
|
||||
unless the entry sets it, so a remote client configured with `server_cdm: true` is told to
|
||||
license with its own local CDM instead, and a client that asks anyway gets a `FORBIDDEN`
|
||||
error. Because a download job always licenses with the server's CDM, a key without
|
||||
`server_cdm` also cannot submit or retry `/api/download` jobs. Keys that have no `users`
|
||||
entry, such as `api_secret`, keep server CDM access.
|
||||
|
||||
```yaml
|
||||
serve:
|
||||
api_secret: change-me
|
||||
@@ -128,6 +146,8 @@ serve:
|
||||
users:
|
||||
a1b2c3d4: # this user's API key
|
||||
services: [EXAMPLE1] # may only use EXAMPLE1
|
||||
e5f6a7b8:
|
||||
server_cdm: true # this key may have the server do the licensing
|
||||
```
|
||||
|
||||
!!! note "`dl` keys inside `serve`"
|
||||
|
||||
Reference in New Issue
Block a user