mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-05-17 06:09:29 +00:00
a7af898617
Replace get_ip_info + get_cached_ip_info pair with a single unshackle.core.utils.ip_info module providing a normalized return shape across providers. Adds optional ipinfo_api_key config for the ipinfo.io Lite endpoint (higher rate limits, ASN/org/continent data), swaps the ipapi.co fallback for ip-api.in, and migrates all callers (service, gluetun, remote_service, api/handlers, DSNP, YT) to the new import path. Auth token is sent per-request and never attached to the shared session headers.
184 lines
6.5 KiB
Markdown
184 lines
6.5 KiB
Markdown
# Service Integration & Authentication Configuration
|
|
|
|
This document covers service-specific configuration, authentication, and metadata integration options.
|
|
|
|
## services (dict)
|
|
|
|
Configuration data for each Service. The Service will have the data within this section merged into the per-service
|
|
`config.yaml` (located in the service's directory) before being provided to the Service class.
|
|
|
|
Think of this config to be used for more sensitive configuration data, like user or device-specific API keys, IDs,
|
|
device attributes, and so on. A per-service `config.yaml` file is typically shared and not meant to be modified,
|
|
so use this for any sensitive configuration data.
|
|
|
|
The Key is the Service Tag, but can take any arbitrary form for its value. It's expected to begin as either a list or
|
|
a dictionary.
|
|
|
|
For example,
|
|
|
|
```yaml
|
|
EXAMPLE:
|
|
client:
|
|
auth_scheme: MESSO
|
|
# ... more sensitive data
|
|
```
|
|
|
|
### Per-Service Configuration Overrides
|
|
|
|
You can override many global configuration options on a per-service basis by nesting them under the
|
|
service tag in the `services` section. Supported override keys include: `dl`, `aria2c`, `n_m3u8dl_re`,
|
|
`curl_impersonate`, `subtitle`, `muxing`, `headers`, and more.
|
|
|
|
Overrides are merged with global config (not replaced) -- only specified keys are overridden, others
|
|
use global defaults. CLI arguments always take priority over service-specific config.
|
|
|
|
For example,
|
|
|
|
```yaml
|
|
services:
|
|
RATE_LIMITED_SERVICE:
|
|
dl:
|
|
downloads: 2 # Limit concurrent track downloads
|
|
workers: 4 # Reduce workers to avoid rate limits
|
|
n_m3u8dl_re:
|
|
thread_count: 4 # Very low thread count
|
|
aria2c:
|
|
max_concurrent_downloads: 1
|
|
```
|
|
|
|
---
|
|
|
|
## credentials (dict[str, str|list|dict])
|
|
|
|
Specify login credentials to use for each Service, and optionally per-profile.
|
|
|
|
For example,
|
|
|
|
```yaml
|
|
EXAMPLE: jane@example.tld:LoremIpsum100 # directly
|
|
EXAMPLE2: # or per-profile, optionally with a default
|
|
default: jane@example.tld:LoremIpsum99 # <-- used by default if -p/--profile is not used
|
|
james: james@example.tld:TheFriend97
|
|
john: john@example.tld:LoremIpsum98
|
|
EXAMPLE3: # the `default` key is not necessary, but no credential will be used by default
|
|
john: john@example.tld:SecretPassword123
|
|
```
|
|
|
|
The value should be in string form, i.e. `john@example.tld:password123` or `john:password123`.
|
|
Any arbitrary values can be used on the left (username/password/phone) and right (password/secret).
|
|
You can also specify these in list form, i.e., `["john@example.tld", ":PasswordWithAColon"]`.
|
|
|
|
If you specify multiple credentials with keys like the `EXAMPLE2` and `EXAMPLE3` example above, then you should
|
|
use a `default` key or no credential will be loaded automatically unless you use `-p/--profile`. You
|
|
do not have to use a `default` key at all.
|
|
|
|
Please be aware that this information is sensitive and to keep it safe. Do not share your config.
|
|
|
|
---
|
|
|
|
## tmdb_api_key (str)
|
|
|
|
API key for The Movie Database (TMDB). This is used for tagging downloaded files with TMDB,
|
|
IMDB and TVDB identifiers. Leave empty to disable automatic lookups.
|
|
|
|
To obtain a TMDB API key:
|
|
|
|
1. Create an account at <https://www.themoviedb.org/>
|
|
2. Go to <https://www.themoviedb.org/settings/api> to register for API access
|
|
3. Fill out the API application form with your project details
|
|
4. Once approved, you'll receive your API key
|
|
|
|
For example,
|
|
|
|
```yaml
|
|
tmdb_api_key: cf66bf18956kca5311ada3bebb84eb9a # Not a real key
|
|
```
|
|
|
|
**Note**: Keep your API key secure and do not share it publicly. This key is used by the `core/providers/tmdb.py` metadata provider to fetch metadata from TMDB for proper file tagging and ID enrichment.
|
|
|
|
---
|
|
|
|
## simkl_client_id (str)
|
|
|
|
Client ID for SIMKL API integration. SIMKL is used as a metadata source for improved title matching and tagging,
|
|
especially when a TMDB API key is not configured.
|
|
|
|
To obtain a SIMKL Client ID:
|
|
|
|
1. Create an account at <https://simkl.com/>
|
|
2. Go to <https://simkl.com/settings/developer/>
|
|
3. Register a new application to receive your Client ID
|
|
|
|
For example,
|
|
|
|
```yaml
|
|
simkl_client_id: "your_client_id_here"
|
|
```
|
|
|
|
**Note**: While optional, having a SIMKL Client ID improves metadata lookup reliability. SIMKL serves as an alternative or fallback metadata source to TMDB. This is used by the `core/providers/simkl.py` metadata provider.
|
|
|
|
---
|
|
|
|
## ipinfo_api_key (str)
|
|
|
|
Optional API token for [ipinfo.io](https://ipinfo.io). When set, unshackle uses the free authenticated **Lite** endpoint (`https://api.ipinfo.io/lite/me`), which has substantially higher rate limits than the anonymous endpoint and returns richer fields (ASN, organization name, continent). Leave empty to use the anonymous ipinfo.io endpoint, with [ip-api.in](https://ip-api.in) as a final fallback.
|
|
|
|
To obtain an ipinfo.io token:
|
|
|
|
1. Sign up for a free account at <https://ipinfo.io/signup>
|
|
2. Copy the token from your dashboard
|
|
|
|
For example,
|
|
|
|
```yaml
|
|
ipinfo_api_key: "12a3b45cd678ef" # Not a real key
|
|
```
|
|
|
|
**Note**: The token is only ever sent to `api.ipinfo.io` as a per-request `Authorization` header — it is never attached to your session for service requests. Used by `core/utils/ip_info.py` for region detection and proxy verification.
|
|
|
|
---
|
|
|
|
## title_cache_enabled (bool)
|
|
|
|
Enable/disable caching of title metadata to reduce redundant API calls. Default: `true`.
|
|
|
|
---
|
|
|
|
## title_cache_time (int)
|
|
|
|
Cache duration in seconds for title metadata. Default: `1800` (30 minutes).
|
|
|
|
---
|
|
|
|
## title_cache_max_retention (int)
|
|
|
|
Maximum retention time in seconds for serving slightly stale cached title metadata when API calls fail.
|
|
Default: `86400` (24 hours). Effective retention is `min(title_cache_time + grace, title_cache_max_retention)`.
|
|
|
|
---
|
|
|
|
## debug (bool)
|
|
|
|
Enable structured JSON debug logging for troubleshooting and service development. Default: `false`.
|
|
|
|
When enabled (via config or the `--debug` CLI flag):
|
|
- Creates JSON Lines (`.jsonl`) log files with complete debugging context
|
|
- Logs: session info, CLI params, service config, CDM details, authentication, titles, tracks metadata,
|
|
DRM operations, vault queries, errors with stack traces
|
|
- File location: `logs/unshackle_debug_{service}_{timestamp}.jsonl`
|
|
|
|
---
|
|
|
|
## debug_keys (bool)
|
|
|
|
Log decryption keys in debug logs. Default: `false`.
|
|
|
|
When `true`, actual content encryption keys (CEKs) are included in debug log output. Useful for
|
|
debugging key retrieval and decryption issues.
|
|
|
|
**Security note:** Passwords, tokens, cookies, and session tokens are always redacted regardless
|
|
of this setting. Only content keys (`content_key`, `key` fields) are affected. Key IDs (`kid`),
|
|
key counts, and other metadata are always logged.
|
|
|
|
---
|