docs: add MkDocs Material documentation site

2026-11-12 12:05:07 +00:00 · 2026-06-30 10:28:48 -06:00
parent 03bcfc0c45
commit ecbcdff314
19 changed files with 1047 additions and 908 deletions
@@ -0,0 +1,64 @@
+# Client Configuration: `remote_services`
+
+`remote_services` is a top-level block in `unshackle.yaml` on the **client** machine. It tells `dl` how to reach a remote `unshackle serve` instance instead of running service code locally. The client handles track selection, download, decrypt, and mux; the server handles auth, manifest parsing, and (optionally) DRM licensing.
+
+## CLI flags
+
+| Flag | Description |
+| --- | --- |
+| `--remote` | Use a remote server instead of local service code. Reads `remote_services` from config. |
+| `--server <name>` | Select a named server when multiple are configured. If only one entry exists it is picked automatically. |
+
+```bash
+unshackle dl --remote EXAMPLE1 "https://example.com/show/abc123"
+unshackle dl --remote --server us-server EXAMPLE1 "https://example.com/show/abc123"
+```
+
+## Config structure
+
+```yaml
+remote_services:
+  my-server:
+    url: "http://192.168.1.100:8786"   # base URL of the remote serve instance
+    api_key: "your-secret-key-here"    # sent as X-Secret-Key; omit or set "" for --no-key servers
+
+    # server_cdm: the server runs its own CDM and returns KID:KEY pairs (mode: server_cdm).
+    # false (default): client runs its own CDM; license challenges are proxied through the server.
+    server_cdm: false
+
+    # Per-service overrides applied on the client side after the remote session is set up.
+    # Supported keys: decryption, downloader, cdm (and any free-form service config keys).
+    services:
+      EXAMPLE1:
+        decryption: mp4decrypt   # override decryption tool for this service (shaka or mp4decrypt)
+```
+
+**`server_cdm`** — when `false` (default) the client builds CDM challenges locally and calls `POST /api/session/{id}/license` with `mode: "proxy"`; the server forwards the challenge to the service's license endpoint and returns raw license bytes. When `true` the client skips local CDM setup and calls with `mode: "server_cdm"`; the server performs the full CDM flow and returns `{ "keys": { "<KID>": "<KEY>" } }`. The server-side user key must have a matching device configured (`devices` / `playready_devices`) for `server_cdm` to work.
+
+## Multiple servers
+
+When more than one server is configured, `--server <name>` is required:
+
+```yaml
+remote_services:
+  us-server:
+    url: "https://us.example.com:8786"
+    api_key: "us-key"
+    server_cdm: true
+    services:
+      EXAMPLE1:
+        decryption: mp4decrypt
+
+  eu-server:
+    url: "https://eu.example.com:8786"
+    api_key: "eu-key"
+    server_cdm: false
+```
+
+```bash
+unshackle dl --remote --server us-server EXAMPLE1 "https://example.com/show/abc123"
+```
+
+## Cache forwarding
+
+On session open the client sends any local `*.json` cache files for the service (tokens, etc.) to the server so it can skip interactive re-auth. On session close the server returns updated cache files; the client writes them back locally so the next remote session can forward them again.