unshackle/docs/ADVANCED_CONFIG.md

# Advanced & System Configuration

This document covers advanced features, debugging, and system-level configuration options.

## serve (dict)

Configuration for the integrated server that provides CDM endpoints (Widevine/PlayReady) and a REST API for remote downloading.

Start the server with:

```bash
unshackle serve                          # Default: localhost:8786
unshackle serve -h 0.0.0.0 -p 8888      # Listen on all interfaces
unshackle serve --no-key                 # Disable authentication
unshackle serve --api-only               # REST API only, no CDM endpoints
unshackle serve --remote-only            # Only expose remote service session endpoints
```

### CLI Options

| Option | Default | Description |
| --- | --- | --- |
| `-h, --host` | `127.0.0.1` | Host to serve from |
| `-p, --port` | `8786` | Port to serve from |
| `--caddy` | `false` | Also serve with Caddy reverse-proxy for HTTPS |
| `--api-only` | `false` | Serve only the REST API, disable CDM endpoints |
| `--no-widevine` | `false` | Disable Widevine CDM endpoints |
| `--no-playready` | `false` | Disable PlayReady CDM endpoints |
| `--no-key` | `false` | Disable API key authentication (allows all requests) |
| `--debug-api` | `false` | Include tracebacks and stderr in API error responses |
| `--debug` | `false` | Enable debug logging for API operations |
| `--remote-only` | `false` | Only expose remote service session endpoints (health, services, search, session) |

### Configuration

- `api_secret` - Secret key for REST API authentication. Required unless `--no-key` is used. All API requests must include this key via the `X-Secret-Key` header.
- `compression_level` - Compression level for API payloads (manifests, cache, cookies). `0`=off, `1`=fast, `6`=balanced, `9`=max. Default: `1`.
- `session_ttl` - Session inactivity timeout in seconds. Each request resets the timer. Default: `300`.
- `max_sessions` - Maximum concurrent sessions before the oldest is evicted. Default: `100`.
- `services` - Optional global service allowlist. Only these service tags are exposed. If omitted, all services are available.
- `devices` - List of Widevine device files (.wvd). If not specified, auto-populated from the WVDs directory.
- `playready_devices` - List of PlayReady device files (.prd). If not specified, auto-populated from the PRDs directory.
- `users` - Dictionary mapping user secret keys to their access configuration:
  - `devices` - List of Widevine devices this user can access
  - `playready_devices` - List of PlayReady devices this user can access
  - `username` - Internal logging name for the user (not visible to users)
  - `services` - Optional per-user service allowlist. Effective access is the intersection of global and per-user allowlists.

#### Server-side `dl` defaults

Any key accepted by `/api/download` (see `docs/API.md`) can also be declared directly under `serve:` and the REST API will treat it as a default. Per-request bodies still win. Use this to raise concurrency, force `best_available`, etc. without each client repeating the values:

```yaml
serve:
  api_secret: "..."
  users: { ... }
  downloads: 4              # parallel tracks per job
  workers: 16               # threads per track
  best_available: true
  no_proxy_download: false
```

Layering: built-in defaults < `serve.*` overrides < service-specific defaults < request body.

For example,

```yaml
serve:
  api_secret: "your-secret-key-here"
  compression_level: 1
  session_ttl: 300
  max_sessions: 100
  # services:           # global allowlist (optional)
  #   - EXAMPLE1
  #   - EXAMPLE2
  users:
    secret_key_for_jane: # 32bit hex recommended, case-sensitive
      devices: # list of allowed Widevine devices for this user
        - generic_nexus_4464_l3
      playready_devices: # list of allowed PlayReady devices for this user
        - my_playready_device
      username: jane # only for internal logging, users will not see this name
      # services:        # per-user allowlist (optional)
      #   - EXAMPLE1
    secret_key_for_james:
      devices:
        - generic_nexus_4464_l3
      username: james
  # devices can be manually specified by path if you don't want to add it to
  # unshackle's WVDs directory for whatever reason
  # devices:
  #   - 'C:\Users\john\Devices\test_devices_001.wvd'
  # playready_devices:
  #   - '/path/to/device.prd'
```

### REST API

When the server is running, interactive API documentation is available at:

- **Swagger UI**: `http://localhost:8786/api/docs/`

See [API.md](API.md) for full REST API documentation with endpoints, parameters, and examples.

---

## max_concurrent_downloads (int)

Maximum number of `/api/download` jobs the serve queue manager will execute in parallel. Each job runs the full `dl` pipeline (authenticate, fetch tracks, decrypt, mux) in its own worker subprocess. This is independent of `serve.downloads`, which controls parallel tracks **inside** a single job. Default: `2`.

```yaml
max_concurrent_downloads: 4
```

---

## download_job_retention_hours (int)

How long completed, failed, or cancelled download jobs remain queryable via `/api/download/jobs/{job_id}` before the periodic cleanup loop drops them. Default: `24`.

```yaml
download_job_retention_hours: 48
```

---

## debug (bool)

Enables comprehensive debug logging. Default: `false`

When enabled (either via config or the `-d`/`--debug` CLI flag):
- Sets console log level to DEBUG for verbose output
- Creates JSON Lines (`.jsonl`) debug log files with structured logging
- Logs detailed information about sessions, service configuration, DRM operations, and errors with full stack traces

For example,

```yaml
debug: true
```

---

## debug_keys (bool)

Controls whether actual decryption keys (CEKs) are included in debug logs. Default: `false`

When enabled:
- Content encryption keys are logged in debug output
- Only affects `content_key` and `key` fields (the actual CEKs)
- Key metadata (`kid`, `keys_count`, `key_id`) is always logged regardless of this setting
- Passwords, tokens, cookies, and session tokens remain redacted even when enabled

For example,

```yaml
debug_keys: true
```

---

## debug_requests (bool)

Controls whether HTTP-library logs are shown during `--debug` sessions. Default: `false`

When `--debug` is active and this is `false`, unshackle silences the noisy per-request logs emitted by `urllib3`, `requests`, `rnet`, `httpx`, and related libraries (e.g. `GET ...seg-001.m4s 200`) so that unshackle's own structured DEBUG output stays readable. Set to `true` to see every individual HTTP request, including per-segment downloads.

Has no effect when `--debug` is not active.

```yaml
debug_requests: true
```

---

## set_terminal_bg (bool)

Controls whether unshackle applies its theme background color to the terminal. Default: `false`

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 `true` if the banner or colored output looks off on your terminal.

```yaml
set_terminal_bg: true
```

---

## update_checks (bool)

Check for updates from the GitHub repository on startup. Default: `true`.

---

## update_check_interval (int)

How often to check for updates, in hours. Default: `24`.

---

## title_cache_enabled (bool)

Enable or disable title metadata caching globally. Default: `true`.

---

## title_cache_time (int)

Title cache duration in seconds. Default: `1800` (30 minutes).

---

## title_cache_max_retention (int)

Maximum cache retention in seconds, used as fallback when the upstream API fails. Default: `86400` (24 hours).

---

## unicode_filenames (bool)

When `false`, replaces non-ASCII characters in output filenames with ASCII equivalents. Default: `false`.

---

## ipinfo_api_key (str)

Optional ipinfo.io token. When set, unshackle uses the ipinfo.io Lite endpoint for IP/geolocation lookups instead of the unauthenticated fallback.

---

## tmdb_api_key (str)

Optional TMDB API key, used for metadata enrichment and IMDb/TMDb tagging.

---

## simkl_client_id (str)

Optional Simkl client ID for metadata lookups.

---

## decrypt_labs_api_key (str)

Optional Decrypt Labs API key, used by services that integrate with the service.

---