mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-11-18 23:15:08 +00:00
Compare commits
12
Commits
a0feb51d5a
..
5.3.0
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
d4a58267d4 | ||
|
|
96da1ac0b0 | ||
|
|
59f3cb4fbe | ||
|
|
987de239ee | ||
|
|
140c2a4b2f | ||
|
|
2f92ffe1a2 | ||
|
|
ecbcdff314 | ||
|
|
03bcfc0c45 | ||
|
|
efb560f887 | ||
|
|
39f5bc2a9e | ||
|
|
f9ab349e9c | ||
|
|
b6fe0ae4b8 |
@@ -0,0 +1,25 @@
|
||||
name: docs
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [dev]
|
||||
paths:
|
||||
- "docs/**"
|
||||
- "overrides/**"
|
||||
- "mkdocs.yml"
|
||||
- ".github/workflows/docs.yml"
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.x"
|
||||
- run: pip install mkdocs-material
|
||||
- run: mkdocs gh-deploy --force --remote-branch docs
|
||||
@@ -6,6 +6,57 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
|
||||
|
||||
This changelog is automatically generated using [git-cliff](https://git-cliff.org).
|
||||
|
||||
## [5.3.0] - 2026-06-30
|
||||
|
||||
### Features
|
||||
|
||||
- *dl*: Add --merge-video to merge video language variants
|
||||
- Native ExpressVPN HTTPS Proxy Provider
|
||||
- Support Python 3.14 and widen range to 3.11-3.14
|
||||
- Add automatic Firefox cookie and localstorage extraction
|
||||
- *api*: Expose title description, date and cover_url in serialize_title
|
||||
- *api*: Expose active-track segment counts and transfer speed in job progress
|
||||
- *vaults*: Add configurable network timeout for remote vaults
|
||||
- *docs*: Add per-vault network timeout configuration for remote vaults
|
||||
- *services*: Load service plugins from git repos
|
||||
- *proxies*: Add Proton VPN proxy provider
|
||||
- *output*: Support nested directories in folder templates
|
||||
- *proxies*: Add ProtonVPN TV login, drop cookie refresh
|
||||
- *titles*: Add air_date for date-based episode naming
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
- *api*: Annotate routes.py to pass strict mypy
|
||||
- *config*: Match per-service cdm keys case-insensitively
|
||||
- *drm*: Don't switch to a mismatched CDM type during licensing
|
||||
- *env*: Only resolve Path items in directory lists
|
||||
- *output*: Treat `/` and `\` as folder separators on any OS
|
||||
- *console*: Pause active live contexts during terminal input
|
||||
- *dl*: Apply per-service decryption tool override
|
||||
- *hls*: Stream segment merges to avoid OOM on large tracks
|
||||
|
||||
### Documentation
|
||||
|
||||
- Rename to match other docs.
|
||||
- *config*: Make docs/ canonical, slim unshackle-example.yaml to a starter
|
||||
- Add MkDocs Material documentation site
|
||||
- *readme*: Link Docs to docs.unshackle.dev, remove Wiki
|
||||
- Add "Creating a Service" guide
|
||||
- Fix inaccuracies in service-creation guide
|
||||
|
||||
### Performance Improvements
|
||||
|
||||
- *tracks*: Skip redundant DV/VUI bitstream passes
|
||||
- *hls*: Rename single decrypted range instead of re-copying
|
||||
|
||||
### Changes
|
||||
|
||||
- *api*: Remove dead code paths in serve/remote layer
|
||||
- *api*: Dedup handler serializers, validation, and service setup
|
||||
- *api*: Use Event.wait and a shared to_enum helper
|
||||
- *api*: Collapse route registration into single ROUTES table
|
||||
- *api*: Drop dead error codes, lock error contract harness
|
||||
|
||||
## [5.2.0] - 2026-06-16
|
||||
|
||||
### Features
|
||||
|
||||
@@ -10,8 +10,7 @@
|
||||
|
||||
<p align="center">
|
||||
<a href="#install">Install</a> ·
|
||||
<a href="https://github.com/unshackle-dl/unshackle/wiki">Wiki</a> ·
|
||||
<a href="docs/">Docs</a> ·
|
||||
<a href="https://docs.unshackle.dev">Docs</a> ·
|
||||
<a href="https://discord.gg/mHYyPaCbFK">Discord</a>
|
||||
</p>
|
||||
|
||||
|
||||
+8
-867
@@ -4,870 +4,11 @@ The unshackle REST API allows you to control downloads, search services, drive r
|
||||
|
||||
The server is built on **aiohttp** (not FastAPI). Implementation lives in `unshackle/commands/serve.py` and `unshackle/core/api/` (`routes.py`, `handlers.py`, `session_store.py`, `input_bridge.py`, `download_manager.py`, `download_worker.py`).
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Start the server (no authentication)
|
||||
unshackle serve --no-key
|
||||
|
||||
# Start with authentication (api_secret in unshackle.yaml)
|
||||
unshackle serve
|
||||
|
||||
# Serve only the REST API (no pywidevine/pyplayready CDM)
|
||||
unshackle serve --api-only
|
||||
|
||||
# Serve only the remote-dl session endpoints (CORS/Cloudflare friendly)
|
||||
unshackle serve --remote-only
|
||||
|
||||
# Disable just one CDM
|
||||
unshackle serve --no-widevine
|
||||
unshackle serve --no-playready
|
||||
|
||||
# Verbose error responses (tracebacks/stderr in JSON)
|
||||
unshackle serve --debug-api
|
||||
```
|
||||
|
||||
`serve` flags:
|
||||
|
||||
| Flag | Description |
|
||||
| --- | --- |
|
||||
| `-h, --host` | Bind host (default `127.0.0.1`) |
|
||||
| `-p, --port` | Bind port (default `8786`) |
|
||||
| `--caddy` | Also launch Caddy using `Caddyfile` next to the unshackle config |
|
||||
| `--api-only` | REST API only; skip the bundled pywidevine/pyplayready CDM endpoints |
|
||||
| `--no-widevine` | Disable Widevine CDM endpoints |
|
||||
| `--no-playready` | Disable PlayReady CDM endpoints |
|
||||
| `--no-key` | Disable API key authentication entirely |
|
||||
| `--debug-api` | Include tracebacks/stderr in error responses |
|
||||
| `--debug` | Enable DEBUG-level logging for API operations |
|
||||
| `--remote-only` | Expose only `/api/health`, `/api/services`, `/api/search`, and `/api/session/*` (implies `--api-only`) |
|
||||
|
||||
## Authentication
|
||||
|
||||
When `api_secret` is set in `unshackle.yaml`, all API requests require the **`X-Secret-Key`** header. There is no query-parameter fallback. `/api/health` is always reachable without authentication. `--no-key` disables auth entirely (not recommended for public-facing servers).
|
||||
|
||||
```yaml
|
||||
# unshackle.yaml
|
||||
serve:
|
||||
api_secret: "your-master-secret" # falls back to global users map below
|
||||
remote_only: false # also toggleable via --remote-only
|
||||
services: ["EXAMPLE1", "EXAMPLE2"] # optional global service allowlist
|
||||
users:
|
||||
user-secret-1:
|
||||
username: alice
|
||||
devices: ["my_widevine_l3"] # Widevine WVD names this user may use
|
||||
playready_devices: ["my_pr_sl2000"] # PlayReady PRD names; defaults to [] (no access)
|
||||
services: ["EXAMPLE1"] # optional per-user allowlist (intersected with global)
|
||||
user-secret-2:
|
||||
username: bob
|
||||
devices: []
|
||||
playready_devices: []
|
||||
```
|
||||
|
||||
### Service allowlists
|
||||
|
||||
`config.serve.services` is the global allowlist; `users.<key>.services` further narrows it per key. The effective set is the intersection. Endpoints affected: `/api/services`, `/api/search`, `/api/list-titles`, `/api/list-tracks`, `/api/download`, and all `/api/session/*` routes.
|
||||
|
||||
### CDM access (server-side decryption)
|
||||
|
||||
There is no separate "tier" flag. Whether the server can return KID:KEY for a session-mode download depends solely on the device lists configured for the calling user key:
|
||||
|
||||
- Empty `devices` and `playready_devices` -> server can only proxy CDM challenges; the client must run its own CDM and parse the license.
|
||||
- Populated lists -> the client may set `mode: "server_cdm"` on `/api/session/{id}/license` and receive `{ "keys": { "<track_id>": { "<KID>": "<KEY>" } } }` instead of raw license bytes.
|
||||
|
||||
Per-service CDM type can be pinned via `config.cdm` (`widevine`/`playready`) or per-service `cdm_type`; otherwise the server picks the type the user has devices for.
|
||||
|
||||
### Server-side `dl` defaults
|
||||
|
||||
Any flag accepted by `/api/download` (see the table below) can be declared under `serve:` in `unshackle.yaml` and the API will apply it as a default. Request-body values still win. Useful for raising concurrency without changing every client call:
|
||||
|
||||
```yaml
|
||||
serve:
|
||||
api_secret: "..."
|
||||
users: { ... }
|
||||
downloads: 4 # parallel tracks per download job
|
||||
workers: 16 # threads per track segment fetch
|
||||
best_available: true
|
||||
no_proxy_download: false
|
||||
```
|
||||
|
||||
Layering order: built-in defaults < `serve.*` overrides < service-specific click defaults < request body.
|
||||
|
||||
### Per-request override gates
|
||||
|
||||
Two security gates under `serve:` guard capabilities that `/api/download` clients can request. Both default OFF; an unset or `false` value causes the server to reject the request with `403 FORBIDDEN`.
|
||||
|
||||
**`cdm_overrides`** — a `/api/download` job body may include a `cdm` field to select a specific server-side device. When this gate is off, every such request is rejected. Set to `true` to allow any device the server has, or to a list of device names to restrict to an explicit subset:
|
||||
|
||||
```yaml
|
||||
serve:
|
||||
# Allow any server-side device:
|
||||
cdm_overrides: true
|
||||
|
||||
# Or restrict to specific devices:
|
||||
cdm_overrides:
|
||||
- generic_nexus_4464_l3
|
||||
```
|
||||
|
||||
**`allow_job_credentials`** — a `/api/download` job body may include a `credential` (single) or `credentials` (map) field to authenticate the job with client-supplied secrets instead of the server's configured credentials. When this gate is off, any job containing either field is rejected. Each distinct credential gets its own isolated token cache on the server. Set to `true` to allow:
|
||||
|
||||
```yaml
|
||||
serve:
|
||||
allow_job_credentials: true
|
||||
```
|
||||
|
||||
Both gates are independent and can be combined. A typical locked-down deployment leaves both unset; a trusted single-client deployment might enable both.
|
||||
|
||||
---
|
||||
|
||||
## Endpoint Map
|
||||
|
||||
Standard endpoints (suppressed in `--remote-only` mode are marked R):
|
||||
|
||||
| Method | Path | R |
|
||||
| --- | --- | :-: |
|
||||
| GET | `/api/health` | ok |
|
||||
| GET | `/api/services` | ok |
|
||||
| POST | `/api/search` | ok |
|
||||
| POST | `/api/list-titles` | hidden |
|
||||
| POST | `/api/list-tracks` | hidden |
|
||||
| POST | `/api/download` | hidden |
|
||||
| GET | `/api/download/jobs` | hidden |
|
||||
| GET | `/api/download/jobs/{job_id}` | hidden |
|
||||
| DELETE | `/api/download/jobs/{job_id}` | hidden |
|
||||
| POST | `/api/session/create` | ok |
|
||||
| GET | `/api/session/{session_id}` | ok |
|
||||
| DELETE | `/api/session/{session_id}` | ok |
|
||||
| GET | `/api/session/{session_id}/titles` | ok |
|
||||
| POST | `/api/session/{session_id}/tracks` | ok |
|
||||
| POST | `/api/session/{session_id}/segments` | ok |
|
||||
| POST | `/api/session/{session_id}/license` | ok |
|
||||
| GET | `/api/session/{session_id}/prompt` | ok |
|
||||
| POST | `/api/session/{session_id}/prompt` | ok |
|
||||
|
||||
CDM endpoints (`/{wvd}/...`, `/playready/{prd}/...`) are exposed unless `--api-only` / `--remote-only` / `--no-widevine` / `--no-playready` is set, and use pywidevine / pyplayready's own auth scheme.
|
||||
|
||||
---
|
||||
|
||||
## Endpoints
|
||||
|
||||
### GET /api/health
|
||||
|
||||
Health check with version and update information. Always reachable without auth.
|
||||
|
||||
```bash
|
||||
curl http://localhost:8786/api/health
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"version": "4.0.0",
|
||||
"update_check": {
|
||||
"update_available": false,
|
||||
"current_version": "4.0.0",
|
||||
"latest_version": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /api/services
|
||||
|
||||
List all available streaming services (filtered by the effective allowlist for the caller).
|
||||
|
||||
```bash
|
||||
curl -H "X-Secret-Key: $KEY" http://localhost:8786/api/services
|
||||
```
|
||||
|
||||
Returns `{"services": [...]}`. Each entry has `tag`, `aliases`, `geofence`, `title_regex`, `url` (from `cli.short_help`), `help` (full docstring), and `cli_params` describing the service-level Click parameters.
|
||||
|
||||
---
|
||||
|
||||
### POST /api/search
|
||||
|
||||
Search for titles from a streaming service.
|
||||
|
||||
**Required parameters:**
|
||||
| Parameter | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `service` | string | Service tag |
|
||||
| `query` | string | Search query |
|
||||
|
||||
**Optional parameters:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `profile` | string | `null` | Profile for credentials/cookies |
|
||||
| `proxy` | string | `null` | Proxy URI or country code |
|
||||
| `no_proxy` | boolean | `false` | Disable all proxy use |
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8786/api/search \
|
||||
-H "X-Secret-Key: $KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"service": "EXAMPLE1", "query": "example show"}'
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"id": "abc123def456",
|
||||
"title": "Example Show",
|
||||
"description": null,
|
||||
"label": "TV Show",
|
||||
"url": "https://example.com/show/abc123def456"
|
||||
}
|
||||
],
|
||||
"count": 1
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### POST /api/list-titles
|
||||
|
||||
Get available titles (seasons/episodes/movies) for a service and title ID. Disabled in `--remote-only` mode.
|
||||
|
||||
**Required parameters:**
|
||||
| Parameter | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `service` | string | Service tag |
|
||||
| `title_id` | string | Title ID or URL |
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8786/api/list-titles \
|
||||
-H "X-Secret-Key: $KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"service": "EXAMPLE1", "title_id": "abc123def456"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### POST /api/list-tracks
|
||||
|
||||
Get video, audio, and subtitle tracks for a title. Disabled in `--remote-only` mode.
|
||||
|
||||
**Required parameters:**
|
||||
| Parameter | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `service` | string | Service tag |
|
||||
| `title_id` | string | Title ID or URL |
|
||||
|
||||
**Optional parameters:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `wanted` | array | all | Episode filter (e.g., `["S01E01"]`) |
|
||||
| `profile` | string | `null` | Profile for credentials/cookies |
|
||||
| `proxy` | string | `null` | Proxy URI or country code |
|
||||
| `no_proxy` | boolean | `false` | Disable all proxy use |
|
||||
|
||||
Returns video, audio, and subtitle tracks with codec, bitrate, resolution, language, and DRM information.
|
||||
|
||||
---
|
||||
|
||||
### POST /api/download
|
||||
|
||||
Start a download job. Returns immediately with a job ID (HTTP 202). Disabled in `--remote-only` mode.
|
||||
|
||||
**Required parameters:**
|
||||
| Parameter | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `service` | string | Service tag |
|
||||
| `title_id` | string | Title ID or URL |
|
||||
|
||||
**Quality and codec parameters:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `quality` | array[int] | best | Resolution(s) (e.g., `[1080, 2160]`) |
|
||||
| `vcodec` | string or array | any | Video codec(s): `H264`, `H265`/`HEVC`, `VP9`, `AV1`, `VC1`, `VP8` |
|
||||
| `acodec` | string or array | any | Audio codec(s): `AAC`, `AC3`, `EC3`, `AC4`, `OPUS`, `FLAC`, `ALAC`, `DTS`, `OGG` |
|
||||
| `vbitrate` | int | highest | Video bitrate in kbps |
|
||||
| `abitrate` | int | highest | Audio bitrate in kbps |
|
||||
| `range` | array[string] | `["SDR"]` | Color range(s): `SDR`, `HDR10`, `HDR10+`, `HLG`, `DV`, `HYBRID` |
|
||||
| `channels` | float | any | Audio channels (e.g., `5.1`, `7.1`) |
|
||||
| `no_atmos` | boolean | `false` | Exclude Dolby Atmos tracks |
|
||||
| `split_audio` | boolean | `null` | Create separate output per audio codec |
|
||||
| `sub_format` | string | `null` | Output subtitle format: `SRT`, `VTT`, `ASS`, `SSA`, `TTML` |
|
||||
|
||||
**Episode selection:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `wanted` | array[string] | all | Episodes (e.g., `["S01E01", "S01E02-S01E05"]`) |
|
||||
| `latest_episode` | boolean | `false` | Download only the most recent episode |
|
||||
|
||||
**Language parameters:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `lang` | array[string] | `["orig"]` | Language for video and audio (`orig` = original) |
|
||||
| `v_lang` | array[string] | `[]` | Language override for video tracks only |
|
||||
| `a_lang` | array[string] | `[]` | Language override for audio tracks only |
|
||||
| `s_lang` | array[string] | `["all"]` | Language for subtitles |
|
||||
| `require_subs` | array[string] | `[]` | Required subtitle languages (skip if missing) |
|
||||
| `forced_subs` | boolean | `false` | Include forced subtitle tracks |
|
||||
| `exact_lang` | boolean | `false` | Exact language matching (no variants) |
|
||||
|
||||
**Track selection:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `video_only` | boolean | `false` | Only download video tracks |
|
||||
| `audio_only` | boolean | `false` | Only download audio tracks |
|
||||
| `subs_only` | boolean | `false` | Only download subtitle tracks |
|
||||
| `chapters_only` | boolean | `false` | Only download chapters |
|
||||
| `no_video` | boolean | `false` | Skip video tracks |
|
||||
| `no_audio` | boolean | `false` | Skip audio tracks |
|
||||
| `no_subs` | boolean | `false` | Skip subtitle tracks |
|
||||
| `no_chapters` | boolean | `false` | Skip chapters |
|
||||
| `audio_description` | boolean | `false` | Include audio description tracks |
|
||||
|
||||
**Output and tagging:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `tag` | string | `null` | Override group tag |
|
||||
| `repack` | boolean | `false` | Add REPACK tag to filename |
|
||||
| `tmdb_id` | int | `null` | Use specific TMDB ID for tagging |
|
||||
| `imdb_id` | string | `null` | Use specific IMDB ID (e.g., `tt1375666`) |
|
||||
| `animeapi_id` | string | `null` | Anime database ID via AnimeAPI (e.g., `mal:12345`) |
|
||||
| `enrich` | boolean | `false` | Override show title and year from external source |
|
||||
| `no_folder` | boolean | `false` | Disable folder creation for TV shows |
|
||||
| `no_source` | boolean | `false` | Remove source tag from filename |
|
||||
| `no_mux` | boolean | `false` | Do not mux tracks into container |
|
||||
| `output_dir` | string | `null` | Override output directory |
|
||||
|
||||
**Download behavior:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `profile` | string | `null` | Profile for credentials/cookies |
|
||||
| `proxy` | string | `null` | Proxy URI or country code |
|
||||
| `no_proxy` | boolean | `false` | Disable all proxy use |
|
||||
| `no_proxy_download` | boolean | `false` | Bypass proxy for segment downloads only. Manifest, license, and auth still use proxy |
|
||||
| `workers` | int | `null` | Max threads per track download |
|
||||
| `downloads` | int | `1` | Concurrent track downloads |
|
||||
| `slow` | boolean or string | `null` | Add randomized delay between titles. `true` = 60-120s, or `"MIN-MAX"` string (e.g., `"20-40"`). Min must be >= 20 |
|
||||
| `best_available` | boolean | `false` | Continue if requested quality unavailable |
|
||||
| `worst` | boolean | `false` | Select the lowest bitrate track within the specified quality. Requires `quality` |
|
||||
| `skip_dl` | boolean | `false` | Skip download, only get decryption keys |
|
||||
| `export` | boolean | `false` | Export manifest, track URLs, keys, and subtitles to JSON in the exports directory |
|
||||
| `cdm_only` | boolean | `null` | Only use CDM (`true`) or only vaults (`false`) |
|
||||
| `no_cache` | boolean | `false` | Bypass title cache |
|
||||
| `reset_cache` | boolean | `false` | Clear title cache before fetching |
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8786/api/download \
|
||||
-H "X-Secret-Key: $KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"service": "EXAMPLE1",
|
||||
"title_id": "abc123def456",
|
||||
"wanted": ["S01E01"],
|
||||
"quality": [1080, 2160],
|
||||
"vcodec": ["H265"],
|
||||
"acodec": ["AAC", "EC3"],
|
||||
"range": ["HDR10", "SDR"],
|
||||
"split_audio": true,
|
||||
"lang": ["en"]
|
||||
}'
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"job_id": "504db959-80b0-446c-a764-7924b761d613",
|
||||
"status": "queued",
|
||||
"created_time": "2026-02-27T18:00:00.000000"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /api/download/jobs
|
||||
|
||||
List all download jobs with optional filtering and sorting. Disabled in `--remote-only` mode.
|
||||
|
||||
**Query parameters:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `status` | string | all | Filter by status: `queued`, `downloading`, `completed`, `failed`, `cancelled` |
|
||||
| `service` | string | all | Filter by service tag |
|
||||
| `sort_by` | string | `created_time` | Sort field: `created_time`, `started_time`, `completed_time`, `progress`, `status`, `service` |
|
||||
| `sort_order` | string | `desc` | Sort order: `asc`, `desc` |
|
||||
|
||||
```bash
|
||||
curl -H "X-Secret-Key: $KEY" "http://localhost:8786/api/download/jobs?status=completed"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /api/download/jobs/{job_id}
|
||||
|
||||
Get detailed information about a specific download job including progress, parameters, and error details.
|
||||
|
||||
```json
|
||||
{
|
||||
"job_id": "504db959-80b0-446c-a764-7924b761d613",
|
||||
"status": "completed",
|
||||
"created_time": "2026-02-27T18:00:00.000000",
|
||||
"service": "EXAMPLE1",
|
||||
"title_id": "abc123def456",
|
||||
"progress": 100.0,
|
||||
"parameters": { },
|
||||
"started_time": "2026-02-27T18:00:01.000000",
|
||||
"completed_time": "2026-02-27T18:00:15.000000",
|
||||
"output_files": [],
|
||||
"error_message": null,
|
||||
"error_details": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### DELETE /api/download/jobs/{job_id}
|
||||
|
||||
Cancel a queued or running download job. Returns 400 if the job has already terminated.
|
||||
|
||||
---
|
||||
|
||||
## Remote Service Sessions
|
||||
|
||||
These endpoints back the `RemoteService` adapter in `unshackle/core/remote_service.py`. They let a thin `dl` client (or any consumer) authenticate against a service on the server, fetch titles/tracks/manifests, and either proxy CDM challenges or have the server resolve KID:KEY directly. The `dl` command's `RemoteService` adapter replaces the old `remote_dl` command. These endpoints are the only `/api/*` routes available in `--remote-only` mode (in addition to `health`, `services`, and `search`).
|
||||
|
||||
### POST /api/session/create
|
||||
|
||||
Authenticate against a service and open a session. Body fields:
|
||||
|
||||
| Field | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `service` | string | Service tag (required) |
|
||||
| `title_id` | string | Title ID/URL (required) |
|
||||
| `credentials` | object | Auth credentials forwarded to `Service.authenticate` |
|
||||
| `cookies` | string | Cookie blob (Netscape or JSON) |
|
||||
| `proxy` | string | Proxy URI or country code |
|
||||
| `no_proxy` | bool | Force-disable proxies |
|
||||
| `profile` | string | Profile name |
|
||||
| `cache` | object | Optional pre-warmed title cache payload |
|
||||
|
||||
If the service requires interactive input during authentication, poll `GET /api/session/{id}/prompt` and submit responses via `POST /api/session/{id}/prompt` until status is `authenticated`.
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"service": "EXAMPLE1",
|
||||
"title_id": "abc123def456",
|
||||
"credentials": {"username": "alice", "password": "hunter2"},
|
||||
"cookies": "# Netscape HTTP Cookie File\n...",
|
||||
"proxy": "us",
|
||||
"no_proxy": false,
|
||||
"profile": "default",
|
||||
"cache": {}
|
||||
}
|
||||
```
|
||||
|
||||
**Response (202-style; auth runs asynchronously):**
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "f1c4a8b2-9c7e-4d2a-bf91-2d3e4f5a6b7c",
|
||||
"service": "EXAMPLE1",
|
||||
"status": "authenticating"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/session/{session_id}
|
||||
|
||||
Returns session metadata. 404 if expired or unknown.
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "f1c4a8b2-9c7e-4d2a-bf91-2d3e4f5a6b7c",
|
||||
"service": "EXAMPLE1",
|
||||
"valid": true,
|
||||
"expires_in": 3600,
|
||||
"track_count": 0,
|
||||
"title_count": 0
|
||||
}
|
||||
```
|
||||
|
||||
### DELETE /api/session/{session_id}
|
||||
|
||||
Tears down the session, cancels any pending prompts, and returns any updated per-session cache files (base64-encoded, zlib-compressed) so the client can re-warm next time.
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"cache": {
|
||||
"tokens": "eJzLSM3JyVcozy/KSVGo5AIAGgQEvQ=="
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/session/{session_id}/titles
|
||||
|
||||
Returns the resolved titles list.
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "f1c4a8b2-9c7e-4d2a-bf91-2d3e4f5a6b7c",
|
||||
"titles": [
|
||||
{
|
||||
"type": "episode",
|
||||
"name": "Pilot",
|
||||
"series_title": "Example Show",
|
||||
"season": 1,
|
||||
"number": 1,
|
||||
"year": 2024,
|
||||
"id": "ep-0001",
|
||||
"language": "en"
|
||||
},
|
||||
{
|
||||
"type": "movie",
|
||||
"name": "Example Movie",
|
||||
"year": 2024,
|
||||
"id": "mov-0001",
|
||||
"language": "en"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/session/{session_id}/tracks
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{"title_id": "ep-0001"}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"title": {
|
||||
"type": "episode",
|
||||
"name": "Pilot",
|
||||
"series_title": "Example Show",
|
||||
"season": 1,
|
||||
"number": 1,
|
||||
"year": 2024,
|
||||
"id": "ep-0001",
|
||||
"language": "en"
|
||||
},
|
||||
"video": [
|
||||
{
|
||||
"id": "v-1080p-h264",
|
||||
"codec": "H264",
|
||||
"codec_display": "H.264",
|
||||
"bitrate": 6000,
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"resolution": "1920x1080",
|
||||
"fps": "23.976",
|
||||
"range": "SDR",
|
||||
"range_display": "SDR",
|
||||
"language": "en",
|
||||
"drm": [
|
||||
{
|
||||
"type": "widevine",
|
||||
"pssh": "AAAAW3Bzc2gAAAAA7e+...",
|
||||
"kids": ["abcdef0123456789abcdef0123456789"],
|
||||
"license_url": "https://license.example.com/widevine"
|
||||
}
|
||||
],
|
||||
"descriptor": "DASH",
|
||||
"url": "https://cdn.example.com/manifest.mpd"
|
||||
}
|
||||
],
|
||||
"audio": [
|
||||
{
|
||||
"id": "a-en-eac3",
|
||||
"codec": "EC3",
|
||||
"codec_display": "Dolby Digital Plus",
|
||||
"bitrate": 640,
|
||||
"channels": "5.1",
|
||||
"language": "en",
|
||||
"atmos": false,
|
||||
"descriptive": false,
|
||||
"drm": null,
|
||||
"descriptor": "DASH",
|
||||
"url": "https://cdn.example.com/manifest.mpd"
|
||||
}
|
||||
],
|
||||
"subtitles": [
|
||||
{
|
||||
"id": "s-en-vtt",
|
||||
"codec": "WebVTT",
|
||||
"language": "en",
|
||||
"forced": false,
|
||||
"sdh": false,
|
||||
"cc": false,
|
||||
"descriptor": "DASH",
|
||||
"url": "https://cdn.example.com/subs/en.vtt"
|
||||
}
|
||||
],
|
||||
"chapters": [
|
||||
{"timestamp": "00:00:00.000", "name": "Chapter 1"}
|
||||
],
|
||||
"attachments": [],
|
||||
"manifests": [
|
||||
{
|
||||
"type": "dash",
|
||||
"url": "https://cdn.example.com/manifest.mpd",
|
||||
"data": "eJzNVk1v2zAM/Ss..."
|
||||
}
|
||||
],
|
||||
"session_headers": {
|
||||
"User-Agent": "Mozilla/5.0 ..."
|
||||
},
|
||||
"session_cookies": {
|
||||
"session": "abc123"
|
||||
},
|
||||
"server_cdm_type": "widevine"
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/session/{session_id}/segments
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{"track_ids": ["v-1080p-h264", "a-en-eac3"]}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"tracks": {
|
||||
"v-1080p-h264": {
|
||||
"descriptor": "DASH",
|
||||
"url": "https://cdn.example.com/manifest.mpd",
|
||||
"drm": [
|
||||
{
|
||||
"type": "widevine",
|
||||
"pssh": "AAAAW3Bzc2gAAAAA7e+...",
|
||||
"kids": ["abcdef0123456789abcdef0123456789"],
|
||||
"license_url": "https://license.example.com/widevine"
|
||||
}
|
||||
],
|
||||
"headers": {"User-Agent": "Mozilla/5.0 ..."},
|
||||
"cookies": {"session": "abc123"},
|
||||
"data": {}
|
||||
},
|
||||
"a-en-eac3": {
|
||||
"descriptor": "DASH",
|
||||
"url": "https://cdn.example.com/manifest.mpd",
|
||||
"drm": null,
|
||||
"headers": {"User-Agent": "Mozilla/5.0 ..."},
|
||||
"cookies": {"session": "abc123"},
|
||||
"data": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/session/{session_id}/license
|
||||
|
||||
Two modes, selected by the `mode` field.
|
||||
|
||||
**`mode: "proxy"` (default)** -- forward a client-built CDM challenge to the service's license endpoint.
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "proxy",
|
||||
"track_id": "v-1080p-h264",
|
||||
"challenge": "CAESxQEK...",
|
||||
"drm_type": "widevine",
|
||||
"pssh": "AAAAW3Bzc2gAAAAA7e+..."
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{"license": "CAIS3wIK..."}
|
||||
```
|
||||
|
||||
**`mode: "server_cdm"`** -- the server uses its own CDM to license the track and extract keys. Single-track form takes `track_id`; batch form takes `track_ids`. Requires the calling user key to have a matching device (`devices` for Widevine, `playready_devices` for PlayReady) in `unshackle.yaml`.
|
||||
|
||||
Request (batch):
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "server_cdm",
|
||||
"track_ids": ["v-1080p-h264", "a-en-eac3"],
|
||||
"drm_type": "widevine"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"keys": {
|
||||
"v-1080p-h264": {
|
||||
"abcdef0123456789abcdef0123456789": "00112233445566778899aabbccddeeff"
|
||||
},
|
||||
"a-en-eac3": {
|
||||
"abcdef0123456789abcdef0123456789": "00112233445566778899aabbccddeeff"
|
||||
}
|
||||
},
|
||||
"drm_type": "widevine"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/session/{session_id}/prompt
|
||||
|
||||
Polled by the client during interactive authentication (OTP, PIN, device codes). Backed by the `InputBridge` in `unshackle/core/api/input_bridge.py`; `Service.request_input()` blocks server-side until the client posts a response.
|
||||
|
||||
Pending input:
|
||||
|
||||
```json
|
||||
{"status": "pending_input", "prompt": "Enter OTP code: "}
|
||||
```
|
||||
|
||||
Other states:
|
||||
|
||||
```json
|
||||
{"status": "authenticating"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"status": "authenticated"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"status": "failed", "error": "Invalid credentials"}
|
||||
```
|
||||
|
||||
### POST /api/session/{session_id}/prompt
|
||||
|
||||
Unblocks the server-side `request_input()` call.
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
{"response": "123456"}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{"status": "accepted"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints return consistent error responses:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"error_code": "INVALID_PARAMETERS",
|
||||
"message": "Invalid vcodec: XYZ. Must be one of: H264, H265, VP9, AV1, VC1, VP8",
|
||||
"timestamp": "2026-02-27T18:00:00.000000+00:00",
|
||||
"details": { }
|
||||
}
|
||||
```
|
||||
|
||||
Common error codes:
|
||||
|
||||
- `INVALID_INPUT` -- malformed request body
|
||||
- `INVALID_PARAMETERS` -- invalid parameter values
|
||||
- `MISSING_SERVICE` -- service tag not provided
|
||||
- `INVALID_SERVICE` -- service not found or not in the caller's allowlist
|
||||
- `SERVICE_ERROR` -- service initialization or runtime error
|
||||
- `AUTH_FAILED` -- authentication failure
|
||||
- `NOT_FOUND` / `TRACK_NOT_FOUND` / session not found -- job/session/track/title missing
|
||||
- `INTERNAL_ERROR` -- unexpected server error
|
||||
|
||||
When `--debug-api` is enabled, error responses include additional `debug_info` with tracebacks and stderr output.
|
||||
|
||||
Authentication errors from the auth middleware are returned as `{"status": 401, "message": "..."}` (not the standard error envelope).
|
||||
|
||||
---
|
||||
|
||||
## Download Job Lifecycle
|
||||
|
||||
```
|
||||
queued -> downloading -> completed
|
||||
\-> failed
|
||||
queued -> cancelled
|
||||
downloading -> cancelled
|
||||
```
|
||||
|
||||
Jobs are retained for 24 hours after completion (override via top-level `download_job_retention_hours` in `unshackle.yaml`). The server runs up to 2 concurrent download jobs by default; override via top-level `max_concurrent_downloads`. This is independent of `serve.downloads`, which controls parallel tracks **within** a single job.
|
||||
|
||||
Remote sessions are managed by `SessionStore` (`unshackle/core/api/session_store.py`); idle sessions and their `InputBridge` instances are cleaned up by a background loop started/stopped with the app lifecycle.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
- [Quick Start](api/quick-start.md)
|
||||
- [Authentication](api/authentication.md)
|
||||
- [Endpoint Map](api/endpoint-map.md)
|
||||
- [Endpoints](api/endpoints.md)
|
||||
- [Remote Service Sessions](api/remote-service-sessions.md)
|
||||
- [Error Responses](api/error-responses.md)
|
||||
- [Download Job Lifecycle](api/download-job-lifecycle.md)
|
||||
- [Client Configuration: `remote_services`](api/client-configuration.md)
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
docs.unshackle.dev
|
||||
@@ -0,0 +1,488 @@
|
||||
# Creating a Service
|
||||
|
||||
This guide walks through writing a new service adapter, section by section, using the bundled
|
||||
reference implementation at
|
||||
[`unshackle/services/EXAMPLE/__init__.py`](https://github.com/unshackle-dl/unshackle/blob/main/unshackle/services/EXAMPLE/__init__.py)
|
||||
as the canonical example. `EXAMPLE` is deliberately exhaustive - it shows every framework feature
|
||||
in one file so you have one place to copy from. It does not run against a real API.
|
||||
|
||||
## File layout
|
||||
|
||||
A service is a directory under `unshackle/services/` named by its **tag** (the short code used on
|
||||
the CLI - `EXAMPLE`, or its aliases `EX`/`DOMAIN`, in the reference service). The directory needs:
|
||||
|
||||
```
|
||||
unshackle/services/TAG/
|
||||
├── __init__.py # required - the Service subclass
|
||||
└── config.yaml # optional - endpoints, headers, client profiles
|
||||
```
|
||||
|
||||
The class inside `__init__.py` **must** have the same name as the directory (`class TAG(Service):`
|
||||
in `services/TAG/__init__.py`). `unshackle/core/services.py` discovers services by globbing
|
||||
`services/*/__init__.py` and looking up a class named after the directory; a mismatch raises
|
||||
`no class named '<TAG>' found ... the class name must match the directory name` at load time, so
|
||||
the failure is loud, not silent.
|
||||
|
||||
## Lifecycle at a glance
|
||||
|
||||
Before the method-by-method breakdown, here's the order the framework calls your service during a
|
||||
download - your methods are the hooks, the framework drives the loop:
|
||||
|
||||
```
|
||||
unshackle dl TAG <title>
|
||||
└─ cli(ctx, title=...) → constructs TAG(ctx, ...)
|
||||
└─ __init__ → super().__init__(ctx) builds session/cache/track_request, resolves geofence proxy
|
||||
1. authenticate(cookies, credential) login / token exchange (always called; base just loads cookies/credential)
|
||||
2. get_titles() → Movies / Series / Album (wrapped by get_titles_cached + title_map)
|
||||
· framework applies episode/season filters
|
||||
3. per title:
|
||||
a. get_tracks(title) → Tracks (parse manifest, post-process, store license data)
|
||||
b. get_chapters(title) → Chapters
|
||||
c. framework selects tracks resolution / range / codec / language (best_available softens misses)
|
||||
d. per track: download → license callback → decrypt → repackage → mux → move to final filename
|
||||
```
|
||||
|
||||
Two things follow from this order:
|
||||
|
||||
- **`get_tracks()` runs before any track selection**, so it must return *everything*; the framework
|
||||
filters afterward in step (c).
|
||||
- **The license callbacks** (`get_widevine_license` etc.) fire in step (d), long after
|
||||
`get_tracks()` returned - they only receive `challenge`, `title`, and `track` (nothing else from
|
||||
`get_tracks()`), so anything they need (license URL, session token) must be stashed during
|
||||
`get_tracks()`.
|
||||
|
||||
## Class docstring and class variables
|
||||
|
||||
```python
|
||||
class EXAMPLE(Service):
|
||||
"""
|
||||
Reference service for domain.com - ...
|
||||
|
||||
Version: 2.0.0
|
||||
Author: sp4rk.y
|
||||
Date: 2026-06-28
|
||||
Authorization: Cookies + Credentials
|
||||
Geofence: US, UK
|
||||
Robustness:
|
||||
Widevine:
|
||||
L1: 2160p, HDR10, HDR10+, DV
|
||||
L3: 1080p, SDR
|
||||
PlayReady:
|
||||
SL3000: 2160p
|
||||
ClearKey: 1080p (DRM-free fallback)
|
||||
|
||||
Tips:
|
||||
- Input may be a full URL or a bare ID/slug
|
||||
"""
|
||||
|
||||
ALIASES = ("EX", "DOMAIN")
|
||||
GEOFENCE = ("US", "UK")
|
||||
TITLE_RE = r"^(?:https?://(?:www\.)?domain\.com/details/)?(?P<title_id>[^/?#]+)"
|
||||
NO_SUBTITLES = False
|
||||
VAULT_TAG = "DIFFERENT_NAME"
|
||||
```
|
||||
|
||||
The docstring **is** the `unshackle dl TAG --help` output, so it follows Click's conventions:
|
||||
|
||||
- Keep `Version`, `Author`, `date`, `Authorization`, `Geofence`, and `Robustness` - they're the fields
|
||||
users and other contributors check first when deciding whether a service still works.
|
||||
|
||||
Class variables, all optional except where noted:
|
||||
|
||||
| Variable | Purpose |
|
||||
|---|---|
|
||||
| `ALIASES: tuple[str, ...]` | Extra CLI tags that resolve to this service, e.g. `dl EX ...` |
|
||||
| `GEOFENCE: tuple[str, ...]` | ISO country codes required; the framework warns/auto-proxies on mismatch |
|
||||
| `TITLE_RE: str` | Regex with named groups (e.g. `(?P<title_id>...)`) used in `get_titles()` to accept either a full URL or a bare ID |
|
||||
| `NO_SUBTITLES: bool` | Convention checked via `hasattr` by `dl.py`, not declared on the base class - set `True` if the service has no subtitle tracks, to skip subtitle handling |
|
||||
| `VAULT_TAG: Optional[str]` | Store/read keys under a different vault namespace than this service's own tag - lets sibling services (e.g. regional variants of the same backend) share one key vault |
|
||||
| `AUTH_METHODS: tuple[str, ...]` | Declares which of `"cookies"`/`"credentials"` the service accepts. Optional - when unset, `unshackle serve`'s `/services` endpoint infers it by inspecting `authenticate()`'s source. Set it explicitly if that inference would guess wrong |
|
||||
|
||||
See [Service Integration & Authentication](SERVICE_CONFIG.md#service-class-conventions) for the
|
||||
full list of `self.*` helpers available once `super().__init__(ctx)` has run.
|
||||
|
||||
## `cli()` - the Click entry point
|
||||
|
||||
```python
|
||||
@staticmethod
|
||||
@click.command(name="EXAMPLE", short_help="https://domain.com", help=__doc__)
|
||||
@click.argument("title", type=str)
|
||||
@click.option("-m", "--movie", is_flag=True, default=False, help="Treat the title as a movie.")
|
||||
@click.option(
|
||||
"-d", "--device",
|
||||
type=click.Choice(["android_tv", "web", "ios"], case_sensitive=False),
|
||||
default="android_tv",
|
||||
help="Client profile block to use from config.yaml.",
|
||||
)
|
||||
@click.pass_context
|
||||
def cli(ctx: click.Context, **kwargs: Any) -> EXAMPLE:
|
||||
return EXAMPLE(ctx, **kwargs)
|
||||
```
|
||||
|
||||
Keep `name="EXAMPLE"` in `@click.command` matching the class/directory name - resolution of
|
||||
`unshackle dl EXAMPLE ...` is actually driven by the directory name matching the class name (see
|
||||
File layout above), but a mismatched `name=` produces confusing `--help`/usage output.
|
||||
`help=__doc__` reuses the class docstring above as the `--help` text. Add `@click.option` entries here for anything a user should be able to toggle per
|
||||
download (device/client profile, movie-vs-series disambiguation, region, etc.) - they arrive as
|
||||
keyword arguments into `__init__`.
|
||||
|
||||
## `__init__()`
|
||||
|
||||
```python
|
||||
def __init__(self, ctx: click.Context, title: str, movie: bool, device: str):
|
||||
self.title = title
|
||||
self.movie = movie
|
||||
self.device = device
|
||||
|
||||
super().__init__(ctx)
|
||||
|
||||
self.cdm = ctx.obj.cdm
|
||||
self.is_playready = is_playready_cdm(self.cdm)
|
||||
self.is_widevine = is_widevine_cdm(self.cdm)
|
||||
|
||||
if self.is_playready:
|
||||
self.device = "playready_tv"
|
||||
elif self.is_widevine:
|
||||
self.log.info(" + Widevine CDM detected")
|
||||
|
||||
# The active -p/--profile, used below to key per-profile token caches.
|
||||
self.profile = (ctx.parent.params.get("profile") if ctx.parent else None) or "default"
|
||||
|
||||
if any(r != Video.Range.SDR for r in self.track_request.ranges):
|
||||
self.track_request.codecs = [Video.Codec.HEVC]
|
||||
|
||||
if self.is_widevine and getattr(self.cdm, "security_level", None) == 3:
|
||||
self.track_request.codecs = [Video.Codec.AVC]
|
||||
self.track_request.ranges = [Video.Range.SDR]
|
||||
|
||||
if self.config is None:
|
||||
raise EnvironmentError("config.yaml is missing for this service.")
|
||||
```
|
||||
|
||||
Order matters here:
|
||||
|
||||
1. Store CLI args **before** `super().__init__(ctx)` only if base-class init needs them; otherwise
|
||||
it doesn't matter, but storing first is the convention every service follows.
|
||||
2. `super().__init__(ctx)` wires up `self.config`, `self.log`, `self.session`, `self.cache`,
|
||||
`self.title_cache`, `self.current_region`, and builds `self.track_request` from the global `dl`
|
||||
flags. Nothing below this line works without it. (`self.request_input` is a base-class method,
|
||||
always available - it isn't assigned here.)
|
||||
3. After that, inspect `ctx.obj.cdm` and classify it with `is_playready_cdm`/`is_widevine_cdm`
|
||||
(`unshackle.core.cdm.detect`) - never hand-roll `isinstance` checks, these helpers also handle
|
||||
remote/wrapper CDMs.
|
||||
4. Read or rewrite `self.track_request` for service-level constraints: e.g. force HEVC when any
|
||||
non-SDR range was requested, or clamp a Widevine L3 box down to AVC/SDR.
|
||||
|
||||
`self.track_request` fields: `codecs: list[Video.Codec]` (empty = no preference),
|
||||
`ranges: list[Video.Range]` (defaults to `[SDR]`), `best_available: bool`. Read codec/range
|
||||
preferences from `self.track_request`, not from `ctx.parent.params` directly - it's the same data,
|
||||
but `track_request` is what `_get_tracks_for_variants()` and the rest of the framework consult.
|
||||
|
||||
## `self.session` and `get_session()`
|
||||
|
||||
`super().__init__(ctx)` sets `self.session = self.get_session()`. The **base** `get_session()` is a
|
||||
plain `requests.Session` with `config.headers` applied and a retry adapter mounted (5 retries,
|
||||
backoff on `429/500/502/503/504`) - it does **not** use rnet/TLS-impersonation by default. If a
|
||||
service needs TLS fingerprinting to get past bot detection, override `get_session()`:
|
||||
|
||||
```python
|
||||
from unshackle.core.session import session
|
||||
|
||||
@staticmethod
|
||||
def get_session() -> RnetSession:
|
||||
return session("Chrome131") # any rnet.Impersonate preset name, e.g. OkHttp4_12, Edge101, Safari18
|
||||
```
|
||||
|
||||
`RnetSession` is a drop-in `requests.Session` replacement (same `.get`/`.post`/cookie jar
|
||||
interface), so nothing else in the service needs to change. For custom SSL cipher requirements
|
||||
instead, mount `unshackle.core.utils.sslciphers.SSLCiphers` on a plain `requests.Session` the same
|
||||
way.
|
||||
|
||||
## `authenticate()`
|
||||
|
||||
```python
|
||||
def authenticate(self, cookies: Optional[CookieJar] = None, credential: Optional[Credential] = None) -> None:
|
||||
super().authenticate(cookies, credential)
|
||||
self.session.headers.update({"user-agent": self.config["client"][self.device]["user_agent"]})
|
||||
|
||||
cache = self.cache.get(f"tokens_{self.device}_{self.profile}")
|
||||
if cache and cache.data.get("expires_in", 0) > int(datetime.now().timestamp()):
|
||||
self.log.info(" + Using cached tokens")
|
||||
elif cache and cache.data.get("refresh_token"):
|
||||
refresh = self.session.post(url=self.config["endpoints"]["refresh"], data=...).json()
|
||||
cache.set(data=refresh, expiration=refresh.get("expires_in"))
|
||||
else:
|
||||
if cookies:
|
||||
... # decode a JWT cookie
|
||||
elif credential:
|
||||
otp = self.request_input("Enter the OTP sent to your device: ")
|
||||
...
|
||||
else:
|
||||
raise EnvironmentError("Service requires either Cookies or Credentials.")
|
||||
token = self.session.post(url=self.config["endpoints"]["login"], data=body).json()
|
||||
cache.set(data=token, expiration=token.get("expires_in"))
|
||||
|
||||
self.token = cache.data["token"]
|
||||
```
|
||||
|
||||
Skip this method entirely for services that need no auth at all. Otherwise:
|
||||
|
||||
- **Always call `super().authenticate(cookies, credential)` first** - it loads the cookie jar into
|
||||
`self.session` and stores `self.credential`.
|
||||
- Cache tokens with `self.cache.get(key)` / `cache.set(data, expiration=seconds)`. Key the cache
|
||||
by whatever varies per session (device, profile, or `credential.sha1`) so multiple profiles
|
||||
don't collide.
|
||||
- Use `self.request_input(prompt)` instead of bare `input()` for anything interactive (OTP, 2FA
|
||||
codes) - locally it prompts via the shared Rich console (`console.input`, so the prompt renders
|
||||
correctly alongside progress/log output), but under `serve` the attached `InputBridge` relays the
|
||||
prompt to the remote client instead of hanging the server.
|
||||
- Raise `EnvironmentError` if auth is required but neither cookies nor a credential were given.
|
||||
- Don't hold onto the raw `Credential` object past this method - store the derived token instead.
|
||||
|
||||
## `search()`
|
||||
|
||||
```python
|
||||
def search(self) -> Generator[SearchResult, None, None]:
|
||||
results = self.session.get(url=self.config["endpoints"]["search"], params={"q": self.title}).json()
|
||||
for result in results["entries"]:
|
||||
yield SearchResult(
|
||||
id_=result["id"],
|
||||
title=result["title"],
|
||||
description=result.get("description"),
|
||||
label="SERIES" if result["programType"] == "series" else result["programType"].upper(),
|
||||
url=result.get("url"),
|
||||
)
|
||||
```
|
||||
|
||||
Optional - implement it to support `unshackle search TAG <query>`. A generator yielding
|
||||
`SearchResult` objects; nothing else consumes its return value, so don't collect to a list first.
|
||||
|
||||
## `get_titles()`
|
||||
|
||||
```python
|
||||
def get_titles(self) -> Titles_T:
|
||||
match = re.match(self.TITLE_RE, self.title)
|
||||
if not match:
|
||||
raise ValueError("Could not parse a title ID - is the URL/ID correct?")
|
||||
title_id = match.group("title_id")
|
||||
|
||||
metadata = self.session.get(url=self.config["endpoints"]["metadata"].format(title_id=title_id)).json()
|
||||
original_lang = Language.find(metadata["languages"][0])
|
||||
|
||||
if self.movie or metadata["programType"] == "movie":
|
||||
return Movies([
|
||||
Movie(
|
||||
id_=metadata["id"],
|
||||
service=self.__class__,
|
||||
name=metadata["title"],
|
||||
year=metadata.get("releaseYear") or None,
|
||||
language=original_lang,
|
||||
data=metadata,
|
||||
)
|
||||
])
|
||||
|
||||
episodes = [...] # flatten seasons into Episode(...) the same way
|
||||
return Series(episodes)
|
||||
```
|
||||
|
||||
Required. Returns `Movies`, `Series`, or (for music) `Album` - never a raw list.
|
||||
|
||||
- Parse `self.title` with `TITLE_RE` first; raise `ValueError` with a clear message if it doesn't
|
||||
match.
|
||||
- `language=` on each `Movie`/`Episode`/`Song` must be the title's **original** recorded language,
|
||||
not the user's preferred language - it's the source of truth `to_tracks()` uses later to flag
|
||||
`is_original_lang` on every track, which drives `-l best/all` selection and the "Original" audio
|
||||
label.
|
||||
- `service=self.__class__`, not `service=self` - a common copy-paste mistake.
|
||||
- Pass the full API response through `data=` on the title. `get_tracks()` and `get_chapters()`
|
||||
read it back as `title.data` - this is the standard way to avoid a second request later.
|
||||
|
||||
## `get_tracks()`
|
||||
|
||||
Two shapes, depending on what the service's API gives you:
|
||||
|
||||
**Pattern A - separate manifest per codec/range.** Use the `_get_tracks_for_variants()` helper:
|
||||
|
||||
```python
|
||||
def get_tracks(self, title: Title_T) -> Tracks:
|
||||
def _fetch_variant(title, codec, range_):
|
||||
vcodec_str = "H265" if codec == Video.Codec.HEVC else "H264"
|
||||
return self._fetch_dash_manifest(title, vcodec=vcodec_str, range_=range_)
|
||||
return self._get_tracks_for_variants(title, _fetch_variant)
|
||||
```
|
||||
|
||||
The helper walks every `codec x range` combination from `self.track_request`, handles `HYBRID`
|
||||
(fetches HDR10 and DV separately and merges them), and - when `--best-available` is set - skips
|
||||
combos the service can't deliver instead of raising.
|
||||
|
||||
**Pattern B - one manifest contains every variant.** Just parse and return; `dl.py` filters by
|
||||
the user's selection:
|
||||
|
||||
```python
|
||||
def get_tracks(self, title: Title_T) -> Tracks:
|
||||
playback = self.session.get(url=self.config["endpoints"]["playback"].format(title_id=title.id)).json()
|
||||
return HLS.from_url(url=playback["manifest_url"], session=self.session).to_tracks(language=title.language)
|
||||
```
|
||||
|
||||
`ISM` (Microsoft Smooth Streaming) follows the same shape as `HLS` here.
|
||||
|
||||
Whichever pattern you use, the manifest fetch is also where you post-process tracks before
|
||||
returning them - see `_fetch_dash_manifest` in `EXAMPLE` for the full set of fixups:
|
||||
|
||||
- **Store DRM/license data** on `self` (e.g. `self.license_data = {...}`) or on `title.data` -
|
||||
`get_widevine_license()` only receives `title` and `track`, not the manifest response, so this
|
||||
is the only place to capture license URLs/tokens.
|
||||
- **Stamp `video.range`** - manifests can't always be trusted to signal range correctly; set it
|
||||
explicitly to what you asked for.
|
||||
- **Flip HDR10 → HDR10+** when the service is known to embed HDR10+ SEI but only labels HDR10 in
|
||||
the manifest - this is a bitstream feature the HLS parser intentionally does not infer.
|
||||
- **Set `video.dv_compatible_bitstream = True`** for HEVC tracks carrying DV RPU NALs in a
|
||||
container that only signals plain HEVC - `DVFixup` then round-trips the bitstream through
|
||||
`dovi_tool` before mux so the output is recognised as Dolby Vision.
|
||||
- **Drop decoy renditions** (e.g. unencrypted "clear" copies some APIs return alongside the real
|
||||
ones).
|
||||
- **Mark descriptive audio** from the manifest's `Role`/label data (`audio.descriptive = True`).
|
||||
- **Set `audio.joc`** when the API tells you a track is Dolby Atmos explicitly (the framework
|
||||
also detects JOC itself from the bitstream).
|
||||
- **Build subtitles by hand** when the manifest's own subtitle list is wrong or incomplete - in
|
||||
that case compute `is_original_lang` yourself with `is_close_match(sub_lang, [title.language])`,
|
||||
the same helper `to_tracks()` uses internally.
|
||||
- **Add cover art** as an `Attachment` if the API provides one.
|
||||
|
||||
```python
|
||||
def get_tracks(self, title: Title_T) -> Tracks:
|
||||
# ... never filter by resolution/codec/language here - return everything,
|
||||
# the framework applies the user's selection after this returns.
|
||||
```
|
||||
|
||||
This is the single most common service bug: filtering inside `get_tracks()`. Don't.
|
||||
|
||||
## `get_chapters()`
|
||||
|
||||
```python
|
||||
def get_chapters(self, title: Title_T) -> Chapters:
|
||||
chapters = []
|
||||
seen = set()
|
||||
for marker in title.data.get("markers", []):
|
||||
ts = marker["start"] # seconds, ms, or "HH:MM:SS.mmm"
|
||||
if ts <= 0 or ts in seen: # skip a marker at 0 and any duplicate timestamp
|
||||
continue
|
||||
seen.add(ts)
|
||||
chapters.append(Chapter(timestamp=ts, name=marker.get("label")))
|
||||
return Chapters(chapters)
|
||||
```
|
||||
|
||||
Return `Chapters()` (or `[]`) if the service has no chapter data - don't skip implementing the
|
||||
method. Timestamps accept float seconds, int milliseconds, or `"HH:MM:SS.mmm"` strings. Prefer
|
||||
descriptive names ("Intro", "End Credits") over generic ones ("Chapter 01").
|
||||
|
||||
**The opening chapter at `00:00:00.000` is created for you - never add your own.** The moment you
|
||||
add the first `Chapter`, `Chapters.add()` injects a `Chapter(0)` at the start if one isn't already
|
||||
present, so every file gets an opening chapter automatically. Two consequences you must handle:
|
||||
|
||||
- **Don't add a "Chapter 1" at timestamp 0 yourself** - it's redundant with the auto-inserted one.
|
||||
- **Guard against duplicate timestamps.** `Chapters.add()` raises `ValueError` if a chapter already
|
||||
exists at that exact timestamp, so a marker the API reports at `0` (an intro/recap that starts at
|
||||
the very beginning) collides with the auto-inserted opening chapter, and two markers at the same
|
||||
time collide with each other. Skip any marker at `0` and de-duplicate timestamps before adding,
|
||||
as the `seen` set above does.
|
||||
|
||||
A `Chapter` with no `name` is valid - it inserts an unnamed chapter break at that timestamp, which
|
||||
is the standard way to close out a named range (e.g. mark the end of an "Intro" so the next chapter
|
||||
boundary lands there).
|
||||
|
||||
## DRM license methods
|
||||
|
||||
```python
|
||||
def get_widevine_service_certificate(self, **_: Any) -> Optional[str]:
|
||||
return self.config.get("certificate") # or None to use the common privacy cert
|
||||
|
||||
def get_widevine_license(self, *, challenge: bytes, title: Title_T, track: AnyTrack) -> Optional[Union[bytes, str]]:
|
||||
license_url = self.license_data.get("url") or self.config["endpoints"].get("widevine_license")
|
||||
response = self.session.post(url=license_url, data=challenge, ...)
|
||||
response.raise_for_status()
|
||||
return response.content
|
||||
|
||||
def get_playready_license(self, *, challenge: bytes, title: Title_T, track: AnyTrack) -> Optional[Union[bytes, str]]:
|
||||
response = self.session.post(url=self.config["endpoints"]["playready_license"], data=challenge)
|
||||
response.raise_for_status()
|
||||
return response.content
|
||||
|
||||
def get_clearkey_license(self, *, challenge: bytes, title: Title_T, track: AnyTrack) -> Optional[Union[bytes, str, dict]]:
|
||||
license_url = self.config["endpoints"].get("clearkey_license")
|
||||
if not license_url:
|
||||
return None # fall back to the manifest-provided Laurl, if any
|
||||
response = self.session.post(url=license_url, data=challenge)
|
||||
response.raise_for_status()
|
||||
return response.json()
|
||||
```
|
||||
|
||||
- `get_widevine_service_certificate()` - return the service's privacy cert string to enable
|
||||
privacy-mode license requests, or `None` to use the common cert.
|
||||
- `get_widevine_license()` - POST `challenge` (raw CDM challenge bytes) to the license endpoint,
|
||||
return the raw license (bytes), or JSON-unwrap it first if the service wraps it
|
||||
(`response.json()["license"]`). `track` is passed in case the service rotates keys per segment
|
||||
and you need its per-segment PSSH.
|
||||
- `get_playready_license()` - same shape as Widevine. If omitted, the base class delegates to
|
||||
`get_widevine_license()`, so only implement it when the service has a genuinely separate
|
||||
PlayReady endpoint.
|
||||
- `get_clearkey_license()` - only for DASH `org.w3.clearkey` (W3C EME). `challenge` is the W3C
|
||||
JSON license request; return the JWK Set as dict, str, or bytes. **Three integration levels,
|
||||
simplest first:**
|
||||
1. Manifest carries a `<Laurl>` - implement nothing; the framework POSTs there itself.
|
||||
2. Custom endpoint/headers - override this method as shown above.
|
||||
3. Obfuscated/bespoke key delivery - fetch and unwrap the key yourself, then pre-populate
|
||||
`drm.content_keys[kid] = key_hex` on the track's `ClearKeyCENC` during `get_tracks()`; the
|
||||
framework skips the license round-trip entirely when every KID is already keyed.
|
||||
- HLS AES-128 ClearKey and fully unencrypted content have no license callback at all - the key
|
||||
comes straight from the manifest or a side endpoint and is attached to the track's DRM object
|
||||
directly.
|
||||
|
||||
## Other extension points
|
||||
|
||||
A handful of base-class hooks aren't exercised by `EXAMPLE` because it has nothing interesting to
|
||||
do in them, but are there when you need them:
|
||||
|
||||
- **Event hooks** - no-ops on the base class, fire during the download pipeline if overridden:
|
||||
`on_segment_downloaded(track, segment: Path)`, `on_track_downloaded(track)`,
|
||||
`on_track_decrypted(track, drm, segment=None)`, `on_track_repacked(track)`,
|
||||
`on_track_multiplex(track)`. Useful for progress reporting or service-specific cleanup tied to
|
||||
pipeline stages.
|
||||
- **`resolve_server_keys(title)`** - not declared on `Service` at all; `dl.py` checks for it with
|
||||
`hasattr` and calls it if present. Use it for services where decryption keys need to be resolved
|
||||
server-side ahead of the normal license flow, separate from the per-track license callbacks.
|
||||
- **`get_titles_cached()` / `apply_title_map()`** - base-class wrappers around your `get_titles()`
|
||||
that add the title-metadata cache and `title_map` config rewriting (see
|
||||
[`title_map`](SERVICE_CONFIG.md#title_map-dict)). `dl.py` calls `get_titles_cached()`, not
|
||||
`get_titles()` directly - implement `get_titles()`, don't override the cached wrapper.
|
||||
|
||||
## `config.yaml`
|
||||
|
||||
```yaml
|
||||
endpoints:
|
||||
base_url: "https://api.example.com"
|
||||
content: "https://api.example.com/content"
|
||||
search: "https://api.example.com/search"
|
||||
license: "https://license.example.com/v1"
|
||||
headers:
|
||||
User-Agent: "..."
|
||||
client:
|
||||
id: "..."
|
||||
device:
|
||||
platform_name: "..."
|
||||
```
|
||||
|
||||
No enforced schema - `self.config` is just whatever YAML you put here, merged with any
|
||||
`services.<TAG>` overrides from the user's `unshackle.yaml` (see
|
||||
[Service Integration & Authentication](SERVICE_CONFIG.md#services-dict)). Conventions:
|
||||
|
||||
- **All URLs live here, never hardcoded in `__init__.py`.** Use `{}` or `{name}` placeholders for
|
||||
dynamic segments and `.format(...)` at the call site.
|
||||
- Treat this file as shared/checked-in - don't put per-user secrets in it. Sensitive,
|
||||
user-specific values (API keys, device IDs) belong in the user's `unshackle.yaml` under
|
||||
`services.<TAG>`, which gets merged into `self.config` at runtime.
|
||||
- `client:`/`device:` blocks are a common idiom for services with multiple device profiles
|
||||
(web/android_tv/ios) - index into them with whatever `-d/--device` option you exposed in `cli()`.
|
||||
|
||||
Use `-d`/`--debug` (before the subcommand) for structured JSONL logging while iterating - see
|
||||
[Structured Debug Logging](DEBUG_LOGGING.md).
|
||||
+34
-20
@@ -136,10 +136,12 @@ remote_cdm:
|
||||
- Support for both Widevine and PlayReady
|
||||
- Multiple security levels (L1, L2, L3, SL2000, SL3000)
|
||||
|
||||
**Note:** The `device_type` field determines whether the CDM operates in PlayReady or Widevine mode.
|
||||
Setting `device_type: PLAYREADY` (or using `device_name: SL2` / `SL3`) activates PlayReady mode.
|
||||
The `security_level` field is auto-computed from `device_name` when not specified (e.g., SL2 defaults
|
||||
to 2000, SL3 to 3000, and Widevine devices default to 3). You can override these if needed.
|
||||
!!! note
|
||||
|
||||
The `device_type` field determines whether the CDM operates in PlayReady or Widevine mode.
|
||||
Setting `device_type: PLAYREADY` (or using `device_name: SL2` / `SL3`) activates PlayReady mode.
|
||||
The `security_level` field is auto-computed from `device_name` when not specified (e.g., SL2 defaults
|
||||
to 2000, SL3 to 3000, and Widevine devices default to 3). You can override these if needed.
|
||||
|
||||
### Custom API Remote CDM
|
||||
|
||||
@@ -310,9 +312,11 @@ remote_cdm:
|
||||
secret: your-api-secret-key # X-Secret-Key sent to the serve instance
|
||||
```
|
||||
|
||||
**Note:** The `/playready` path suffix in `host` is required — `pyplayready.RemoteCdm`
|
||||
appends its own endpoint paths on top of this base, so omitting the suffix will result
|
||||
in 404 errors.
|
||||
!!! note
|
||||
|
||||
The `/playready` path suffix in `host` is required — `pyplayready.RemoteCdm`
|
||||
appends its own endpoint paths on top of this base, so omitting the suffix will result
|
||||
in 404 errors.
|
||||
|
||||
### Legacy PyWidevine Serve Format
|
||||
|
||||
@@ -329,7 +333,9 @@ remote_cdm:
|
||||
secret: secret_key
|
||||
```
|
||||
|
||||
**Note:** If the `type` field is not specified, the entry is treated as a legacy pywidevine serve CDM.
|
||||
!!! note
|
||||
|
||||
If the `type` field is not specified, the entry is treated as a legacy pywidevine serve CDM.
|
||||
|
||||
[pywidevine]: https://github.com/rlaphoenix/pywidevine
|
||||
|
||||
@@ -348,10 +354,12 @@ For example,
|
||||
decrypt_labs_api_key: "your_api_key_here"
|
||||
```
|
||||
|
||||
**Note**: This is different from the per-CDM `secret` field in `remote_cdm` entries. This provides a global
|
||||
API key that can be referenced across multiple DecryptLabs CDM configurations. If a `remote_cdm` entry with
|
||||
`type: "decrypt_labs"` does not have a `secret` field specified, the global `decrypt_labs_api_key` will be
|
||||
used as a fallback.
|
||||
!!! note
|
||||
|
||||
This is different from the per-CDM `secret` field in `remote_cdm` entries. This provides a global
|
||||
API key that can be referenced across multiple DecryptLabs CDM configurations. If a `remote_cdm` entry with
|
||||
`type: "decrypt_labs"` does not have a `secret` field specified, the global `decrypt_labs_api_key` will be
|
||||
used as a fallback.
|
||||
|
||||
---
|
||||
|
||||
@@ -402,8 +410,10 @@ locally via a WASM module.
|
||||
MonaLisa uses per-segment decryption during download (not post-download like Widevine/PlayReady),
|
||||
so segments are decrypted as they are downloaded.
|
||||
|
||||
**Note:** MonaLisa is configured per-service rather than through global config options. Services
|
||||
that use MonaLisa handle ticket/key retrieval and CDM initialization internally.
|
||||
!!! note
|
||||
|
||||
MonaLisa is configured per-service rather than through global config options. Services
|
||||
that use MonaLisa handle ticket/key retrieval and CDM initialization internally.
|
||||
|
||||
---
|
||||
|
||||
@@ -470,7 +480,7 @@ vault_timeout: 10.0 # seconds; per-vault `timeout:` overrides this
|
||||
### Using an API Vault
|
||||
|
||||
API vaults use a specific HTTP request format, therefore API or HTTP Key Vault APIs from other projects or services may
|
||||
not work in unshackle. The API format can be seen in the [API Vault Code](unshackle/vaults/API.py).
|
||||
not work in unshackle. The API format can be seen in the [API Vault Code](https://github.com/unshackle-dl/unshackle/blob/dev/unshackle/vaults/API.py).
|
||||
|
||||
```yaml
|
||||
- type: API
|
||||
@@ -523,10 +533,12 @@ case something happens to your MySQL Vault.
|
||||
# no_push: true # optional; commonly true for local backup vaults
|
||||
```
|
||||
|
||||
**Note**: You do not need to create the file at the specified path.
|
||||
SQLite will create a new SQLite database at that path if one does not exist.
|
||||
Try not to accidentally move the `db` file once created without reflecting the change in the config, or you will end
|
||||
up with multiple databases.
|
||||
!!! note
|
||||
|
||||
You do not need to create the file at the specified path.
|
||||
SQLite will create a new SQLite database at that path if one does not exist.
|
||||
Try not to accidentally move the `db` file once created without reflecting the change in the config, or you will end
|
||||
up with multiple databases.
|
||||
|
||||
If you work on a Team I recommend every team member having their own SQLite Vault even if you all use a MySQL vault
|
||||
together.
|
||||
@@ -579,6 +591,8 @@ is useful for integrating with various third-party key vault APIs.
|
||||
api_mode: "decrypt_labs"
|
||||
```
|
||||
|
||||
**Note**: The `decrypt_labs` mode is always read-only and cannot receive pushed keys.
|
||||
!!! note
|
||||
|
||||
The `decrypt_labs` mode is always read-only and cannot receive pushed keys.
|
||||
|
||||
---
|
||||
|
||||
+10
-9
@@ -65,7 +65,8 @@ Format: `gluetun:provider:region`
|
||||
3. Generate or view your service credentials
|
||||
4. Copy the username and password
|
||||
|
||||
> **Note**: Use service credentials, NOT your account email/password.
|
||||
!!! note
|
||||
Use service credentials, NOT your account email/password.
|
||||
|
||||
### WireGuard Credentials (Advanced)
|
||||
|
||||
@@ -244,15 +245,15 @@ Common issues:
|
||||
|
||||
---
|
||||
|
||||
# ExpressVPN HTTPS Proxy
|
||||
## ExpressVPN HTTPS Proxy
|
||||
|
||||
ExpressVPN is a standalone HTTPS proxy provider — it does **not** use Docker or the gluetun sub-provider system. It authenticates via a browser-extension OAuth flow (Keycloak/PKCE) and returns an authenticated `https://cat:<token>@<host>:443` proxy URL.
|
||||
|
||||
## Prerequisites
|
||||
### Prerequisites
|
||||
|
||||
An active ExpressVPN subscription is required. The provider resolves proxy-capable locations through ExpressVPN's own API, so no local VPN client or Docker container is needed.
|
||||
|
||||
## Authentication
|
||||
### Authentication
|
||||
|
||||
The provider uses a token cascade (tried in order):
|
||||
|
||||
@@ -262,7 +263,7 @@ The provider uses a token cascade (tried in order):
|
||||
|
||||
Export cookies from a browser that is logged in to `auth.expressvpn.com`. Any Netscape-format, JSON array, or `name=value` file is accepted.
|
||||
|
||||
## Configuration
|
||||
### Configuration
|
||||
|
||||
Add to `~/.config/unshackle/unshackle.yaml` under `proxy_providers`:
|
||||
|
||||
@@ -279,7 +280,7 @@ proxy_providers:
|
||||
|
||||
`region_map` maps a country code to a default city preset. An empty (null) value enables smart connection (a random location in that country). The preset is only applied when the CLI query contains no city; an explicit city in the query always takes precedence.
|
||||
|
||||
### Optional keys
|
||||
#### Optional keys
|
||||
|
||||
| Key | Default | Description |
|
||||
|-----|---------|-------------|
|
||||
@@ -291,7 +292,7 @@ proxy_providers:
|
||||
| `refresh_token` | *(none)* | OAuth refresh token (manual override) |
|
||||
| `timeout` | `10.0` | HTTP request timeout in seconds |
|
||||
|
||||
## Usage
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
unshackle dl SERVICE CONTENT --proxy expressvpn:us # random/smart US location
|
||||
@@ -307,7 +308,7 @@ Query format: `expressvpn:<country>[-<city>[-<N>]]`
|
||||
- `city` — optional city abbreviation or slug matched against location names using first-letter abbreviation (`ny` → "New York"), exact slug, prefix, then substring strategies.
|
||||
- `N` — optional 1-based server index (e.g. `-2` selects the second server in the matched city). If `N` exceeds the available server count, a random server is selected.
|
||||
|
||||
## City matching
|
||||
### City matching
|
||||
|
||||
The city part of the query is matched against ExpressVPN location names using these strategies (in priority order):
|
||||
|
||||
@@ -316,6 +317,6 @@ The city part of the query is matched against ExpressVPN location names using th
|
||||
3. Prefix match — `mia` matches "Miami"
|
||||
4. Substring match — `york` matches "New York"
|
||||
|
||||
## Token cache
|
||||
### Token cache
|
||||
|
||||
After the first successful authentication the token cache is written to `cache/global/expressvpn_tokens.json` (mode 0600). Subsequent runs refresh expired access/SRT/connection tokens automatically without re-reading cookies.
|
||||
|
||||
+53
-8
@@ -58,21 +58,66 @@ Note that `gb` is used instead of `uk` to be more consistent across regional sys
|
||||
### protonvpn (dict)
|
||||
|
||||
Enable Proton VPN as a proxy provider. Proton mints short-lived HTTPS proxy credentials per session, so
|
||||
authentication reuses an exported `account.proton.me` browser session rather than static credentials.
|
||||
authentication reuses a Proton account session (obtained via TV login or an exported browser session) rather than
|
||||
static credentials. **Free Proton accounts work**, limited to the free-tier exit countries.
|
||||
|
||||
Export the cookies for `account.proton.me` (Netscape `cookies.txt` or a JSON cookie list) — they must include
|
||||
the `AUTH-<UID>` and `REFRESH-<UID>` cookies — and save them at `<cookies>/vpn/protonvpn.txt`. **No yaml is
|
||||
required**: the provider auto-loads when that file exists. Exporting straight from the logged-in web page is
|
||||
fine; cookies for other Proton apps (e.g. `mail.proton.me`) are ignored automatically. The session refreshes on
|
||||
its own when the access token expires, so you only re-export if it is fully revoked. **Free Proton accounts
|
||||
work**, limited to the free-tier exit countries.
|
||||
There are two ways to obtain that session — TV login or cookie export. You only need one. They can also coexist: a
|
||||
cached or cookie session is always tried first, and TV login is only used as a fallback when no session is present.
|
||||
|
||||
Configuration is optional — only add a block to override defaults:
|
||||
#### TV login (self-sustaining, recommended)
|
||||
|
||||
Set `enable: true` and run any command that uses the proxy. On first use, when no session is cached, unshackle
|
||||
prints a code and pauses:
|
||||
|
||||
1. Open `https://account.proton.me/vpn/tv/code` in a browser where you are signed in to Proton.
|
||||
2. Enter the code shown in the terminal and approve it.
|
||||
3. Return to the terminal and **press Enter** to continue.
|
||||
|
||||
The minted refresh token is cached at `<cache>/vpn/protonvpn.json` and **refreshes on its own forever after**, so
|
||||
this is genuinely a one-time step — later runs load straight from the cache without prompting. The prompt is **off
|
||||
by default** (`enable: false`) so nobody is prompted unexpectedly, and it is skipped automatically when there is no
|
||||
interactive terminal (e.g. under `serve`, cron, or piped input) — in those contexts, use a cookie export or run an
|
||||
interactive command once to seed the cache first.
|
||||
|
||||
#### Cookie export (easiest to collect, but lapses)
|
||||
|
||||
Export the cookies for `account.proton.me` **or** `account.protonvpn.com` (Netscape `cookies.txt` or a JSON cookie
|
||||
list) and save them at `<cookies>/vpn/protonvpn.txt`. The provider auto-loads when that file exists (no YAML
|
||||
required); cookies for other Proton apps (e.g. `mail.proton.me`) are ignored automatically.
|
||||
|
||||
- The export **must include the `AUTH-<UID>` cookie**. It is **HttpOnly** — many one-click cookie-export
|
||||
extensions skip HttpOnly cookies by default, which is the most common reason an export "doesn't work". Use an
|
||||
exporter that includes them.
|
||||
- A browser session **cannot be refreshed headlessly** — Proton rotates browser refresh tokens and ties them to
|
||||
the live browser. unshackle therefore uses the cookie's access token only (it never tries to refresh it) and the
|
||||
session works until that token expires (Proton's TTL, typically ~24h); after that you must re-export. For a
|
||||
set-and-forget setup, prefer TV login.
|
||||
- Cookies are read fresh from the file on every run and are **never written to the cache**. If a TV-login cache
|
||||
also exists, it is preferred unless the cookie file is newer — so to force the cookie session, just re-save
|
||||
(re-export) the cookie file.
|
||||
|
||||
#### Resetting
|
||||
|
||||
To start clean, delete both `<cookies>/vpn/protonvpn.txt` and `<cache>/vpn/protonvpn.json`.
|
||||
|
||||
#### Troubleshooting
|
||||
|
||||
- **`Proton: no session available …`** — no cookies and no cache were found. Either export cookies, or set
|
||||
`enable: true` and run from an interactive terminal (the prompt is skipped on non-tty stdin).
|
||||
- **`Proton: session expired; re-export … cookies`** — a cookie session's access token lapsed and cannot be
|
||||
refreshed (expected for cookie auth). Re-export the cookies, or switch to TV login.
|
||||
|
||||
#### Configuration
|
||||
|
||||
Configuration is optional — only add a block to enable TV login or override defaults:
|
||||
|
||||
```yaml
|
||||
proxy_providers:
|
||||
protonvpn:
|
||||
enable: true # prompt the one-time TV login when no session is cached (default false)
|
||||
cookie_path: /path/to/protonvpn.txt # optional; defaults to <cookies>/vpn/protonvpn.txt
|
||||
cache_path: /path/to/protonvpn.json # optional; defaults to <cache>/vpn/protonvpn.json
|
||||
timeout: 10 # optional; per-request timeout in seconds (default 10)
|
||||
server_map:
|
||||
stream-us: us:ny # optional alias -> country / country:city / countryNN
|
||||
```
|
||||
|
||||
+15
-3
@@ -43,7 +43,7 @@ Add `?` suffix to make a variable conditional (omitted when empty): `{year?}`, `
|
||||
|---|---|
|
||||
| `title` | Title of the movie, episode, or track |
|
||||
| `year` | Release year |
|
||||
| `source` | Service source tag (e.g. `AMZN`, `NF`) |
|
||||
| `source` | Service source tag (the uppercase service directory name) |
|
||||
| `tag` | Group/release tag configured via `tag:` |
|
||||
| `edition` | Edition label (e.g. `Extended`, `Theatrical`) |
|
||||
| `repack` | `REPACK` when the release is a repack, otherwise empty |
|
||||
@@ -57,6 +57,18 @@ Add `?` suffix to make a variable conditional (omitted when empty): `{year?}`, `
|
||||
| `episode` | Episode number (e.g. `1`) |
|
||||
| `season_episode` | Combined season/episode (e.g. `S01E01`) |
|
||||
| `episode_name` | Episode title |
|
||||
| `date` | Air date in ISO form (e.g. `2024-06-30`), only for daily/sports content |
|
||||
|
||||
!!! note "Daily / sports content"
|
||||
When a service supplies an air date (daily talk shows, news, sports events),
|
||||
`{season_episode}` automatically renders the date using your template's separator
|
||||
(e.g. `2024.06.30` for a dotted template, `2024 06 30` for a spaced one). The
|
||||
standalone `{year}` is dropped from the filename — the air date is the sole date —
|
||||
so every episode of a show names consistently. Folders still keep the year (e.g.
|
||||
`Show Name (2010)/2024/`). No template change is needed.
|
||||
|
||||
Use the `{date}` variable instead if you want a fixed `YYYY-MM-DD` form regardless
|
||||
of separator. Folders for dated episodes group by air year (e.g. `Show Name/2024/`).
|
||||
|
||||
### Video / audio variables
|
||||
|
||||
@@ -414,14 +426,14 @@ How it works:
|
||||
local first to let your local tweaks override a repo.
|
||||
- **What you see on load.** A one-line summary is logged each run, e.g.:
|
||||
|
||||
```
|
||||
```text
|
||||
Loaded 103 services (36 duplicate(s) ignored)
|
||||
```
|
||||
|
||||
The full per-duplicate detail is logged only at debug verbosity (`unshackle -d ...`), one line per
|
||||
duplicate, naming the path that loaded and the path that was ignored:
|
||||
|
||||
```
|
||||
```text
|
||||
EXAMPLE: using <unshackle>/services/EXAMPLE/__init__.py, ignoring duplicate <unshackle>/services/_repos/your-repo/EXAMPLE/__init__.py
|
||||
```
|
||||
|
||||
|
||||
+3
-2
@@ -1,11 +1,12 @@
|
||||
# docs/
|
||||
# unshackle Documentation
|
||||
|
||||
This folder is the **canonical configuration reference** for unshackle. `unshackle/unshackle-example.yaml` is a minimal starter config only — it intentionally omits most options. Come here for the full picture.
|
||||
This is the **canonical configuration reference** for unshackle. `unshackle/unshackle-example.yaml` is a minimal starter config only - it intentionally omits most options. Come here for the full picture.
|
||||
|
||||
## Contents
|
||||
|
||||
| Document | Description |
|
||||
|---|---|
|
||||
| [Creating a Service](CREATING_A_SERVICE.md) | Section-by-section guide to writing a new service adapter, based on the `EXAMPLE` service |
|
||||
| [Advanced & System Configuration](ADVANCED_CONFIG.md) | `serve`, debugging, and system-level options not covered elsewhere |
|
||||
| [REST API Documentation](API.md) | HTTP API exposed by `unshackle serve`: endpoints, auth, remote downloads, CDM hosting |
|
||||
| [Structured Debug Logging](DEBUG_LOGGING.md) | `-d`/`--debug` JSONL output: schema, redaction rules, `log_event`/`timed_operation` conventions |
|
||||
|
||||
+10
-6
@@ -209,7 +209,8 @@ For example,
|
||||
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.
|
||||
!!! 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.
|
||||
|
||||
---
|
||||
|
||||
@@ -230,7 +231,8 @@ For example,
|
||||
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.
|
||||
!!! 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.
|
||||
|
||||
---
|
||||
|
||||
@@ -249,7 +251,8 @@ For example,
|
||||
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.
|
||||
!!! 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.
|
||||
|
||||
---
|
||||
|
||||
@@ -291,8 +294,9 @@ 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.
|
||||
!!! note "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.
|
||||
|
||||
---
|
||||
|
||||
@@ -33,7 +33,7 @@ Control subtitle conversion, SDH (hearing-impaired) stripping, formatting preser
|
||||
`--sub-format srt` for the muxed track, or `sidecar_format: srt` for sidecars. To keep raw styled
|
||||
sidecars, set `sidecar_format: original`.
|
||||
|
||||
**Segmented subtitles** (`fVTT`/WVTT and `fTTML`/STPP from DASH/HLS, e.g. HBO Max) are read directly
|
||||
**Segmented subtitles** (`fVTT`/WVTT and `fTTML`/STPP from DASH/HLS) are read directly
|
||||
from the fragmented MP4: fVTT via subby's `WVTTConverter`, fTTML via pycaption's box parsing. They
|
||||
can be converted *from* but not *to*.
|
||||
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
# Authentication
|
||||
|
||||
When `api_secret` is set in `unshackle.yaml`, all API requests require the **`X-Secret-Key`** header. There is no query-parameter fallback. `/api/health` is always reachable without authentication. `--no-key` disables auth entirely (not recommended for public-facing servers).
|
||||
|
||||
```yaml
|
||||
# unshackle.yaml
|
||||
serve:
|
||||
api_secret: "your-master-secret" # falls back to global users map below
|
||||
remote_only: false # also toggleable via --remote-only
|
||||
services: ["EXAMPLE1", "EXAMPLE2"] # optional global service allowlist
|
||||
users:
|
||||
user-secret-1:
|
||||
username: alice
|
||||
devices: ["my_widevine_l3"] # Widevine WVD names this user may use
|
||||
playready_devices: ["my_pr_sl2000"] # PlayReady PRD names; defaults to [] (no access)
|
||||
services: ["EXAMPLE1"] # optional per-user allowlist (intersected with global)
|
||||
user-secret-2:
|
||||
username: bob
|
||||
devices: []
|
||||
playready_devices: []
|
||||
```
|
||||
|
||||
## Service allowlists
|
||||
|
||||
`config.serve.services` is the global allowlist; `users.<key>.services` further narrows it per key. The effective set is the intersection. Endpoints affected: `/api/services`, `/api/search`, `/api/list-titles`, `/api/list-tracks`, `/api/download`, and all `/api/session/*` routes.
|
||||
|
||||
## CDM access (server-side decryption)
|
||||
|
||||
There is no separate "tier" flag. Whether the server can return KID:KEY for a session-mode download depends solely on the device lists configured for the calling user key:
|
||||
|
||||
- Empty `devices` and `playready_devices` -> server can only proxy CDM challenges; the client must run its own CDM and parse the license.
|
||||
- Populated lists -> the client may set `mode: "server_cdm"` on `/api/session/{id}/license` and receive `{ "keys": { "<track_id>": { "<KID>": "<KEY>" } } }` instead of raw license bytes.
|
||||
|
||||
Per-service CDM type can be pinned via `config.cdm` (`widevine`/`playready`) or per-service `cdm_type`; otherwise the server picks the type the user has devices for.
|
||||
|
||||
## Server-side `dl` defaults
|
||||
|
||||
Any flag accepted by `/api/download` (see the table below) can be declared under `serve:` in `unshackle.yaml` and the API will apply it as a default. Request-body values still win. Useful for raising concurrency without changing every client call:
|
||||
|
||||
```yaml
|
||||
serve:
|
||||
api_secret: "..."
|
||||
users: { ... }
|
||||
downloads: 4 # parallel tracks per download job
|
||||
workers: 16 # threads per track segment fetch
|
||||
best_available: true
|
||||
no_proxy_download: false
|
||||
```
|
||||
|
||||
Layering order: built-in defaults < `serve.*` overrides < service-specific click defaults < request body.
|
||||
|
||||
## Per-request override gates
|
||||
|
||||
Two security gates under `serve:` guard capabilities that `/api/download` clients can request. Both default OFF; an unset or `false` value causes the server to reject the request with `403 FORBIDDEN`.
|
||||
|
||||
**`cdm_overrides`** — a `/api/download` job body may include a `cdm` field to select a specific server-side device. When this gate is off, every such request is rejected. Set to `true` to allow any device the server has, or to a list of device names to restrict to an explicit subset:
|
||||
|
||||
```yaml
|
||||
serve:
|
||||
# Allow any server-side device:
|
||||
cdm_overrides: true
|
||||
|
||||
# Or restrict to specific devices:
|
||||
cdm_overrides:
|
||||
- generic_nexus_4464_l3
|
||||
```
|
||||
|
||||
**`allow_job_credentials`** — a `/api/download` job body may include a `credential` (single) or `credentials` (map) field to authenticate the job with client-supplied secrets instead of the server's configured credentials. When this gate is off, any job containing either field is rejected. Each distinct credential gets its own isolated token cache on the server. Set to `true` to allow:
|
||||
|
||||
```yaml
|
||||
serve:
|
||||
allow_job_credentials: true
|
||||
```
|
||||
|
||||
Both gates are independent and can be combined. A typical locked-down deployment leaves both unset; a trusted single-client deployment might enable both.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Download Job Lifecycle
|
||||
|
||||
```text
|
||||
queued -> downloading -> completed
|
||||
\-> failed
|
||||
queued -> cancelled
|
||||
downloading -> cancelled
|
||||
```
|
||||
|
||||
Jobs are retained for 24 hours after completion (override via top-level `download_job_retention_hours` in `unshackle.yaml`). The server runs up to 2 concurrent download jobs by default; override via top-level `max_concurrent_downloads`. This is independent of `serve.downloads`, which controls parallel tracks **within** a single job.
|
||||
|
||||
Remote sessions are managed by `SessionStore` (`unshackle/core/api/session_store.py`); idle sessions and their `InputBridge` instances are cleaned up by a background loop started/stopped with the app lifecycle.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Endpoint Map
|
||||
|
||||
Standard endpoints (suppressed in `--remote-only` mode are marked R):
|
||||
|
||||
| Method | Path | R |
|
||||
| --- | --- | :-: |
|
||||
| GET | `/api/health` | ok |
|
||||
| GET | `/api/services` | ok |
|
||||
| POST | `/api/search` | ok |
|
||||
| POST | `/api/list-titles` | hidden |
|
||||
| POST | `/api/list-tracks` | hidden |
|
||||
| POST | `/api/download` | hidden |
|
||||
| GET | `/api/download/jobs` | hidden |
|
||||
| GET | `/api/download/jobs/{job_id}` | hidden |
|
||||
| DELETE | `/api/download/jobs/{job_id}` | hidden |
|
||||
| POST | `/api/session/create` | ok |
|
||||
| GET | `/api/session/{session_id}` | ok |
|
||||
| DELETE | `/api/session/{session_id}` | ok |
|
||||
| GET | `/api/session/{session_id}/titles` | ok |
|
||||
| POST | `/api/session/{session_id}/tracks` | ok |
|
||||
| POST | `/api/session/{session_id}/segments` | ok |
|
||||
| POST | `/api/session/{session_id}/license` | ok |
|
||||
| GET | `/api/session/{session_id}/prompt` | ok |
|
||||
| POST | `/api/session/{session_id}/prompt` | ok |
|
||||
|
||||
CDM endpoints (`/{wvd}/...`, `/playready/{prd}/...`) are exposed unless `--api-only` / `--remote-only` / `--no-widevine` / `--no-playready` is set, and use pywidevine / pyplayready's own auth scheme.
|
||||
@@ -0,0 +1,277 @@
|
||||
# Endpoints
|
||||
|
||||
## GET /api/health
|
||||
|
||||
Health check with version and update information. Always reachable without auth.
|
||||
|
||||
```bash
|
||||
curl http://localhost:8786/api/health
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"version": "4.0.0",
|
||||
"update_check": {
|
||||
"update_available": false,
|
||||
"current_version": "4.0.0",
|
||||
"latest_version": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /api/services
|
||||
|
||||
List all available streaming services (filtered by the effective allowlist for the caller).
|
||||
|
||||
```bash
|
||||
curl -H "X-Secret-Key: $KEY" http://localhost:8786/api/services
|
||||
```
|
||||
|
||||
Returns `{"services": [...]}`. Each entry has `tag`, `aliases`, `geofence`, `title_regex`, `url` (from `cli.short_help`), `help` (full docstring), and `cli_params` describing the service-level Click parameters.
|
||||
|
||||
---
|
||||
|
||||
## POST /api/search
|
||||
|
||||
Search for titles from a streaming service.
|
||||
|
||||
**Required parameters:**
|
||||
| Parameter | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `service` | string | Service tag |
|
||||
| `query` | string | Search query |
|
||||
|
||||
**Optional parameters:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `profile` | string | `null` | Profile for credentials/cookies |
|
||||
| `proxy` | string | `null` | Proxy URI or country code |
|
||||
| `no_proxy` | boolean | `false` | Disable all proxy use |
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8786/api/search \
|
||||
-H "X-Secret-Key: $KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"service": "EXAMPLE1", "query": "example show"}'
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"id": "abc123def456",
|
||||
"title": "Example Show",
|
||||
"description": null,
|
||||
"label": "TV Show",
|
||||
"url": "https://example.com/show/abc123def456"
|
||||
}
|
||||
],
|
||||
"count": 1
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /api/list-titles
|
||||
|
||||
Get available titles (seasons/episodes/movies) for a service and title ID. Disabled in `--remote-only` mode.
|
||||
|
||||
**Required parameters:**
|
||||
| Parameter | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `service` | string | Service tag |
|
||||
| `title_id` | string | Title ID or URL |
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8786/api/list-titles \
|
||||
-H "X-Secret-Key: $KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"service": "EXAMPLE1", "title_id": "abc123def456"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /api/list-tracks
|
||||
|
||||
Get video, audio, and subtitle tracks for a title. Disabled in `--remote-only` mode.
|
||||
|
||||
**Required parameters:**
|
||||
| Parameter | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `service` | string | Service tag |
|
||||
| `title_id` | string | Title ID or URL |
|
||||
|
||||
**Optional parameters:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `wanted` | array | all | Episode filter (e.g., `["S01E01"]`) |
|
||||
| `profile` | string | `null` | Profile for credentials/cookies |
|
||||
| `proxy` | string | `null` | Proxy URI or country code |
|
||||
| `no_proxy` | boolean | `false` | Disable all proxy use |
|
||||
|
||||
Returns video, audio, and subtitle tracks with codec, bitrate, resolution, language, and DRM information.
|
||||
|
||||
---
|
||||
|
||||
## POST /api/download
|
||||
|
||||
Start a download job. Returns immediately with a job ID (HTTP 202). Disabled in `--remote-only` mode.
|
||||
|
||||
**Required parameters:**
|
||||
| Parameter | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `service` | string | Service tag |
|
||||
| `title_id` | string | Title ID or URL |
|
||||
|
||||
**Quality and codec parameters:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `quality` | array[int] | best | Resolution(s) (e.g., `[1080, 2160]`) |
|
||||
| `vcodec` | string or array | any | Video codec(s): `H264`, `H265`/`HEVC`, `VP9`, `AV1`, `VC1`, `VP8` |
|
||||
| `acodec` | string or array | any | Audio codec(s): `AAC`, `AC3`, `EC3`, `AC4`, `OPUS`, `FLAC`, `ALAC`, `DTS`, `OGG` |
|
||||
| `vbitrate` | int | highest | Video bitrate in kbps |
|
||||
| `abitrate` | int | highest | Audio bitrate in kbps |
|
||||
| `range` | array[string] | `["SDR"]` | Color range(s): `SDR`, `HDR10`, `HDR10+`, `HLG`, `DV`, `HYBRID` |
|
||||
| `channels` | float | any | Audio channels (e.g., `5.1`, `7.1`) |
|
||||
| `no_atmos` | boolean | `false` | Exclude Dolby Atmos tracks |
|
||||
| `split_audio` | boolean | `null` | Create separate output per audio codec |
|
||||
| `sub_format` | string | `null` | Output subtitle format: `SRT`, `VTT`, `ASS`, `SSA`, `TTML` |
|
||||
|
||||
**Episode selection:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `wanted` | array[string] | all | Episodes (e.g., `["S01E01", "S01E02-S01E05"]`) |
|
||||
| `latest_episode` | boolean | `false` | Download only the most recent episode |
|
||||
|
||||
**Language parameters:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `lang` | array[string] | `["orig"]` | Language for video and audio (`orig` = original) |
|
||||
| `v_lang` | array[string] | `[]` | Language override for video tracks only |
|
||||
| `a_lang` | array[string] | `[]` | Language override for audio tracks only |
|
||||
| `s_lang` | array[string] | `["all"]` | Language for subtitles |
|
||||
| `require_subs` | array[string] | `[]` | Required subtitle languages (skip if missing) |
|
||||
| `forced_subs` | boolean | `false` | Include forced subtitle tracks |
|
||||
| `exact_lang` | boolean | `false` | Exact language matching (no variants) |
|
||||
|
||||
**Track selection:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `video_only` | boolean | `false` | Only download video tracks |
|
||||
| `audio_only` | boolean | `false` | Only download audio tracks |
|
||||
| `subs_only` | boolean | `false` | Only download subtitle tracks |
|
||||
| `chapters_only` | boolean | `false` | Only download chapters |
|
||||
| `no_video` | boolean | `false` | Skip video tracks |
|
||||
| `no_audio` | boolean | `false` | Skip audio tracks |
|
||||
| `no_subs` | boolean | `false` | Skip subtitle tracks |
|
||||
| `no_chapters` | boolean | `false` | Skip chapters |
|
||||
| `audio_description` | boolean | `false` | Include audio description tracks |
|
||||
|
||||
**Output and tagging:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `tag` | string | `null` | Override group tag |
|
||||
| `repack` | boolean | `false` | Add REPACK tag to filename |
|
||||
| `tmdb_id` | int | `null` | Use specific TMDB ID for tagging |
|
||||
| `imdb_id` | string | `null` | Use specific IMDB ID (e.g., `tt1375666`) |
|
||||
| `animeapi_id` | string | `null` | Anime database ID via AnimeAPI (e.g., `mal:12345`) |
|
||||
| `enrich` | boolean | `false` | Override show title and year from external source |
|
||||
| `no_folder` | boolean | `false` | Disable folder creation for TV shows |
|
||||
| `no_source` | boolean | `false` | Remove source tag from filename |
|
||||
| `no_mux` | boolean | `false` | Do not mux tracks into container |
|
||||
| `output_dir` | string | `null` | Override output directory |
|
||||
|
||||
**Download behavior:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `profile` | string | `null` | Profile for credentials/cookies |
|
||||
| `proxy` | string | `null` | Proxy URI or country code |
|
||||
| `no_proxy` | boolean | `false` | Disable all proxy use |
|
||||
| `no_proxy_download` | boolean | `false` | Bypass proxy for segment downloads only. Manifest, license, and auth still use proxy |
|
||||
| `workers` | int | `null` | Max threads per track download |
|
||||
| `downloads` | int | `1` | Concurrent track downloads |
|
||||
| `slow` | boolean or string | `null` | Add randomized delay between titles. `true` = 60-120s, or `"MIN-MAX"` string (e.g., `"20-40"`). Min must be >= 20 |
|
||||
| `best_available` | boolean | `false` | Continue if requested quality unavailable |
|
||||
| `worst` | boolean | `false` | Select the lowest bitrate track within the specified quality. Requires `quality` |
|
||||
| `skip_dl` | boolean | `false` | Skip download, only get decryption keys |
|
||||
| `export` | boolean | `false` | Export manifest, track URLs, keys, and subtitles to JSON in the exports directory |
|
||||
| `cdm_only` | boolean | `null` | Only use CDM (`true`) or only vaults (`false`) |
|
||||
| `no_cache` | boolean | `false` | Bypass title cache |
|
||||
| `reset_cache` | boolean | `false` | Clear title cache before fetching |
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8786/api/download \
|
||||
-H "X-Secret-Key: $KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"service": "EXAMPLE1",
|
||||
"title_id": "abc123def456",
|
||||
"wanted": ["S01E01"],
|
||||
"quality": [1080, 2160],
|
||||
"vcodec": ["H265"],
|
||||
"acodec": ["AAC", "EC3"],
|
||||
"range": ["HDR10", "SDR"],
|
||||
"split_audio": true,
|
||||
"lang": ["en"]
|
||||
}'
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"job_id": "504db959-80b0-446c-a764-7924b761d613",
|
||||
"status": "queued",
|
||||
"created_time": "2026-02-27T18:00:00.000000"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /api/download/jobs
|
||||
|
||||
List all download jobs with optional filtering and sorting. Disabled in `--remote-only` mode.
|
||||
|
||||
**Query parameters:**
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `status` | string | all | Filter by status: `queued`, `downloading`, `completed`, `failed`, `cancelled` |
|
||||
| `service` | string | all | Filter by service tag |
|
||||
| `sort_by` | string | `created_time` | Sort field: `created_time`, `started_time`, `completed_time`, `progress`, `status`, `service` |
|
||||
| `sort_order` | string | `desc` | Sort order: `asc`, `desc` |
|
||||
|
||||
```bash
|
||||
curl -H "X-Secret-Key: $KEY" "http://localhost:8786/api/download/jobs?status=completed"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /api/download/jobs/{job_id}
|
||||
|
||||
Get detailed information about a specific download job including progress, parameters, and error details.
|
||||
|
||||
```json
|
||||
{
|
||||
"job_id": "504db959-80b0-446c-a764-7924b761d613",
|
||||
"status": "completed",
|
||||
"created_time": "2026-02-27T18:00:00.000000",
|
||||
"service": "EXAMPLE1",
|
||||
"title_id": "abc123def456",
|
||||
"progress": 100.0,
|
||||
"parameters": { },
|
||||
"started_time": "2026-02-27T18:00:01.000000",
|
||||
"completed_time": "2026-02-27T18:00:15.000000",
|
||||
"output_files": [],
|
||||
"error_message": null,
|
||||
"error_details": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DELETE /api/download/jobs/{job_id}
|
||||
|
||||
Cancel a queued or running download job. Returns 400 if the job has already terminated.
|
||||
@@ -0,0 +1,28 @@
|
||||
# Error Responses
|
||||
|
||||
All endpoints return consistent error responses:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"error_code": "INVALID_PARAMETERS",
|
||||
"message": "Invalid vcodec: XYZ. Must be one of: H264, H265, VP9, AV1, VC1, VP8",
|
||||
"timestamp": "2026-02-27T18:00:00.000000+00:00",
|
||||
"details": { }
|
||||
}
|
||||
```
|
||||
|
||||
Common error codes:
|
||||
|
||||
- `INVALID_INPUT` -- malformed request body
|
||||
- `INVALID_PARAMETERS` -- invalid parameter values
|
||||
- `MISSING_SERVICE` -- service tag not provided
|
||||
- `INVALID_SERVICE` -- service not found or not in the caller's allowlist
|
||||
- `SERVICE_ERROR` -- service initialization or runtime error
|
||||
- `AUTH_FAILED` -- authentication failure
|
||||
- `NOT_FOUND` / `TRACK_NOT_FOUND` / session not found -- job/session/track/title missing
|
||||
- `INTERNAL_ERROR` -- unexpected server error
|
||||
|
||||
When `--debug-api` is enabled, error responses include additional `debug_info` with tracebacks and stderr output.
|
||||
|
||||
Authentication errors from the auth middleware are returned as `{"status": 401, "message": "..."}` (not the standard error envelope).
|
||||
@@ -0,0 +1,37 @@
|
||||
# Quick Start
|
||||
|
||||
```bash
|
||||
# Start the server (no authentication)
|
||||
unshackle serve --no-key
|
||||
|
||||
# Start with authentication (api_secret in unshackle.yaml)
|
||||
unshackle serve
|
||||
|
||||
# Serve only the REST API (no pywidevine/pyplayready CDM)
|
||||
unshackle serve --api-only
|
||||
|
||||
# Serve only the remote-dl session endpoints (CORS/Cloudflare friendly)
|
||||
unshackle serve --remote-only
|
||||
|
||||
# Disable just one CDM
|
||||
unshackle serve --no-widevine
|
||||
unshackle serve --no-playready
|
||||
|
||||
# Verbose error responses (tracebacks/stderr in JSON)
|
||||
unshackle serve --debug-api
|
||||
```
|
||||
|
||||
`serve` flags:
|
||||
|
||||
| Flag | Description |
|
||||
| --- | --- |
|
||||
| `-h, --host` | Bind host (default `127.0.0.1`) |
|
||||
| `-p, --port` | Bind port (default `8786`) |
|
||||
| `--caddy` | Also launch Caddy using `Caddyfile` next to the unshackle config |
|
||||
| `--api-only` | REST API only; skip the bundled pywidevine/pyplayready CDM endpoints |
|
||||
| `--no-widevine` | Disable Widevine CDM endpoints |
|
||||
| `--no-playready` | Disable PlayReady CDM endpoints |
|
||||
| `--no-key` | Disable API key authentication entirely |
|
||||
| `--debug-api` | Include tracebacks/stderr in error responses |
|
||||
| `--debug` | Enable DEBUG-level logging for API operations |
|
||||
| `--remote-only` | Expose only `/api/health`, `/api/services`, `/api/search`, and `/api/session/*` (implies `--api-only`) |
|
||||
@@ -0,0 +1,329 @@
|
||||
# Remote Service Sessions
|
||||
|
||||
These endpoints back the `RemoteService` adapter in `unshackle/core/remote_service.py`. They let a thin `dl` client (or any consumer) authenticate against a service on the server, fetch titles/tracks/manifests, and either proxy CDM challenges or have the server resolve KID:KEY directly. The `dl` command's `RemoteService` adapter replaces the old `remote_dl` command. These endpoints are the only `/api/*` routes available in `--remote-only` mode (in addition to `health`, `services`, and `search`).
|
||||
|
||||
## POST /api/session/create
|
||||
|
||||
Authenticate against a service and open a session. Body fields:
|
||||
|
||||
| Field | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `service` | string | Service tag (required) |
|
||||
| `title_id` | string | Title ID/URL (required) |
|
||||
| `credentials` | object | Auth credentials forwarded to `Service.authenticate` |
|
||||
| `cookies` | string | Cookie blob (Netscape or JSON) |
|
||||
| `proxy` | string | Proxy URI or country code |
|
||||
| `no_proxy` | bool | Force-disable proxies |
|
||||
| `profile` | string | Profile name |
|
||||
| `cache` | object | Optional pre-warmed title cache payload |
|
||||
|
||||
If the service requires interactive input during authentication, poll `GET /api/session/{id}/prompt` and submit responses via `POST /api/session/{id}/prompt` until status is `authenticated`.
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"service": "EXAMPLE1",
|
||||
"title_id": "abc123def456",
|
||||
"credentials": {"username": "alice", "password": "hunter2"},
|
||||
"cookies": "# Netscape HTTP Cookie File\n...",
|
||||
"proxy": "us",
|
||||
"no_proxy": false,
|
||||
"profile": "default",
|
||||
"cache": {}
|
||||
}
|
||||
```
|
||||
|
||||
**Response (202-style; auth runs asynchronously):**
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "f1c4a8b2-9c7e-4d2a-bf91-2d3e4f5a6b7c",
|
||||
"service": "EXAMPLE1",
|
||||
"status": "authenticating"
|
||||
}
|
||||
```
|
||||
|
||||
## GET /api/session/{session_id}
|
||||
|
||||
Returns session metadata. 404 if expired or unknown.
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "f1c4a8b2-9c7e-4d2a-bf91-2d3e4f5a6b7c",
|
||||
"service": "EXAMPLE1",
|
||||
"valid": true,
|
||||
"expires_in": 3600,
|
||||
"track_count": 0,
|
||||
"title_count": 0
|
||||
}
|
||||
```
|
||||
|
||||
## DELETE /api/session/{session_id}
|
||||
|
||||
Tears down the session, cancels any pending prompts, and returns any updated per-session cache files (base64-encoded, zlib-compressed) so the client can re-warm next time.
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"cache": {
|
||||
"tokens": "eJzLSM3JyVcozy/KSVGo5AIAGgQEvQ=="
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## GET /api/session/{session_id}/titles
|
||||
|
||||
Returns the resolved titles list.
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "f1c4a8b2-9c7e-4d2a-bf91-2d3e4f5a6b7c",
|
||||
"titles": [
|
||||
{
|
||||
"type": "episode",
|
||||
"name": "Pilot",
|
||||
"series_title": "Example Show",
|
||||
"season": 1,
|
||||
"number": 1,
|
||||
"year": 2024,
|
||||
"id": "ep-0001",
|
||||
"language": "en"
|
||||
},
|
||||
{
|
||||
"type": "movie",
|
||||
"name": "Example Movie",
|
||||
"year": 2024,
|
||||
"id": "mov-0001",
|
||||
"language": "en"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## POST /api/session/{session_id}/tracks
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{"title_id": "ep-0001"}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"title": {
|
||||
"type": "episode",
|
||||
"name": "Pilot",
|
||||
"series_title": "Example Show",
|
||||
"season": 1,
|
||||
"number": 1,
|
||||
"year": 2024,
|
||||
"id": "ep-0001",
|
||||
"language": "en"
|
||||
},
|
||||
"video": [
|
||||
{
|
||||
"id": "v-1080p-h264",
|
||||
"codec": "H264",
|
||||
"codec_display": "H.264",
|
||||
"bitrate": 6000,
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"resolution": "1920x1080",
|
||||
"fps": "23.976",
|
||||
"range": "SDR",
|
||||
"range_display": "SDR",
|
||||
"language": "en",
|
||||
"drm": [
|
||||
{
|
||||
"type": "widevine",
|
||||
"pssh": "AAAAW3Bzc2gAAAAA7e+...",
|
||||
"kids": ["abcdef0123456789abcdef0123456789"],
|
||||
"license_url": "https://license.example.com/widevine"
|
||||
}
|
||||
],
|
||||
"descriptor": "DASH",
|
||||
"url": "https://cdn.example.com/manifest.mpd"
|
||||
}
|
||||
],
|
||||
"audio": [
|
||||
{
|
||||
"id": "a-en-eac3",
|
||||
"codec": "EC3",
|
||||
"codec_display": "Dolby Digital Plus",
|
||||
"bitrate": 640,
|
||||
"channels": "5.1",
|
||||
"language": "en",
|
||||
"atmos": false,
|
||||
"descriptive": false,
|
||||
"drm": null,
|
||||
"descriptor": "DASH",
|
||||
"url": "https://cdn.example.com/manifest.mpd"
|
||||
}
|
||||
],
|
||||
"subtitles": [
|
||||
{
|
||||
"id": "s-en-vtt",
|
||||
"codec": "WebVTT",
|
||||
"language": "en",
|
||||
"forced": false,
|
||||
"sdh": false,
|
||||
"cc": false,
|
||||
"descriptor": "DASH",
|
||||
"url": "https://cdn.example.com/subs/en.vtt"
|
||||
}
|
||||
],
|
||||
"chapters": [
|
||||
{"timestamp": "00:00:00.000", "name": "Chapter 1"}
|
||||
],
|
||||
"attachments": [],
|
||||
"manifests": [
|
||||
{
|
||||
"type": "dash",
|
||||
"url": "https://cdn.example.com/manifest.mpd",
|
||||
"data": "eJzNVk1v2zAM/Ss..."
|
||||
}
|
||||
],
|
||||
"session_headers": {
|
||||
"User-Agent": "Mozilla/5.0 ..."
|
||||
},
|
||||
"session_cookies": {
|
||||
"session": "abc123"
|
||||
},
|
||||
"server_cdm_type": "widevine"
|
||||
}
|
||||
```
|
||||
|
||||
## POST /api/session/{session_id}/segments
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{"track_ids": ["v-1080p-h264", "a-en-eac3"]}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"tracks": {
|
||||
"v-1080p-h264": {
|
||||
"descriptor": "DASH",
|
||||
"url": "https://cdn.example.com/manifest.mpd",
|
||||
"drm": [
|
||||
{
|
||||
"type": "widevine",
|
||||
"pssh": "AAAAW3Bzc2gAAAAA7e+...",
|
||||
"kids": ["abcdef0123456789abcdef0123456789"],
|
||||
"license_url": "https://license.example.com/widevine"
|
||||
}
|
||||
],
|
||||
"headers": {"User-Agent": "Mozilla/5.0 ..."},
|
||||
"cookies": {"session": "abc123"},
|
||||
"data": {}
|
||||
},
|
||||
"a-en-eac3": {
|
||||
"descriptor": "DASH",
|
||||
"url": "https://cdn.example.com/manifest.mpd",
|
||||
"drm": null,
|
||||
"headers": {"User-Agent": "Mozilla/5.0 ..."},
|
||||
"cookies": {"session": "abc123"},
|
||||
"data": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## POST /api/session/{session_id}/license
|
||||
|
||||
Two modes, selected by the `mode` field.
|
||||
|
||||
**`mode: "proxy"` (default)** -- forward a client-built CDM challenge to the service's license endpoint.
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "proxy",
|
||||
"track_id": "v-1080p-h264",
|
||||
"challenge": "CAESxQEK...",
|
||||
"drm_type": "widevine",
|
||||
"pssh": "AAAAW3Bzc2gAAAAA7e+..."
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{"license": "CAIS3wIK..."}
|
||||
```
|
||||
|
||||
**`mode: "server_cdm"`** -- the server uses its own CDM to license the track and extract keys. Single-track form takes `track_id`; batch form takes `track_ids`. Requires the calling user key to have a matching device (`devices` for Widevine, `playready_devices` for PlayReady) in `unshackle.yaml`.
|
||||
|
||||
Request (batch):
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "server_cdm",
|
||||
"track_ids": ["v-1080p-h264", "a-en-eac3"],
|
||||
"drm_type": "widevine"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"keys": {
|
||||
"v-1080p-h264": {
|
||||
"abcdef0123456789abcdef0123456789": "00112233445566778899aabbccddeeff"
|
||||
},
|
||||
"a-en-eac3": {
|
||||
"abcdef0123456789abcdef0123456789": "00112233445566778899aabbccddeeff"
|
||||
}
|
||||
},
|
||||
"drm_type": "widevine"
|
||||
}
|
||||
```
|
||||
|
||||
## GET /api/session/{session_id}/prompt
|
||||
|
||||
Polled by the client during interactive authentication (OTP, PIN, device codes). Backed by the `InputBridge` in `unshackle/core/api/input_bridge.py`; `Service.request_input()` blocks server-side until the client posts a response.
|
||||
|
||||
Pending input:
|
||||
|
||||
```json
|
||||
{"status": "pending_input", "prompt": "Enter OTP code: "}
|
||||
```
|
||||
|
||||
Other states:
|
||||
|
||||
```json
|
||||
{"status": "authenticating"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"status": "authenticated"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"status": "failed", "error": "Invalid credentials"}
|
||||
```
|
||||
|
||||
## POST /api/session/{session_id}/prompt
|
||||
|
||||
Unblocks the server-side `request_input()` call.
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
{"response": "123456"}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{"status": "accepted"}
|
||||
```
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
site_name: unshackle
|
||||
site_description: Configuration reference for unshackle
|
||||
site_url: https://docs.unshackle.dev/
|
||||
repo_url: https://github.com/unshackle-dl/unshackle
|
||||
docs_dir: docs
|
||||
|
||||
theme:
|
||||
name: material
|
||||
custom_dir: overrides
|
||||
favicon: assets/favicon.svg
|
||||
icon:
|
||||
logo: custom/no_encryption
|
||||
palette:
|
||||
- media: "(prefers-color-scheme)"
|
||||
toggle:
|
||||
icon: material/link
|
||||
name: Switch to light mode
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default
|
||||
primary: indigo
|
||||
accent: indigo
|
||||
toggle:
|
||||
icon: material/toggle-switch
|
||||
name: Switch to dark mode
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
primary: black
|
||||
accent: indigo
|
||||
toggle:
|
||||
icon: material/toggle-switch-off
|
||||
name: Switch to system preference
|
||||
font:
|
||||
text: Roboto
|
||||
code: Roboto Mono
|
||||
features:
|
||||
- content.code.annotate
|
||||
- content.code.copy
|
||||
- content.tooltips
|
||||
- navigation.footer
|
||||
- navigation.indexes
|
||||
- navigation.sections
|
||||
- navigation.tabs
|
||||
- navigation.top
|
||||
- navigation.tracking
|
||||
- search.highlight
|
||||
- search.share
|
||||
- search.suggest
|
||||
- toc.follow
|
||||
|
||||
markdown_extensions:
|
||||
- abbr
|
||||
- admonition
|
||||
- attr_list
|
||||
- def_list
|
||||
- footnotes
|
||||
- md_in_html
|
||||
- tables
|
||||
- toc:
|
||||
permalink: true
|
||||
- pymdownx.betterem:
|
||||
smart_enable: all
|
||||
- pymdownx.caret
|
||||
- pymdownx.details
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
line_spans: __span
|
||||
pygments_lang_class: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.keys
|
||||
- pymdownx.mark
|
||||
- pymdownx.smartsymbols
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- pymdownx.tilde
|
||||
|
||||
plugins:
|
||||
- search
|
||||
|
||||
nav:
|
||||
- Home: README.md
|
||||
- Creating a Service: CREATING_A_SERVICE.md
|
||||
- Configuration:
|
||||
- Service Integration & Auth: SERVICE_CONFIG.md
|
||||
- Download & Processing: DOWNLOAD_CONFIG.md
|
||||
- Output & Naming: OUTPUT_CONFIG.md
|
||||
- Subtitles: SUBTITLE_CONFIG.md
|
||||
- DRM & CDM: DRM_CONFIG.md
|
||||
- Network & Proxy: NETWORK_CONFIG.md
|
||||
- Gluetun VPN: GLUETUN.md
|
||||
- Advanced & System: ADVANCED_CONFIG.md
|
||||
- REST API:
|
||||
- Overview: API.md
|
||||
- Quick Start: api/quick-start.md
|
||||
- Authentication: api/authentication.md
|
||||
- Endpoints: api/endpoints.md
|
||||
- Endpoint Map: api/endpoint-map.md
|
||||
- Download Job Lifecycle: api/download-job-lifecycle.md
|
||||
- Remote Service Sessions: api/remote-service-sessions.md
|
||||
- Client Configuration: api/client-configuration.md
|
||||
- Error Responses: api/error-responses.md
|
||||
- Reference:
|
||||
- Debug Logging: DEBUG_LOGGING.md
|
||||
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="m800-274-80-80v-206H514l-80-80h166v-80q0-50-34.5-85T481-840q-50 0-84 34.5T363-720v9l-73-73q22-61 75-98.5T481-920q83 0 141 58.5T680-720v80h40q33 0 56.5 23.5T800-560v286Zm20 246-62-62q-11 5-20 7.5T720-80H240q-33 0-56.5-23.5T160-160v-400q0-25 14.5-46t37.5-30L28-820l56-56L876-84l-56 56ZM686-160 539-309q-11 11-25.5 17t-31.5 6q-33 0-56.5-23.5T402-366q0-17 6-31.5t17-25.5L286-560h-46v400h446ZM486-360Zm131-97Z"/></svg>
|
||||
|
After Width: | Height: | Size: 511 B |
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24" fill="#26a69a"><path d="m800-274-80-80v-206H514l-80-80h166v-80q0-50-34.5-85T481-840q-50 0-84 34.5T363-720v9l-73-73q22-61 75-98.5T481-920q83 0 141 58.5T680-720v80h40q33 0 56.5 23.5T800-560v286Zm20 246-62-62q-11 5-20 7.5T720-80H240q-33 0-56.5-23.5T160-160v-400q0-25 14.5-46t37.5-30L28-820l56-56L876-84l-56 56ZM686-160 539-309q-11 11-25.5 17t-31.5 6q-33 0-56.5-23.5T402-366q0-17 6-31.5t17-25.5L286-560h-46v400h446ZM486-360Zm131-97Z"/></svg>
|
||||
|
After Width: | Height: | Size: 526 B |
+1
-1
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
||||
|
||||
[project]
|
||||
name = "unshackle"
|
||||
version = "5.2.0"
|
||||
version = "5.3.0"
|
||||
description = "Modular Movie, TV, and Music Archival Software."
|
||||
authors = [{ name = "unshackle team" }]
|
||||
requires-python = ">=3.11,<3.15"
|
||||
|
||||
@@ -0,0 +1,109 @@
|
||||
"""Tests for date-based ("daily"/sports) episode naming via Episode.air_date."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import date, datetime
|
||||
|
||||
import pytest
|
||||
|
||||
from unshackle.core.config import config
|
||||
from unshackle.core.titles.episode import Episode
|
||||
|
||||
|
||||
class DummyService:
|
||||
pass
|
||||
|
||||
|
||||
class StubMediaInfo:
|
||||
"""Minimal MediaInfo stand-in: the template context only reads track lists."""
|
||||
|
||||
video_tracks: list = []
|
||||
audio_tracks: list = []
|
||||
|
||||
|
||||
def make_episode(**overrides) -> Episode:
|
||||
kwargs = dict(
|
||||
id_="ep-0001",
|
||||
service=DummyService,
|
||||
title="The Show",
|
||||
season=2024,
|
||||
number=181,
|
||||
name="The Big Race",
|
||||
year=2024,
|
||||
)
|
||||
kwargs.update(overrides)
|
||||
return Episode(**kwargs)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def reset_template():
|
||||
saved = (config.output_template, config.folder_templates, config.folder_template)
|
||||
config.output_template = {"series": "{title}.{year?}.{season_episode}.{quality}-{tag}"}
|
||||
config.folder_templates = {}
|
||||
config.folder_template = ""
|
||||
yield config
|
||||
config.output_template, config.folder_templates, config.folder_template = saved
|
||||
|
||||
|
||||
def test_air_date_replaces_season_episode_dotted(reset_template):
|
||||
ep = make_episode(air_date=date(2024, 6, 30))
|
||||
ctx = ep._build_template_context(StubMediaInfo())
|
||||
assert ctx["season_episode"] == "2024.06.30"
|
||||
assert ctx["season"] == "2024.06.30"
|
||||
assert ctx["episode"] == ""
|
||||
assert ctx["year"] == "" # date carries the year
|
||||
assert ctx["date"] == "2024-06-30" # ISO regardless of separator
|
||||
|
||||
|
||||
def test_air_date_uses_space_separator(reset_template):
|
||||
reset_template.output_template = {"series": "{title} {season_episode} {quality}-{tag}"}
|
||||
ep = make_episode(air_date=date(2024, 6, 30))
|
||||
assert ep._build_template_context(StubMediaInfo())["season_episode"] == "2024 06 30"
|
||||
|
||||
|
||||
def test_iso_string_air_date_coerced(reset_template):
|
||||
ep = make_episode(air_date="2024-06-30")
|
||||
assert isinstance(ep.air_date, date)
|
||||
assert ep._build_template_context(StubMediaInfo())["season_episode"] == "2024.06.30"
|
||||
|
||||
|
||||
def test_year_always_dropped_in_file_when_dated(reset_template):
|
||||
"""The air date is the sole date in the filename; a distinct year is dropped too (deterministic)."""
|
||||
ep = make_episode(year=2010, air_date=date(2013, 10, 30))
|
||||
ctx = ep._build_template_context(StubMediaInfo())
|
||||
assert ctx["year"] == ""
|
||||
assert ctx["season_episode"] == "2013.10.30"
|
||||
|
||||
|
||||
def test_yearless_title_takes_year_from_date(reset_template):
|
||||
"""A title with no year still names cleanly; the date supplies the year."""
|
||||
ep = make_episode(year=None, air_date=date(2026, 6, 28))
|
||||
ctx = ep._build_template_context(StubMediaInfo())
|
||||
assert ctx["year"] == ""
|
||||
assert ctx["season_episode"] == "2026.06.28"
|
||||
|
||||
|
||||
def test_datetime_normalized_to_date(reset_template):
|
||||
"""A datetime (subclass of date) must not leak its time into the {date} token."""
|
||||
ep = make_episode(air_date=datetime(2024, 6, 30, 13, 0, 0))
|
||||
assert type(ep.air_date) is date
|
||||
assert ep._build_template_context(StubMediaInfo())["date"] == "2024-06-30"
|
||||
|
||||
|
||||
def test_no_air_date_is_unchanged(reset_template):
|
||||
"""Regression: without air_date, naming is exactly as before (presentation-only field)."""
|
||||
ep = make_episode()
|
||||
ctx = ep._build_template_context(StubMediaInfo())
|
||||
assert ctx["season_episode"] == "S2024E181"
|
||||
assert ctx["season"] == "S2024"
|
||||
assert ctx["episode"] == "E181"
|
||||
assert ctx["year"] == 2024
|
||||
assert ctx["date"] == ""
|
||||
|
||||
|
||||
def test_dated_folder_groups_by_year(reset_template):
|
||||
reset_template.folder_templates = {}
|
||||
reset_template.folder_template = ""
|
||||
folder = make_episode(air_date=date(2024, 6, 30)).get_filename(StubMediaInfo(), folder=True)
|
||||
assert "2024" in folder
|
||||
assert "S2024" not in folder # season folder is the year, not the faked season
|
||||
@@ -1296,6 +1296,8 @@ class dl:
|
||||
else:
|
||||
vaults_only = not cdm_only
|
||||
|
||||
config.decryption = resolve_decryption(config.decryption_map, config.decryption, service.__class__.__name__.upper())
|
||||
|
||||
log_event(
|
||||
"drm_mode_config",
|
||||
level="DEBUG",
|
||||
@@ -1304,6 +1306,7 @@ class dl:
|
||||
"cdm_only": cdm_only,
|
||||
"vaults_only": vaults_only,
|
||||
"mode": "CDM only" if cdm_only else ("Vaults only" if vaults_only else "Both CDM and Vaults"),
|
||||
"decryption": config.decryption,
|
||||
},
|
||||
)
|
||||
|
||||
@@ -3452,6 +3455,8 @@ class dl:
|
||||
@staticmethod
|
||||
def title_to_meta(title: Title_T) -> dict[str, Any]:
|
||||
"""Capture the title fields needed to rebuild a Title for output naming on import."""
|
||||
from datetime import date
|
||||
|
||||
from unshackle.core.titles import Episode, Movie
|
||||
|
||||
meta: dict[str, Any] = {
|
||||
@@ -3466,6 +3471,7 @@ class dl:
|
||||
number=title.number,
|
||||
name=title.name,
|
||||
year=title.year,
|
||||
air_date=title.air_date.isoformat() if isinstance(title.air_date, date) else title.air_date,
|
||||
)
|
||||
elif isinstance(title, Movie):
|
||||
meta.update(type="movie", name=title.name, year=title.year)
|
||||
|
||||
@@ -1 +1 @@
|
||||
__version__ = "5.2.0"
|
||||
__version__ = "5.3.0"
|
||||
|
||||
@@ -158,6 +158,7 @@ class Config:
|
||||
"episode",
|
||||
"season_episode",
|
||||
"episode_name",
|
||||
"date",
|
||||
"quality",
|
||||
"resolution",
|
||||
"source",
|
||||
|
||||
@@ -740,11 +740,19 @@ class HLS:
|
||||
delete: Delete the file once it's been merged.
|
||||
include_map_data: Whether to include the init map data.
|
||||
"""
|
||||
prepend = include_map_data and map_data and map_data[1]
|
||||
if len(via) == 1 and not prepend and delete:
|
||||
try:
|
||||
os.replace(via[0], to)
|
||||
return
|
||||
except OSError:
|
||||
pass
|
||||
with open(to, "wb") as x:
|
||||
if include_map_data and map_data and map_data[1]:
|
||||
if prepend:
|
||||
x.write(map_data[1])
|
||||
for file in via:
|
||||
x.write(file.read_bytes())
|
||||
with open(file, "rb") as segment:
|
||||
shutil.copyfileobj(segment, x, 1024 * 1024)
|
||||
x.flush()
|
||||
if delete:
|
||||
file.unlink()
|
||||
@@ -1005,8 +1013,8 @@ class HLS:
|
||||
else:
|
||||
with open(save_path, "wb") as f:
|
||||
for discontinuity_file in segments_to_merge:
|
||||
discontinuity_data = discontinuity_file.read_bytes()
|
||||
f.write(discontinuity_data)
|
||||
with open(discontinuity_file, "rb") as src:
|
||||
shutil.copyfileobj(src, f, 1024 * 1024)
|
||||
f.flush()
|
||||
os.fsync(f.fileno())
|
||||
discontinuity_file.unlink()
|
||||
|
||||
@@ -5,12 +5,16 @@ import logging
|
||||
import os
|
||||
import random
|
||||
import re
|
||||
import sys
|
||||
import time
|
||||
from pathlib import Path
|
||||
from typing import Optional
|
||||
|
||||
import requests
|
||||
from rich.text import Text
|
||||
|
||||
from unshackle.core.config import config
|
||||
from unshackle.core.console import console
|
||||
from unshackle.core.proxies.proxy import Proxy
|
||||
|
||||
log = logging.getLogger("proxies.proton")
|
||||
@@ -20,8 +24,9 @@ class ProtonVPN(Proxy):
|
||||
"""
|
||||
Proton VPN HTTPS proxy provider.
|
||||
|
||||
Reuses an exported account.proton.me session (the AUTH-<UID>/REFRESH-<UID> cookies) to call
|
||||
the VPN API, resolves a server by country/city, mints short-lived proxy credentials, and
|
||||
Authenticates via TV login (a self-sustaining session cached at <cache>/vpn/protonvpn.json, the
|
||||
only refreshable kind) or an exported account.proton.me cookie session (AUTH-<UID>, access only —
|
||||
re-export on expiry). Resolves a server by country/city, mints short-lived proxy credentials, and
|
||||
returns an authenticated HTTPS proxy URL (https://user:pass@server:4443).
|
||||
|
||||
Query format (after the provider prefix, e.g. "protonvpn:us"):
|
||||
@@ -33,6 +38,7 @@ class ProtonVPN(Proxy):
|
||||
"""
|
||||
|
||||
API_BASE = "https://account.proton.me/api"
|
||||
API_HOSTS = ("account.proton.me", "account.protonvpn.com")
|
||||
APP_VERSION = "browser-vpn@1.3.5"
|
||||
PROXY_PORT = 4443
|
||||
SECURE_CORE_PORT = 443
|
||||
@@ -42,15 +48,25 @@ class ProtonVPN(Proxy):
|
||||
TOKEN_DURATION = 1200 # free tier caps the granted lifetime lower
|
||||
COUNTRY_ALIASES = {"gb": "uk"} # Proton labels the United Kingdom "UK", not the ISO "GB"
|
||||
|
||||
TV_API_BASE = "https://vpn-api.proton.me"
|
||||
TV_APP_VERSION = "android_tv-vpn@5.18.75.1+play"
|
||||
TV_USER_AGENT = "ProtonVPN/5.18.75.1 (Android 11; NVIDIA SHIELD Android TV)"
|
||||
TV_ACCEPT = "application/vnd.protonmail.v1+json"
|
||||
POLL_TIMEOUT = 600.0
|
||||
POLL_INTERVAL = 5.0
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
server_map: Optional[dict[str, str]] = None,
|
||||
cookie_path: Optional[str] = None,
|
||||
cache_path: Optional[str] = None,
|
||||
timeout: float = 10.0,
|
||||
enable: bool = False,
|
||||
):
|
||||
self.server_map = {str(k).lower().strip(): str(v).lower().strip() for k, v in (server_map or {}).items()}
|
||||
self.timeout = timeout
|
||||
self.enable = enable
|
||||
self.api_base = self.API_BASE
|
||||
|
||||
self.uid: Optional[str] = None
|
||||
self.access_token: Optional[str] = None
|
||||
@@ -66,7 +82,11 @@ class ProtonVPN(Proxy):
|
||||
|
||||
def __repr__(self) -> str:
|
||||
try:
|
||||
servers = self.get_logicals() # eager so the "Loaded ProtonVPN: …" line shows the catalog size
|
||||
# only fetch the catalog if a session exists; never start TV login here (that belongs in get_proxy)
|
||||
if self.access_token or self.cookie_path.is_file() or self.cache_path.is_file():
|
||||
servers = self.get_logicals()
|
||||
else:
|
||||
servers = self.logicals or []
|
||||
except Exception:
|
||||
servers = self.logicals or []
|
||||
if not servers:
|
||||
@@ -77,6 +97,7 @@ class ProtonVPN(Proxy):
|
||||
)
|
||||
|
||||
def get_proxy(self, query: str) -> Optional[str]:
|
||||
self.ensure_session()
|
||||
server = self.resolve_server(query.strip().lower())
|
||||
if not server:
|
||||
return None
|
||||
@@ -195,15 +216,22 @@ class ProtonVPN(Proxy):
|
||||
if not self.access_token:
|
||||
self.load_session()
|
||||
if not self.access_token:
|
||||
log.error("Proton: no session available; export account.proton.me cookies to %s", self.cookie_path)
|
||||
log.error(
|
||||
"Proton: no session available; export account.proton.me cookies to %s "
|
||||
"or set proxy_providers.protonvpn.enable: true for the one-time TV login",
|
||||
self.cookie_path,
|
||||
)
|
||||
return None
|
||||
|
||||
for attempt in range(2):
|
||||
response = requests.request(method, f"{self.API_BASE}{path}", headers=self.headers(), timeout=self.timeout)
|
||||
response = requests.request(method, f"{self.api_base}{path}", headers=self.headers(), timeout=self.timeout)
|
||||
if response.status_code == 401 and attempt == 0 and self.refresh_session():
|
||||
continue
|
||||
if response.status_code == 401:
|
||||
log.error("Proton: session expired; re-export account.proton.me cookies to %s", self.cookie_path)
|
||||
log.error(
|
||||
"Proton: session expired; re-export cookies to %s or use TV login",
|
||||
self.cookie_path,
|
||||
)
|
||||
return None
|
||||
if not response.ok:
|
||||
raise ValueError(f"Proton request failed with HTTP {response.status_code}: {path}")
|
||||
@@ -222,7 +250,7 @@ class ProtonVPN(Proxy):
|
||||
if not self.refresh_token or not self.uid:
|
||||
return False
|
||||
response = requests.post(
|
||||
f"{self.API_BASE}/auth/refresh",
|
||||
f"{self.api_base}/auth/refresh",
|
||||
json={
|
||||
"UID": self.uid,
|
||||
"ResponseType": "token",
|
||||
@@ -245,34 +273,95 @@ class ProtonVPN(Proxy):
|
||||
def load_session(self) -> None:
|
||||
cached = self.load_cache()
|
||||
|
||||
api_host = self.API_BASE.split("://", 1)[-1].split("/", 1)[0]
|
||||
cookie_uid = cookie_access = cookie_refresh = None
|
||||
cookie_uid = cookie_access = cookie_host = None
|
||||
for name, value, domain in self.load_cookies():
|
||||
if domain and domain.lstrip(".") != api_host:
|
||||
host = domain.lstrip(".") if domain else ""
|
||||
if host and host not in self.API_HOSTS:
|
||||
continue
|
||||
if name.startswith("AUTH-"):
|
||||
cookie_uid, cookie_access = name[len("AUTH-") :], value
|
||||
elif name.startswith("REFRESH-"):
|
||||
cookie_refresh = value
|
||||
cookie_uid, cookie_access, cookie_host = name[len("AUTH-") :], value, host
|
||||
|
||||
# Cached tokens win, but only for the same account and not older than a re-exported cookie file
|
||||
same_account = cookie_uid is None or cached.get("uid") == cookie_uid
|
||||
# The TV cache is the only refreshable session
|
||||
cookie_newer = (
|
||||
self.cookie_path.is_file()
|
||||
and self.cache_path.is_file()
|
||||
and self.cookie_path.stat().st_mtime > self.cache_path.stat().st_mtime
|
||||
)
|
||||
if cached.get("access_token") and same_account and not cookie_newer:
|
||||
if cached.get("access_token") and not cookie_newer:
|
||||
self.uid = cached["uid"]
|
||||
self.access_token = cached["access_token"]
|
||||
self.refresh_token = cached.get("refresh_token")
|
||||
self.api_base = cached.get("api_base") or self.api_base
|
||||
return
|
||||
|
||||
self.uid, self.access_token = cookie_uid, cookie_access
|
||||
# A cookie-only re-export may lack REFRESH-; reuse the cache's refresh token if it's the same account
|
||||
self.refresh_token = cookie_refresh or (cached.get("refresh_token") if same_account else None)
|
||||
if self.uid and self.access_token:
|
||||
self.save_session()
|
||||
# Cookie session: access token only. Browser sessions can't refresh headlessly
|
||||
self.uid, self.access_token, self.refresh_token = cookie_uid, cookie_access, None
|
||||
if cookie_host:
|
||||
self.api_base = f"https://{cookie_host}/api"
|
||||
|
||||
def ensure_session(self) -> None:
|
||||
if not self.access_token:
|
||||
self.load_session()
|
||||
if not self.access_token and self.enable and sys.stdin.isatty():
|
||||
self.tv_login()
|
||||
|
||||
def tv_login(self) -> bool:
|
||||
"""Fork a TV session and have the user approve the code at proton.me/tv; tokens refresh like the cookie path."""
|
||||
headers = {
|
||||
"x-pm-appversion": self.TV_APP_VERSION,
|
||||
"x-pm-locale": "en",
|
||||
"User-Agent": self.TV_USER_AGENT,
|
||||
"Accept": self.TV_ACCEPT,
|
||||
}
|
||||
try:
|
||||
response = requests.get(f"{self.TV_API_BASE}/auth/v4/sessions/forks", headers=headers, timeout=self.timeout)
|
||||
response.raise_for_status()
|
||||
fork = response.json()
|
||||
except (requests.RequestException, ValueError) as error:
|
||||
log.error("Proton: failed to start TV login: %s", error)
|
||||
return False
|
||||
|
||||
selector, user_code = fork.get("Selector"), fork.get("UserCode")
|
||||
if not selector or not user_code:
|
||||
log.error("Proton: unexpected TV login response")
|
||||
return False
|
||||
|
||||
indent = " " * 5
|
||||
prompt = (
|
||||
"Proton: open https://account.proton.me/vpn/tv/code\n"
|
||||
f"Enter code {user_code}, then press Enter to continue..."
|
||||
)
|
||||
try:
|
||||
console.input(Text(indent + prompt.replace("\n", "\n" + indent), style="text"))
|
||||
except EOFError:
|
||||
return False
|
||||
|
||||
poll_url = f"{self.TV_API_BASE}/auth/v4/sessions/forks/{selector}"
|
||||
deadline = time.monotonic() + self.POLL_TIMEOUT
|
||||
while time.monotonic() < deadline:
|
||||
response = requests.get(poll_url, headers=headers, timeout=self.timeout)
|
||||
if response.status_code == 422: # not approved yet
|
||||
time.sleep(self.POLL_INTERVAL)
|
||||
continue
|
||||
if not response.ok:
|
||||
log.error("Proton: TV login poll failed with HTTP %s", response.status_code)
|
||||
return False
|
||||
try:
|
||||
tokens = response.json()
|
||||
except ValueError:
|
||||
log.error("Proton: unexpected TV login token response")
|
||||
return False
|
||||
uid, access, refresh = tokens.get("UID"), tokens.get("AccessToken"), tokens.get("RefreshToken")
|
||||
if uid and access and refresh:
|
||||
self.uid, self.access_token, self.refresh_token = uid, access, refresh
|
||||
self.save_session()
|
||||
log.info("Proton: TV login successful")
|
||||
return True
|
||||
log.error("Proton: TV login response missing tokens")
|
||||
return False
|
||||
|
||||
log.error("Proton: TV login not approved in time; run the command again to retry")
|
||||
return False
|
||||
|
||||
def load_cookies(self) -> list[tuple[str, str, str]]:
|
||||
"""Return [(name, value, domain), ...] from a Netscape cookies.txt or JSON cookie list."""
|
||||
@@ -315,7 +404,12 @@ class ProtonVPN(Proxy):
|
||||
return data if isinstance(data, dict) else {}
|
||||
|
||||
def save_session(self) -> None:
|
||||
tokens = {"uid": self.uid, "access_token": self.access_token, "refresh_token": self.refresh_token}
|
||||
tokens = {
|
||||
"uid": self.uid,
|
||||
"access_token": self.access_token,
|
||||
"refresh_token": self.refresh_token,
|
||||
"api_base": self.api_base,
|
||||
}
|
||||
try:
|
||||
self.cache_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
write_private(self.cache_path, json.dumps({k: v for k, v in tokens.items() if v}, indent=2))
|
||||
@@ -331,7 +425,7 @@ class ProtonVPN(Proxy):
|
||||
return cookies_dir / "vpn" / "protonvpn.txt"
|
||||
|
||||
def default_cache_path(self) -> Path:
|
||||
return Path(config.directories.cache) / "global" / "proton_tokens.json"
|
||||
return Path(config.directories.cache) / "vpn" / "protonvpn.json"
|
||||
|
||||
|
||||
def slugify(value: str) -> str:
|
||||
|
||||
@@ -297,6 +297,7 @@ def _build_title(info: Dict[str, Any], service_tag: str, fallback_id: str) -> Un
|
||||
name=info.get("name"),
|
||||
year=info.get("year"),
|
||||
language=lang,
|
||||
air_date=info.get("air_date"),
|
||||
)
|
||||
return Movie(
|
||||
id_=info.get("id", fallback_id),
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import re
|
||||
from abc import ABC
|
||||
from collections import Counter
|
||||
from datetime import date, datetime
|
||||
from typing import Any, Iterable, Optional, Union
|
||||
|
||||
from langcodes import Language
|
||||
@@ -27,6 +28,7 @@ class Episode(Title):
|
||||
language: Optional[Union[str, Language]] = None,
|
||||
data: Optional[Any] = None,
|
||||
description: Optional[str] = None,
|
||||
air_date: Optional[Union[date, str]] = None,
|
||||
) -> None:
|
||||
super().__init__(id_, service, language, data)
|
||||
|
||||
@@ -71,12 +73,22 @@ class Episode(Title):
|
||||
if year is not None and year <= 0:
|
||||
raise ValueError(f"Episode year cannot be {year}")
|
||||
|
||||
if isinstance(air_date, datetime):
|
||||
air_date = air_date.date() # avoid leaking time into the {date} token
|
||||
elif isinstance(air_date, str):
|
||||
# keep as date when parseable so naming can format it
|
||||
try:
|
||||
air_date = date.fromisoformat(air_date[:10])
|
||||
except ValueError:
|
||||
pass
|
||||
|
||||
self.title = title
|
||||
self.season = season
|
||||
self.number = number
|
||||
self.name = name
|
||||
self.year = year
|
||||
self.description = description
|
||||
self.air_date = air_date
|
||||
|
||||
def _build_template_context(self, media_info: MediaInfo, show_service: bool = True) -> dict:
|
||||
"""Build template context dictionary from MediaInfo."""
|
||||
@@ -87,9 +99,38 @@ class Episode(Title):
|
||||
context["episode"] = f"E{self.number:02}"
|
||||
context["season_episode"] = f"S{self.season:02}E{self.number:02}"
|
||||
context["episode_name"] = self.name or ""
|
||||
context["date"] = ""
|
||||
if self.air_date:
|
||||
# daily/sports: air date replaces SxxExx
|
||||
disp = self._air_date_display()
|
||||
context["season"] = disp
|
||||
context["episode"] = ""
|
||||
context["season_episode"] = disp
|
||||
context["year"] = "" # air date is the sole date in the file; folders keep the year
|
||||
context["date"] = self.air_date.isoformat() if isinstance(self.air_date, date) else str(self.air_date)
|
||||
return context
|
||||
|
||||
def _air_date_display(self) -> str:
|
||||
"""Render air_date using the series template's own separator (dots or spaces)."""
|
||||
if isinstance(self.air_date, date):
|
||||
sep = config.get_template_separator("series") if config.output_template.get("series") else "."
|
||||
return f"{self.air_date.year:04}{sep}{self.air_date.month:02}{sep}{self.air_date.day:02}"
|
||||
return str(self.air_date)
|
||||
|
||||
def _folder_season(self) -> str:
|
||||
"""Season folder label: air year for dated content, else SxxExx-style season."""
|
||||
if isinstance(self.air_date, date):
|
||||
return f"{self.air_date.year:04}"
|
||||
return f"S{self.season:02}"
|
||||
|
||||
def __str__(self) -> str:
|
||||
if self.air_date:
|
||||
return "{title}{year} {date} {name}".format(
|
||||
title=self.title,
|
||||
year=f" {self.year}" if self.year else "",
|
||||
date=self._air_date_display(),
|
||||
name=self.name or "",
|
||||
).strip()
|
||||
return "{title}{year} S{season:02}E{number:02} {name}".format(
|
||||
title=self.title,
|
||||
year=f" {self.year}" if self.year else "",
|
||||
@@ -103,7 +144,8 @@ class Episode(Title):
|
||||
template = config.get_folder_template("series")
|
||||
if template:
|
||||
context = self._build_template_context(media_info, show_service)
|
||||
context["season"] = f"S{self.season:02}"
|
||||
context["season"] = self._folder_season()
|
||||
context["year"] = self.year or "" # folders keep the year
|
||||
segments = [
|
||||
TemplateFormatter(seg).format(context) for seg in re.split(r"[\\/]", template) if seg.strip()
|
||||
]
|
||||
@@ -123,7 +165,8 @@ class Episode(Title):
|
||||
|
||||
formatter = TemplateFormatter(derived_template)
|
||||
context = self._build_template_context(media_info, show_service)
|
||||
context["season"] = f"S{self.season:02}"
|
||||
context["season"] = self._folder_season()
|
||||
context["year"] = self.year or "" # folders keep the year
|
||||
|
||||
folder_name = formatter.format(context)
|
||||
|
||||
@@ -134,7 +177,7 @@ class Episode(Title):
|
||||
name = f"{self.title}"
|
||||
if self.year:
|
||||
name += f" {self.year}"
|
||||
name += f" S{self.season:02}"
|
||||
name += f" {self._folder_season()}"
|
||||
return sanitize_filename(name, " ")
|
||||
|
||||
formatter = TemplateFormatter(config.output_template["series"])
|
||||
@@ -168,13 +211,17 @@ class Series(SortedKeyList, ABC):
|
||||
)
|
||||
for episode in self:
|
||||
if episode.season == season:
|
||||
label = (
|
||||
episode._air_date_display()
|
||||
if episode.air_date
|
||||
else str(episode.number).zfill(len(str(episodes)))
|
||||
)
|
||||
if episode.name:
|
||||
season_tree.add(
|
||||
f"[bold]{str(episode.number).zfill(len(str(episodes)))}.[/] "
|
||||
f"[bright_black]{episode.name}"
|
||||
)
|
||||
season_tree.add(f"[bold]{label}.[/] [bright_black]{episode.name}")
|
||||
elif episode.air_date:
|
||||
season_tree.add(f"[bright_black]{label}")
|
||||
else:
|
||||
season_tree.add(f"[bright_black]Episode {str(episode.number).zfill(len(str(episodes)))}")
|
||||
season_tree.add(f"[bright_black]Episode {label}")
|
||||
|
||||
return tree
|
||||
|
||||
|
||||
@@ -1,13 +1,14 @@
|
||||
"""
|
||||
DV fixup for HLS composite HEVC streams.
|
||||
DV exposure for HLS composite HEVC streams.
|
||||
|
||||
Some services deliver DV Profile 8.1 in a stream whose primary CODECS is plain
|
||||
hvc1, with DV advertised only via SUPPLEMENTAL-CODECS. The fMP4 carries DV RPU NALs but
|
||||
the container does not signal DV, so muxing produces an MKV that mediainfo and DV-capable
|
||||
TVs see as plain HDR10/HDR10+.
|
||||
hvc1, with DV advertised only via SUPPLEMENTAL-CODECS. The fMP4 carries valid DV RPU NALs
|
||||
but the container does not signal DV, so muxing the MP4 directly produces an MKV that
|
||||
mediainfo and DV-capable TVs see as plain HDR10/HDR10+.
|
||||
|
||||
A dovi_tool extract-rpu / inject-rpu round-trip rewrites the bitstream so it is recognised
|
||||
as DV after muxing. HDR10+ SEI NALs and HDR10 base layer signaling survive untouched.
|
||||
The RPU is already valid — only the container's DV signaling is lost. Demuxing the
|
||||
elementary HEVC stream (ffmpeg -c:v copy) exposes the in-stream RPU to mkvmerge, which then
|
||||
signals DV in the muxed MKV. No dovi_tool extract/inject round-trip is needed.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -19,11 +20,9 @@ from typing import TYPE_CHECKING
|
||||
from rich.padding import Padding
|
||||
from rich.rule import Rule
|
||||
|
||||
from unshackle.core.binaries import FFMPEG, DoviTool
|
||||
from unshackle.core.config import config
|
||||
from unshackle.core.binaries import FFMPEG
|
||||
from unshackle.core.console import console
|
||||
from unshackle.core.utilities import log_event
|
||||
from unshackle.core.utils import dovi
|
||||
from unshackle.core.utils.subprocess import run_step
|
||||
|
||||
if TYPE_CHECKING:
|
||||
@@ -31,46 +30,37 @@ if TYPE_CHECKING:
|
||||
|
||||
|
||||
class DVFixup:
|
||||
"""Round-trip a DV-composite HEVC track through dovi_tool to restore DV signaling."""
|
||||
"""Demux a DV-composite HEVC track to its elementary stream so mkvmerge exposes DV."""
|
||||
|
||||
def __init__(self, video: "Video") -> None:
|
||||
self.log = logging.getLogger("dv-fixup")
|
||||
self.video = video
|
||||
|
||||
if not DoviTool:
|
||||
raise EnvironmentError("dovi_tool is required for DV-composite fixup but was not found.")
|
||||
if not FFMPEG:
|
||||
raise EnvironmentError("ffmpeg is required for DV-composite fixup but was not found.")
|
||||
if not video.path or not Path(video.path).exists():
|
||||
raise ValueError(f"Video track {video.id} was not downloaded before DV fixup.")
|
||||
|
||||
def run(self) -> Path:
|
||||
"""Execute the fixup. Returns the DV-signaled HEVC path, or the original
|
||||
source path on any failure so muxing can proceed with the as-downloaded file."""
|
||||
"""Demux the elementary HEVC so mkvmerge exposes its DV RPU. Returns the
|
||||
elementary-stream path, or the original source on any failure so muxing can
|
||||
proceed with the as-downloaded file."""
|
||||
source = Path(self.video.path)
|
||||
height = self.video.height or 0
|
||||
console.print(Padding(Rule(f"[rule.text]DV Composite Fixup ({height}p)"), (1, 2)))
|
||||
|
||||
fixed_hevc = source.with_name(f"{self.video.id}.dv.hevc")
|
||||
if fixed_hevc.exists() and fixed_hevc.stat().st_size > 0:
|
||||
self.log.info("✓ DV signaling already restored (reusing existing fixup)")
|
||||
self.log.info("✓ DV signaling already exposed (reusing existing demux)")
|
||||
return fixed_hevc
|
||||
|
||||
tmp = config.directories.temp
|
||||
tmp.mkdir(parents=True, exist_ok=True)
|
||||
suffix = f"{self.video.id}_{height or 'na'}"
|
||||
raw_hevc = tmp / f"dvfix_{suffix}.hevc"
|
||||
rpu = tmp / f"dvfix_{suffix}_rpu.bin"
|
||||
|
||||
try:
|
||||
run_step(
|
||||
[FFMPEG, "-nostdin", "-y", "-i", source, "-c:v", "copy", "-f", "hevc", raw_hevc],
|
||||
status="Demuxing HEVC bitstream...",
|
||||
output=raw_hevc,
|
||||
[FFMPEG, "-nostdin", "-y", "-i", source, "-c:v", "copy", "-f", "hevc", fixed_hevc],
|
||||
status="Demuxing HEVC bitstream to expose DV...",
|
||||
output=fixed_hevc,
|
||||
label="ffmpeg demux",
|
||||
)
|
||||
dovi.extract_rpu_with_fallback(raw_hevc, rpu)
|
||||
dovi.inject_rpu(raw_hevc, rpu, fixed_hevc, status="Re-injecting DV RPU with proper signaling...")
|
||||
except Exception as e:
|
||||
self.log.warning(f"DV fixup failed ({e}); muxing source as-is.")
|
||||
log_event(
|
||||
@@ -79,14 +69,10 @@ class DVFixup:
|
||||
message="DV fixup failed; falling back to source",
|
||||
context={"error": str(e), "source": str(source)},
|
||||
)
|
||||
for leftover in (raw_hevc, rpu, fixed_hevc):
|
||||
leftover.unlink(missing_ok=True)
|
||||
fixed_hevc.unlink(missing_ok=True)
|
||||
return source
|
||||
|
||||
for leftover in (raw_hevc, rpu):
|
||||
leftover.unlink(missing_ok=True)
|
||||
|
||||
self.log.info("✓ DV signaling restored")
|
||||
self.log.info("✓ DV signaling exposed")
|
||||
log_event(
|
||||
"dv_fixup",
|
||||
level="INFO",
|
||||
|
||||
@@ -433,6 +433,35 @@ class Video(Track):
|
||||
if not vui:
|
||||
return False
|
||||
|
||||
# Skip the rewrite when the bitstream VUI already matches the target — avoids a full
|
||||
# bitstream pass on services that already ship correct colour metadata
|
||||
expected = {
|
||||
Video.Range.HDR10: ("bt2020", "smpte2084", "bt2020nc"),
|
||||
Video.Range.HDR10P: ("bt2020", "smpte2084", "bt2020nc"),
|
||||
Video.Range.HLG: ("bt2020", "arib-std-b67", "bt2020nc"),
|
||||
}.get(self.range)
|
||||
if expected and binaries.FFProbe:
|
||||
probe = subprocess.run(
|
||||
[
|
||||
binaries.FFProbe,
|
||||
"-v",
|
||||
"error",
|
||||
"-select_streams",
|
||||
"v:0",
|
||||
"-show_entries",
|
||||
"stream=color_primaries,color_transfer,color_space",
|
||||
"-of",
|
||||
"default=noprint_wrappers=1",
|
||||
str(self.path),
|
||||
],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
vals = dict(line.split("=", 1) for line in probe.stdout.splitlines() if "=" in line)
|
||||
current = (vals.get("color_primaries"), vals.get("color_transfer"), vals.get("color_space"))
|
||||
if current == expected:
|
||||
return False
|
||||
|
||||
if not binaries.FFMPEG:
|
||||
raise EnvironmentError('FFmpeg executable "ffmpeg" was not found but is required for this call.')
|
||||
|
||||
|
||||
@@ -25,15 +25,14 @@ from unshackle.core.utilities import is_close_match
|
||||
|
||||
class EXAMPLE(Service):
|
||||
"""
|
||||
\b
|
||||
Reference service for domain.com - a deliberately exhaustive showcase of
|
||||
EVERYTHING an unshackle service can touch. It is NOT meant to run against a
|
||||
real API; it exists so a new service author can see one canonical example of
|
||||
every framework feature in one place.
|
||||
|
||||
\b
|
||||
Version: 2.0.0
|
||||
Author: sp4rk.y
|
||||
Date: 2026-06-28
|
||||
Authorization: Cookies + Credentials
|
||||
Geofence: US, UK
|
||||
Robustness:
|
||||
@@ -44,14 +43,12 @@ class EXAMPLE(Service):
|
||||
SL3000: 2160p
|
||||
ClearKey: 1080p (DRM-free fallback)
|
||||
|
||||
\b
|
||||
Tips:
|
||||
- Input may be a full URL or a bare ID/slug:
|
||||
https://domain.com/details/20914 -> 20914
|
||||
- -m / --movie forces movie parsing when the API type is ambiguous.
|
||||
- -d / --device selects a client profile block from config.yaml.
|
||||
|
||||
\b
|
||||
Feature map (where to look):
|
||||
__init__ TrackRequest read/override, CDM-aware codec gating
|
||||
authenticate cookies AND credentials, JWT decode, token cache+refresh
|
||||
@@ -286,6 +283,8 @@ class EXAMPLE(Service):
|
||||
year=metadata["releaseYear"] if metadata.get("releaseYear", 0) > 0 else None,
|
||||
language=original_lang,
|
||||
data=ep,
|
||||
# daily/sports: name by date instead of SxxExx (date or ISO string)
|
||||
# air_date=ep.get("airDate"),
|
||||
)
|
||||
)
|
||||
return Series(episodes)
|
||||
|
||||
Reference in New Issue
Block a user