Compare commits

..
Author SHA1 Message Date
imSp4rky 4ebe41fafd feat(tracks): add subtitle.type_priority config for variant ordering
Optional ranking of forced/normal/sdh per language, mirroring audio.codec_priority; first track gets the default flag, so this also picks the default subtitle. Unset = existing behavior.
2026-07-07 17:36:58 -06:00
imSp4rky 1dba4a8f82 fix(core): decode subprocess output as UTF-8 with replacement
Strict UTF-8 decode of external tool output (ffmpeg/shaka/mp4decrypt) crashed reader threads on non-English Windows (cp950/Big5).
2026-07-07 09:23:05 -06:00
imSp4rky 5cd50544a8 fix(remote): harden serve API access control and input handling
Bind sessions and download jobs to the API key (not source IP), reject path-traversal cache keys, bound decompression of peer-supplied blobs, gate the CDM device before the vault fallback, and compare API keys in constant time.
2026-07-06 23:54:05 -06:00
imSp4rky 84d9b92530 docs: expand config reference and genericize service names 2026-07-06 22:50:38 -06:00
54 changed files with 794 additions and 978 deletions
+5 -5
View File
@@ -32,14 +32,14 @@ is a service**, and the folder name is the service **tag**:
```text
services/
└── EXAMPLE/
├── __init__.py # required — defines the service class
└── config.yaml # optional — per-service configuration
├── __init__.py # required - defines the service class
└── config.yaml # optional - per-service configuration
```
Two rules the loader enforces:
1. **The class name must exactly match the folder/tag name.** Folder `AMZN` must
define `class AMZN`. A mismatch raises a `RuntimeError`.
1. **The class name must exactly match the folder/tag name.** Folder `EXAMPLE` must
define `class EXAMPLE`. A mismatch raises a `RuntimeError`.
2. **List order is priority.** The first services path to define a given tag
wins; later duplicates are shadowed. Put your own local overrides *last* to
use them as fallbacks, or *first* to override a repo.
@@ -546,7 +546,7 @@ from unshackle.core.tracks import Chapters, Tracks
class MYSVC(Service):
"""
MyService — https://myservice.com
MyService - https://myservice.com
\b
Usage: unshackle dl MYSVC <title-id-or-url>
+3 -3
View File
@@ -59,7 +59,7 @@ serve:
username: alice
devices: ["my_widevine_device"] # Widevine (.wvd) devices this key may use
playready_devices: ["my_playready_prd"] # PlayReady (.prd) devices this key may use
services: ["AMZN", "NF"] # optional per-key service allowlist
services: ["EXAMPLE1", "EXAMPLE2"] # optional per-key service allowlist
a-secret-key-for-bob:
username: bob
devices: ["my_widevine_device"]
@@ -217,11 +217,11 @@ The effective allowlist for a request is:
```yaml title="Restricting services"
serve:
api_secret: "admin-key"
services: ["AMZN", "NF", "DSNP"] # global ceiling for all keys
services: ["EXAMPLE1", "EXAMPLE2", "EXAMPLE3"] # global ceiling for all keys
users:
limited-key:
username: limited
services: ["AMZN"] # this key ends up allowed only AMZN
services: ["EXAMPLE1"] # this key ends up allowed only EXAMPLE1
```
Endpoints that name a service (listing services, searching, listing titles/tracks, downloading, profiles, history, and remote sessions) all filter against this allowlist. A request for a service outside the key's allowlist is rejected as an invalid service. Service tags are matched after normalization, so casing and aliases resolve consistently.
+26 -26
View File
@@ -130,8 +130,8 @@ Search a service for titles by query string. The service must implement `search(
| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `service` | string | yes | — | Service tag. |
| `query` | string | yes | — | Search query. |
| `service` | string | yes | - | Service tag. |
| `query` | string | yes | - | Search query. |
| `profile` | string | no | `null` | Credential/cookie profile to use. |
| `proxy` | string | no | `null` | Proxy URI or country code. |
| `no_proxy` | boolean | no | `false` | Force-disable all proxy use. |
@@ -164,7 +164,7 @@ Search a service for titles by query string. The service must implement `search(
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Search completed. |
| `200` | - | Search completed. |
| `400` | `INVALID_PARAMETERS` | Missing `query`. |
| `400` | `INVALID_SERVICE` | Unknown or disallowed service. |
| `400` | `INVALID_PROXY` | Proxy could not be resolved. |
@@ -222,7 +222,7 @@ Each serialized title carries `type` (`"episode"`, `"movie"`, or `"other"`), `na
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Titles returned. |
| `200` | - | Titles returned. |
| `400` | `INVALID_INPUT` | Missing `service` or `title_id`. |
| `400` | `INVALID_SERVICE` | Unknown or disallowed service. |
| `401` | `AUTH_FAILED` | Authentication with the service failed. |
@@ -242,7 +242,7 @@ List the video, audio, and subtitle tracks for a title. For series, you can scop
| `wanted` | string | no | Episode/season range (e.g. `"S01E01-S01E03"`). |
| `season` | int/string | no | Season number (combined with `episode`). |
| `episode` | int/string | no | Episode number (combined with `season`). |
| `profile`, `proxy`, `no_proxy`, `cdm_type` | — | no | As on `list-titles`. |
| `profile`, `proxy`, `no_proxy`, `cdm_type` | - | no | As on `list-titles`. |
When both `season` and `episode` are given, they are combined into a `"{season}x{episode}"` selector.
@@ -297,7 +297,7 @@ The `drm` array on a track is a list of `{type, pssh?, kids?, content_keys?, lic
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Tracks returned. |
| `200` | - | Tracks returned. |
| `400` | `INVALID_INPUT` | Missing `service` or `title_id`. |
| `400` | `INVALID_PARAMETERS` | Invalid `wanted` range. |
| `400` | `INVALID_SERVICE` | Unknown or disallowed service. |
@@ -378,7 +378,7 @@ Create a download job. Requires `service` and `title_id`; every other field is a
| `best_available` | boolean | `false` | Fall back to best available. |
| `repack` | boolean | `false` | Add REPACK tag. |
| `tag` | string | `null` | Release group tag. |
| `tmdb_id` / `imdb_id` / `animeapi_id` | — | `null` | External ID overrides for tagging. |
| `tmdb_id` / `imdb_id` / `animeapi_id` | - | `null` | External ID overrides for tagging. |
| `enrich` | boolean | `false` | Override title/year from external source. |
| `output_dir` | string | `null` | Override output directory. |
| `no_cache` / `reset_cache` | boolean | `false` | Title cache controls. |
@@ -395,7 +395,7 @@ Create a download job. Requires `service` and `title_id`; every other field is a
| Status | Error code | Meaning |
| --- | --- | --- |
| `202` | — | Job queued. |
| `202` | - | Job queued. |
| `400` | `INVALID_INPUT` | Missing `service`/`title_id` or malformed JSON. |
| `400` | `INVALID_PARAMETERS` | A parameter failed validation. |
| `400` | `INVALID_SERVICE` | Unknown or disallowed service. |
@@ -409,8 +409,8 @@ List download jobs, with optional filtering and sorting.
| Param | Values | Default | Description |
| --- | --- | --- | --- |
| `status` | `queued`, `downloading`, `completed`, `failed`, `cancelled` | — | Filter by status. |
| `service` | service tag | — | Filter by service. |
| `status` | `queued`, `downloading`, `completed`, `failed`, `cancelled` | - | Filter by status. |
| `service` | service tag | - | Filter by service. |
| `sort_by` | `created_time`, `started_time`, `completed_time`, `progress`, `status`, `service` | `created_time` | Sort field. |
| `sort_order` | `asc`, `desc` | `desc` | Sort direction. |
| `full` | `true`, `false` | `false` | Include full per-job details. |
@@ -454,7 +454,7 @@ With `full=true`, each job additionally includes `parameters` (with secrets reda
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Jobs returned. |
| `200` | - | Jobs returned. |
| `400` | `INVALID_PARAMETERS` | Invalid `sort_by` or `sort_order`. |
### `GET /api/download/jobs/{job_id}`
@@ -463,7 +463,7 @@ Fetch a single job with full details (equivalent to a `full=true` list entry).
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Job returned. |
| `200` | - | Job returned. |
| `404` | `JOB_NOT_FOUND` | No such job. |
### `DELETE /api/download/jobs/{job_id}`
@@ -478,8 +478,8 @@ Cancel or remove a job. The behaviour depends on the job's current state:
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Job cancelled. |
| `204` | — | Terminal job removed (empty body). |
| `200` | - | Job cancelled. |
| `204` | - | Terminal job removed (empty body). |
| `400` | `INVALID_PARAMETERS` | Job is in a state that cannot be cancelled. |
| `404` | `JOB_NOT_FOUND` | No such job. |
@@ -512,7 +512,7 @@ Enqueue a **new** job that reuses a terminal job's service, title, and parameter
| Status | Error code | Meaning |
| --- | --- | --- |
| `202` | — | New job queued. |
| `202` | - | New job queued. |
| `404` | `JOB_NOT_FOUND` | No such job. |
| `409` | `CONFLICT` | Job is not in a terminal state. |
| `400` | `INVALID_SERVICE` | Service is no longer allowed. |
@@ -530,7 +530,7 @@ Move a queued job to the front of the download queue.
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Job moved to front. |
| `200` | - | Job moved to front. |
| `404` | `JOB_NOT_FOUND` | No such job. |
| `409` | `CONFLICT` | Job is not queued. |
@@ -593,7 +593,7 @@ Read the persisted history of jobs that reached a terminal state, newest first.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | int (≥ 1) | `100` | Maximum entries to return. |
| `service` | string | — | Case-insensitive service filter. |
| `service` | string | - | Case-insensitive service filter. |
=== "Response `200`"
@@ -619,7 +619,7 @@ Read the persisted history of jobs that reached a terminal state, newest first.
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | History returned. |
| `200` | - | History returned. |
| `400` | `INVALID_PARAMETERS` | Invalid `limit`. |
### `DELETE /api/history/{job_id}`
@@ -628,7 +628,7 @@ Remove a single persisted history entry. Returns **`204 No Content`** (empty bod
| Status | Error code | Meaning |
| --- | --- | --- |
| `204` | — | Entry removed (empty body). |
| `204` | - | Entry removed (empty body). |
| `404` | `NOT_FOUND` | No such entry (or outside your allowlist). |
### `POST /api/maintenance/clear-cache` and `POST /api/maintenance/clear-temp`
@@ -648,7 +648,7 @@ The `409` guard is about active file I/O, not an arbitrary lock: an in-flight jo
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Directory cleared. |
| `200` | - | Directory cleared. |
| `409` | `CONFLICT` | A download is currently active. |
### `POST /api/maintenance/refresh-services`
@@ -718,7 +718,7 @@ Create a session for a service and title. Authentication runs asynchronously in
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Session created; authentication in progress. |
| `200` | - | Session created; authentication in progress. |
| `400` | `INVALID_INPUT` | Missing `service` or `title_id`. |
| `400` | `INVALID_SERVICE` | Unknown or disallowed service. |
@@ -752,7 +752,7 @@ Poll for the authentication status and any pending interactive prompt (OTP, PIN,
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Status returned. |
| `200` | - | Status returned. |
| `403` | `FORBIDDEN` | Request IP differs from the session creator. |
| `404` | `SESSION_NOT_FOUND` | No such session. |
@@ -768,7 +768,7 @@ Submit a response to a pending prompt. Body: `{ "response": "..." }` (required).
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Response accepted. |
| `200` | - | Response accepted. |
| `400` | `INVALID_INPUT` | Missing `response`, or no prompt is pending. |
| `404` | `SESSION_NOT_FOUND` | No such session. |
@@ -810,7 +810,7 @@ Get tracks and chapters for a specific title within the session. Body: `{ "title
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Tracks returned. |
| `200` | - | Tracks returned. |
| `400` | `INVALID_INPUT` | Missing or unknown `title_id`. |
| `404` | `SESSION_NOT_FOUND` | No such session. |
@@ -830,7 +830,7 @@ Resolve the download URL, DRM info, headers, cookies, and raw track data for sel
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | Segment info returned. |
| `200` | - | Segment info returned. |
| `400` | `INVALID_INPUT` | Missing `track_ids`. |
| `404` | `TRACK_NOT_FOUND` | An unknown track ID was requested. |
@@ -876,7 +876,7 @@ Acquire DRM keys. Two modes are supported via the `mode` field.
| Status | Error code | Meaning |
| --- | --- | --- |
| `200` | — | License/keys returned. |
| `200` | - | License/keys returned. |
| `400` | `INVALID_INPUT` | Missing challenge/PSSH, or no CDM device configured for the key. |
| `400` | `INVALID_PARAMETERS` | Unsupported `drm_type`. |
| `404` | `TRACK_NOT_FOUND` | Unknown track ID. |
+1 -1
View File
@@ -139,7 +139,7 @@ uncategorised exception bubbles up, the server runs it through a classifier that
inspects the exception type and message and maps it to the most appropriate code.
The classification is keyword-based, checked in order:
| If the error mentions… | It becomes | Retryable |
| If the error mentions... | It becomes | Retryable |
|---|---|---|
| auth, login, credential, unauthorized, forbidden, token | `AUTH_FAILED` (401) | no |
| connection, timeout, network, unreachable, socket, dns, resolve (or `ConnectionError`, `TimeoutError`, `URLError`, `SSLError`) | `NETWORK_ERROR` (503) | yes |
+1 -1
View File
@@ -211,7 +211,7 @@ every request except `/api/health`:
curl -X POST http://127.0.0.1:8786/api/search \
-H "X-Secret-Key: your-api-secret" \
-H "Content-Type: application/json" \
-d '{"service": "NF", "query": "example"}'
-d '{"service": "EXAMPLE", "query": "example"}'
```
A missing or unknown key returns `401`. The full model, including per-key service
+2 -2
View File
@@ -86,7 +86,7 @@ curl -X POST http://127.0.0.1:8786/api/download \
-H "X-Secret-Key: your-api-secret" \
-H "Content-Type: application/json" \
-d '{
"service": "NF",
"service": "EXAMPLE",
"title_id": "81234567",
"quality": ["1080"],
"range": ["HDR10"]
@@ -228,7 +228,7 @@ state, and this is important because the response differs:
|---|---|---|
| `queued` or `downloading` | The job is cancelled. A running download's worker process is terminated. | `200` with `{"status": "success", "message": "Job cancelled"}` |
| `completed`, `failed`, or `cancelled` (terminal) | The job is **removed** from the manager entirely. | `204 No Content`, empty body |
| Not found | — | `404` with error code `JOB_NOT_FOUND` |
| Not found | - | `404` with error code `JOB_NOT_FOUND` |
In other words, `DELETE` on a live job *cancels* it, while `DELETE` on an already
finished job *deletes it from the list*. This dual meaning is deliberate: one verb
+3 -3
View File
@@ -161,7 +161,7 @@ If the key is missing or wrong, you get a `401` with a plain body:
```
!!! warning "Two error shapes exist"
The authentication middleware returns the short `{"status": 401, "message": "..."}` shape shown above. Every **other** error the API produces uses the richer structured shape (`error_code`, `timestamp`, `details`, …) described in [Error handling](#error-handling). A robust client should handle both.
The authentication middleware returns the short `{"status": 401, "message": "..."}` shape shown above. Every **other** error the API produces uses the richer structured shape (`error_code`, `timestamp`, `details`, ...) described in [Error handling](#error-handling). A robust client should handle both.
The `tag` value for the service you want is the identifier you pass as `service` in the calls below.
@@ -225,8 +225,8 @@ The request body accepts the full download parameter set. A few of the most usef
| Field | Default | Meaning |
| --- | --- | --- |
| `service` | — | Service tag (required) |
| `title_id` | — | Title identifier (required) |
| `service` | - | Service tag (required) |
| `title_id` | - | Title identifier (required) |
| `profile` | `null` | Named credential/cookie profile to use |
| `quality` | `[]` | Resolution(s), e.g. `[1080]`; empty means best available |
| `vcodec` | `null` | Video codec, e.g. `"H265"` |
+12 -12
View File
@@ -65,7 +65,7 @@ remote_services:
server_cdm: false
# Optional: per-service config overrides applied locally (title_map, cdm, etc.)
services:
AMZN:
EXAMPLE:
title_map:
"0ABCDEF": "The Show (Renamed Locally)"
```
@@ -87,13 +87,13 @@ remote_services:
If exactly one server is configured, unshackle uses it implicitly:
```bash
unshackle dl AMZN 0ABCDEF
unshackle dl EXAMPLE 0ABCDEF
```
If **more than one** server is configured, you must pick one with `--server`:
```bash
unshackle dl --server my_server AMZN 0ABCDEF
unshackle dl --server my_server EXAMPLE 0ABCDEF
```
With no `remote_services` configured at all, unshackle raises a clear error telling
@@ -280,10 +280,10 @@ All routes are exposed even in `--remote-only` server mode. Paths use the
The response returns **before** authentication finishes:
```json
{ "session_id": "…uuid4…", "service": "AMZN", "status": "authenticating" }
{ "session_id": "...uuid4...", "service": "EXAMPLE", "status": "authenticating" }
```
Authentication runs on a background thread (`asyncio.to_thread(authenticate, …)`).
Authentication runs on a background thread (`asyncio.to_thread(authenticate, ...)`).
The session starts in `AUTHENTICATING`; the client must poll the prompt endpoint
until it reaches `authenticated` (or `failed`).
@@ -306,11 +306,11 @@ layer.
{ "status": "authenticated" }
{ "status": "authenticating" }
{ "status": "pending_input", "prompt": "Enter code: " }
{ "status": "failed", "error": "…message…" }
{ "status": "failed", "error": "...message..." }
```
A missing session returns `404 SESSION_NOT_FOUND`; an IP mismatch returns
`403 FORBIDDEN`. `POST /api/session/{id}/prompt` takes `{ "response": "…" }` and
`403 FORBIDDEN`. `POST /api/session/{id}/prompt` takes `{ "response": "..." }` and
returns `{ "status": "accepted" }`; posting with no pending prompt is an
`INVALID_INPUT` error.
@@ -364,7 +364,7 @@ and base64-encoding, **excluding** `titles_*` files) and returns them under a
`cache` key so the client can persist refreshed tokens:
```json
{ "status": "ok", "cache": { "tokens": "…base64(zlib(bytes))…" } }
{ "status": "ok", "cache": { "tokens": "...base64(zlib(bytes))..." } }
```
### Session info response
@@ -373,8 +373,8 @@ and base64-encoding, **excluding** `titles_*` files) and returns them under a
```json
{
"session_id": "…",
"service": "AMZN",
"session_id": "...",
"service": "EXAMPLE",
"valid": true,
"expires_in": 300,
"track_count": 12,
@@ -410,7 +410,7 @@ session API and a good template for any client.
## Troubleshooting
!!! example "\"Could not connect to remote server … Is it running?\""
!!! example "\"Could not connect to remote server ... Is it running?\""
The client couldn't reach the URL. Confirm `unshackle serve` is running on the
server, the `url`/port in `remote_services` are correct (default port `8786`),
and any firewall or reverse proxy allows the connection.
@@ -426,6 +426,6 @@ session API and a good template for any client.
prompts you, check that credentials/cookies forwarded from the client are valid
for the service.
!!! example "\"Multiple remote services configured. Use --server …\""
!!! example "\"Multiple remote services configured. Use --server ...\""
You have more than one entry under `remote_services`. Pass `--server <name>`
to pick one.
+3 -3
View File
@@ -25,9 +25,9 @@ your service, in order:
```text
Service.get_titles → which movies / episodes / songs exist
│
Service.get_tracks → fetch a manifest for one title …
Service.get_tracks → fetch a manifest for one title ...
│
manifest.to_tracks → … parsed into Video / Audio / Subtitle tracks
manifest.to_tracks → ... parsed into Video / Audio / Subtitle tracks
│
Track.download → fetch + merge segments (core-driven)
│
@@ -310,7 +310,7 @@ A typical `get_tracks` therefore looks like fetching the manifest text with
- **HLS**: set `track.OnSegmentFilter(segment)` to drop unwanted segments (ads/bumpers).
- **DASH**: pass a `period_filter` callable to `to_tracks` to drop whole periods.
Amazon caching-breadth periods and non-`content` segment types are dropped automatically.
Caching-breadth periods some services emit and non-`content` segment types are dropped automatically.
### Format gotchas worth knowing
+37 -2
View File
@@ -63,11 +63,11 @@ tag: MYGRP
# Default Widevine/PlayReady device to use, with per-service overrides
cdm:
default: my_device_l3
AMZN: my_device_l1
EXAMPLE: my_device_l1
# Per-service login details (service tag -> "username:password")
credentials:
AMZN: my_email@example.com:hunter2
EXAMPLE: my_email@example.com:hunter2
# Default HTTP headers merged into every request
headers:
@@ -94,6 +94,41 @@ For the full list with types and defaults, see the [Configuration Reference](../
!!! warning "Unknown keys are silently ignored"
unshackle does not validate your config against a schema. If you misspell a key, it is simply skipped and the default is used. You will not get an error. Double-check key names (and their nesting) if a setting does not seem to apply.
## Setting download defaults (`dl:`)
If you always pass the same `dl` flags (a language, a resolution, a codec), put them under a
`dl:` key once and unshackle applies them to every download. Any flag from
[Downloading](../guide/downloading.md) works here; the key is the flag's long name with dashes
turned into underscores (`--best-available` → `best_available`).
```yaml title="unshackle.yaml"
dl:
lang: [en] # -l en
quality: [1080] # -q 1080
vcodec: [H265] # -v H265
sub_format: srt # convert subtitles to SRT
downloads: 2 # two tracks at once
```
You can still override any of these on the command line for a one-off; an explicit flag
always beats the config default. You can also scope defaults to a single service by nesting a
`dl:` block under it:
```yaml title="Per-service defaults"
dl:
lang: [en] # default for everything
services:
EXAMPLE:
dl:
lang: [en, ja] # Example downloads English + Japanese
```
!!! tip "A few keys are named after the flag's internal name"
Most keys are obvious, but set these exact ones: `range` (`-r`), `list` (`--list`),
`tmdb_id` (`--tmdb`), `imdb_id` (`--imdb`), `no_atmos` (`--noatmos`), and `output_dir`
(`-o`). The [Configuration Reference](../reference/configuration.md#dl) has the full list
and every available key.
## The directory layout
The `directories` key controls where unshackle reads and writes its various files. Each directory has a sensible default, and you can override most of them by giving a new path. Paths support `~` for your home directory.
+17 -17
View File
@@ -79,7 +79,7 @@ full set of valid variables, including `resolution`, `video`, `audio`, `hdr`,
## 3. Add a service
The service tag you pass to `dl` (like `NF`) maps to a **service module**, a small
The service tag you pass to `dl` (like `EXAMPLE`) maps to a **service module**, a small
plugin that knows how to talk to one streaming platform. unshackle ships without
any bundled services, so you add the one(s) you want.
@@ -90,14 +90,14 @@ that exact same name.
=== "Local folder"
Drop a service folder into your services directory. A service tagged `NF`
Drop a service folder into your services directory. A service tagged `EXAMPLE`
lives at:
```
<services>/NF/__init__.py # defines a class named NF
<services>/EXAMPLE/__init__.py # defines a class named EXAMPLE
```
Once the folder is in place, the tag `NF` is immediately available to `dl`,
Once the folder is in place, the tag `EXAMPLE` is immediately available to `dl`,
`search`, and the other service-aware commands.
=== "Git repository"
@@ -140,7 +140,7 @@ covers everything else:
```yaml title="unshackle.yaml"
cdm:
default: my_device # the .wvd file's name, without the extension
NF: my_other_device # override for a specific service
EXAMPLE: my_other_device # override for a specific service
```
PlayReady works the same way with `.prd` files created and managed by the
@@ -157,14 +157,14 @@ Services that require a login read either **cookies** or **credentials**.
- **Cookies**: export the service's cookies to a Netscape-format text file and
place it in your cookies directory. unshackle looks for, in order:
`cookies/{SERVICE}.txt`, then `cookies/{SERVICE}/{profile}.txt`, then
`cookies/{SERVICE}/default.txt`. So a file at `cookies/NF.txt` is picked up
automatically for the `NF` service.
`cookies/{SERVICE}/default.txt`. So a file at `cookies/EXAMPLE.txt` is picked up
automatically for the `EXAMPLE` service.
- **Credentials**: store a username and password per service in your config:
```yaml title="unshackle.yaml"
credentials:
NF: "email@example.com:your-password"
EXAMPLE: "email@example.com:your-password"
```
Use the `-p/--profile` flag to switch between multiple accounts for the same
@@ -177,14 +177,14 @@ If you have a URL or ID already, skip this. Otherwise, search the service for a
title and note the `id` it prints, since that is what you feed to `dl`:
```shell
unshackle search NF "The Office"
unshackle search EXAMPLE "My Show"
```
You can also list what a service exposes for a given title without downloading:
```shell
unshackle dl --list-titles NF 81234567 # show seasons/episodes
unshackle dl --list NF 81234567 # show available tracks
unshackle dl --list-titles EXAMPLE 81234567 # show seasons/episodes
unshackle dl --list EXAMPLE 81234567 # show available tracks
```
## 7. Run your first download
@@ -196,13 +196,13 @@ unshackle dl <FLAGS> <SERVICE-TAG> <TITLE>
```
- **`dl`** carries every quality, language, track, and output flag.
- **`<SERVICE-TAG>`** picks which service to talk to (`NF`, `DSNP`, …).
- **`<SERVICE-TAG>`** picks which service to talk to (e.g. `EXAMPLE`).
- **`<TITLE>`** is the URL, ID, or slug the service understands.
A good first command asks for 1080p with English audio and subtitles:
```shell title="Your first download"
unshackle dl -q 1080 -l en NF 81234567
unshackle dl -q 1080 -l en EXAMPLE 81234567
```
unshackle will fetch the title, select the tracks matching your flags, acquire
@@ -224,13 +224,13 @@ keys through your CDM (and any key vaults), then decrypt, mux, and tag the resul
!!! example "A few realistic variations"
```shell
# A whole first season in the best available quality
unshackle dl -w S01 NF 81234567
unshackle dl -w S01 EXAMPLE 81234567
# 2160p HDR10 with the original-language audio plus English subtitles
unshackle dl -q 2160 -r HDR10 -l orig -sl en NF 81234567
unshackle dl -q 2160 -r HDR10 -l orig -sl en EXAMPLE 81234567
# Just the newest episode of an ongoing show
unshackle dl --latest-episode NF 81234567
unshackle dl --latest-episode EXAMPLE 81234567
```
See [Downloading](../guide/downloading.md) for the complete flag reference, including
@@ -243,7 +243,7 @@ By default, finished files are written to the `downloads` directory
folder alongside the project). Override it per run with `-o`:
```shell
unshackle dl -q 1080 -o /mnt/media/incoming NF 81234567
unshackle dl -q 1080 -o /mnt/media/incoming EXAMPLE 81234567
```
- **Movies** are written as a single `.mkv` file named from your `movies` template.
+20 -20
View File
@@ -45,16 +45,16 @@ unshackle dl [OPTIONS] SERVICE [SERVICE ARGS...]
```
- `OPTIONS`: every flag below, parsed at the `dl` level.
- `SERVICE`: a service tag (e.g. `NF`, `DSNP`). Tags are case-insensitive and honour each service's aliases (`disney+`, `DSNP`, etc. all resolve to the same tag).
- `SERVICE`: a service tag (e.g. `EXAMPLE1`, `EXAMPLE2`). Tags are case-insensitive and honour each service's aliases (`example+`, `EXAMPLE2`, etc. all resolve to the same tag).
- `SERVICE ARGS`: the title, URL, or ID, plus any service-specific options. These belong to the service, not to `dl`.
!!! example "Typical downloads"
```shell
# Best available 1080p SDR of a Netflix title
unshackle dl -q 1080 NF 81234567
# Best available 1080p SDR of a title
unshackle dl -q 1080 EXAMPLE 81234567
# 4K HDR10, English audio + subs, from a URL
unshackle dl -q 2160 -r HDR10 -l en DSNP "https://www.disneyplus.com/…"
unshackle dl -q 2160 -r HDR10 -l en EXAMPLE "https://www.example.com/..."
# A season range, HEVC video, EC3 audio
unshackle dl -w S01-S03 -v H.265 -a EC3 SERVICE TITLE-ID
@@ -67,16 +67,16 @@ unshackle dl [OPTIONS] SERVICE [SERVICE ARGS...]
| Flag | Default | Description |
|---|---|---|
| `-p`, `--profile` | — | Profile for credentials and cookies. |
| `-p`, `--profile` | - | Profile for credentials and cookies. |
| `-q`, `--quality` | best | Resolution(s), comma-separated, e.g. `1080,720`. `-q 1080` also matches anamorphic tracks by 16:9 canvas. |
| `-v`, `--vcodec` | any | Video codec(s). Accepts names or values: `AVC`/`H.264`, `HEVC`/`H.265`, `VC1`, `VP8`, `VP9`, `AV1`. |
| `-a`, `--acodec` | any | Audio codec(s), comma-separated. Accepts `AAC`, `AC3`/`DD`, `EC3`/`DD+`/`eac3`/`ddp`, `AC4`, `OPUS`, `OGG`/`vorbis`, `DTS`, `ALAC`, `FLAC`. |
| `-vb`, `--vbitrate` | highest | Exact video bitrate in kbps. |
| `-ab`, `--abitrate` | highest | Exact audio bitrate in kbps. |
| `-vb-range`, `--vbitrate-range` | — | Video bitrate range in kbps, e.g. `6000-7000`; picks highest within. Mutually exclusive with `--vbitrate`. |
| `-ab-range`, `--abitrate-range` | — | Audio bitrate range in kbps, e.g. `128-256`. Mutually exclusive with `--abitrate`. |
| `-vb-range`, `--vbitrate-range` | - | Video bitrate range in kbps, e.g. `6000-7000`; picks highest within. Mutually exclusive with `--vbitrate`. |
| `-ab-range`, `--abitrate-range` | - | Audio bitrate range in kbps, e.g. `128-256`. Mutually exclusive with `--abitrate`. |
| `-r`, `--range` | `SDR` | Colour range(s): `SDR`, `HLG`, `HDR10`, `HDR10P` (HDR10+), `DV`, `HYBRID`. |
| `-c`, `--channels` | — | Audio channels; matches sub-layouts (5.1 ≈ 6.0). |
| `-c`, `--channels` | - | Audio channels; matches sub-layouts (5.1 ≈ 6.0). |
| `-naa`, `--noatmos` | off | Exclude Dolby Atmos audio tracks. |
| `--worst` | off | Pick the lowest bitrate within the requested quality. **Requires `-q`.** |
| `--best-available` | off | Continue with the best available if a requested resolution/language is absent, instead of failing. |
@@ -91,13 +91,13 @@ unshackle dl [OPTIONS] SERVICE [SERVICE ARGS...]
| Flag | Default | Description |
|---|---|---|
| `-l`, `--lang` | `orig` | Language(s) for **both** video and audio. `orig` = the title's original language; e.g. `orig,en`. |
| `-vl`, `--v-lang` | — | Video-only language (overrides `-l` for video). |
| `-al`, `--a-lang` | — | Audio-only language (overrides `-l` for audio). |
| `-vl`, `--v-lang` | - | Video-only language (overrides `-l` for video). |
| `-al`, `--a-lang` | - | Audio-only language (overrides `-l` for audio). |
| `-sl`, `--s-lang` | `all` | Subtitle language(s). |
| `--require-subs` | — | Required subtitle langs; keeps **all** subs only if these exist. **Cannot combine with `--s-lang`.** |
| `--require-subs` | - | Required subtitle langs; keeps **all** subs only if these exist. **Cannot combine with `--s-lang`.** |
| `-fs`, `--forced-subs` | off | Include forced subtitle tracks. |
| `--exact-lang` | off | Exact matching only: `-l es-419` matches `es-419`, not `es-ES`. |
| `--sub-format` | — | Output subtitle format (`SRT`/`srt`, `VTT`/`webvtt`, `ASS`/`ssa`, `TTML`, `SMI`, …), or `original` to keep the source format. |
| `--sub-format` | - | Output subtitle format (`SRT`/`srt`, `VTT`/`webvtt`, `ASS`/`ssa`, `TTML`, `SMI`, ...), or `original` to keep the source format. |
The special language tokens `orig`, `all`, and `best` are honoured everywhere a language is expected.
@@ -175,7 +175,7 @@ Keep only certain track types, or skip certain track types. Attachments are alwa
| `--no-cache` | off | Bypass the title cache. |
| `--reset-cache` | off | Clear the title cache. |
| `--list` | off | List available/would-be-downloaded tracks; do not download. |
| `--slow` | — | Inter-title delay. Bare `--slow` = 60-120s; `--slow 20-40` = custom range (minimum 20s). |
| `--slow` | - | Inter-title delay. Bare `--slow` = 60-120s; `--slow 20-40` = custom range (minimum 20s). |
!!! warning "Some flags cannot be combined"
`--require-subs` and `--s-lang`; `--select-titles` and `--wanted`; `--worst` requires `--quality`; `--vbitrate` and `--vbitrate-range` (and the audio equivalents) are mutually exclusive.
@@ -200,8 +200,8 @@ The query syntax is defined per service. Results are printed as a tree of titles
!!! example
```shell
unshackle search NF "The Office"
unshackle search -p myprofile NF "breaking bad"
unshackle search EXAMPLE "My Show"
unshackle search -p myprofile EXAMPLE "Another Show"
unshackle search --proxy nordvpn:ca SERVICE "query"
```
@@ -306,7 +306,7 @@ Clear an environment directory. The directory is emptied and recreated, and the
unshackle env check
unshackle env info
unshackle env clear cache
unshackle env clear cache NF # one service only
unshackle env clear cache EXAMPLE # one service only
unshackle env clear temp
```
@@ -356,10 +356,10 @@ Create service tables on vaults that use tables, for every installed service, wh
!!! example
```shell
unshackle kv copy main backup1 backup2
unshackle kv copy main backup -s NF
unshackle kv copy main backup -s EXAMPLE
unshackle kv sync main mysql_vault
unshackle kv add keys.txt NF main backup
unshackle kv search 0123456789abcdef0123456789abcdef -s NF -v main
unshackle kv add keys.txt EXAMPLE main backup
unshackle kv search 0123456789abcdef0123456789abcdef -s EXAMPLE -v main
unshackle kv prepare main mysql_vault
```
@@ -521,7 +521,7 @@ Losslessly set the video range flag to full or limited at the bitstream level.
| Option | Default | Description |
|---|---|---|
| `--full` / `--limited` | — | Full (0-255) or limited (16-235) range. |
| `--full` / `--limited` | - | Full (0-255) or limited (16-235) range. |
| `-p`, `--preview` | off | Preview instead of writing a file. |
### `util test PATH`
+41 -41
View File
@@ -26,23 +26,23 @@ unshackle dl [OPTIONS] SERVICE [SERVICE ARGUMENTS]
- `unshackle`: the root command.
- `dl`: the download command. **All of the options on this page are parsed here**, so
they go *before* the service tag.
- `SERVICE`: a service tag such as `NF`, `DSNP`, `AMZN`. Service tags are
case-insensitive and honour each service's aliases (for example `disney+` resolves to
- `SERVICE`: a service tag such as `EXAMPLE1`, `EXAMPLE2`, `EXAMPLE3`. Service tags are
case-insensitive and honour each service's aliases (for example `example+` resolves to
its real tag).
- `SERVICE ARGUMENTS`: usually a title ID or URL. This positional argument belongs to
the **service**, not to `dl`, so it comes *after* the tag.
```shell title="A minimal download"
unshackle dl NF 81234567
unshackle dl EXAMPLE 81234567
```
```shell title="Flags belong to dl, the title belongs to the service"
unshackle dl -q 1080 -v H.265 -r HDR10 --lang en DSNP 'https://www.disneyplus.com/…'
unshackle dl -q 1080 -v H.265 -r HDR10 --lang en EXAMPLE 'https://www.example.com/...'
```
!!! tip "See what a service accepts"
Because the positional argument is defined by each service, run
`unshackle dl SERVICE --help` (e.g. `unshackle dl NF --help`) to see that service's
`unshackle dl SERVICE --help` (e.g. `unshackle dl EXAMPLE --help`) to see that service's
own argument and any service-specific options.
## The download flow
@@ -75,11 +75,11 @@ downloaded. `--skip-dl` runs the license step but skips the actual segment downl
list. Without it, unshackle picks the **best available** resolution.
```shell title="Single resolution"
unshackle dl -q 1080 NF 81234567
unshackle dl -q 1080 EXAMPLE 81234567
```
```shell title="Multiple resolutions in one run"
unshackle dl -q 2160,1080,720 NF 81234567
unshackle dl -q 2160,1080,720 EXAMPLE 81234567
```
!!! note "16:9 canvas matching"
@@ -97,7 +97,7 @@ By default a missing requested resolution is an error. Two flags change that:
| `--worst` | Within the specified quality, pick the **lowest** bitrate rendition. **Requires `-q/--quality`.** |
```shell title="Never fail on a missing resolution"
unshackle dl -q 2160 --best-available AMZN 0ABC123
unshackle dl -q 2160 --best-available EXAMPLE 0ABC123
```
## Video codec and color range
@@ -117,9 +117,9 @@ either enum **names** or their **values**, comma-separated.
| `AV1` | `AV1` |
```shell title="Either spelling works"
unshackle dl -v HEVC NF 81234567
unshackle dl -v H.265 NF 81234567
unshackle dl -v hevc,avc NF 81234567
unshackle dl -v HEVC EXAMPLE 81234567
unshackle dl -v H.265 EXAMPLE 81234567
unshackle dl -v hevc,avc EXAMPLE 81234567
```
### Color range
@@ -136,7 +136,7 @@ unshackle dl -v hevc,avc NF 81234567
| `HYBRID` | Fetch both an HDR10/HDR10+ base and a DV track, then merge them |
```shell title="Grab HDR10 and Dolby Vision in one run"
unshackle dl -q 2160 -r HDR10,DV DSNP '…'
unshackle dl -q 2160 -r HDR10,DV EXAMPLE '...'
```
!!! warning "HYBRID requires dovi_tool"
@@ -215,7 +215,7 @@ Names, values, and a few aliases are accepted: `eac3` and `ddp` both resolve to
and `vorbis` resolves to `OGG`.
```shell title="Prefer Dolby Digital Plus, fall back to AAC"
unshackle dl -a EC3,AAC NF 81234567
unshackle dl -a EC3,AAC EXAMPLE 81234567
```
### Channels and Atmos
@@ -225,7 +225,7 @@ unshackle dl -a EC3,AAC NF 81234567
- `-naa` / `--noatmos`: exclude Dolby Atmos audio tracks from selection.
```shell title="5.1 audio, no Atmos"
unshackle dl -c 5.1 --noatmos AMZN 0ABC123
unshackle dl -c 5.1 --noatmos EXAMPLE 0ABC123
```
## Languages
@@ -236,7 +236,7 @@ unshackle dl -c 5.1 --noatmos AMZN 0ABC123
`orig`, the title's original language.
```shell title="Original language plus English"
unshackle dl -l orig,en NF 81234567
unshackle dl -l orig,en EXAMPLE 81234567
```
The special token `orig` is resolved to the title's actual original language everywhere
@@ -247,7 +247,7 @@ it is used. You can override each stream type independently:
- `-al` / `--a-lang`: language for **audio only** (overrides `-l` for audio).
```shell title="English audio over the original video"
unshackle dl -al en NF 81234567
unshackle dl -al en EXAMPLE 81234567
```
### Exact vs fuzzy matching
@@ -269,7 +269,7 @@ matches only `es-419`, not `es-ES`.
every available subtitle language is downloaded.
```shell title="Only English and Spanish subtitles"
unshackle dl -sl en,es NF 81234567
unshackle dl -sl en,es EXAMPLE 81234567
```
### Requiring subtitles
@@ -299,7 +299,7 @@ download on the presence of a specific subtitle track.
| `original` | Keep the source format, no conversion |
```shell title="Convert subtitles to SRT"
unshackle dl --sub-format srt NF 81234567
unshackle dl --sub-format srt EXAMPLE 81234567
```
!!! note "SDH stripping happens by default"
@@ -321,24 +321,24 @@ with `-` to exclude it.
=== "Whole seasons"
```shell
unshackle dl -w S01 NF 81234567
unshackle dl -w S01-S03 NF 81234567
unshackle dl -w S01,S03,S05 NF 81234567
unshackle dl -w S01 EXAMPLE 81234567
unshackle dl -w S01-S03 EXAMPLE 81234567
unshackle dl -w S01,S03,S05 EXAMPLE 81234567
```
=== "Specific episodes"
```shell
unshackle dl -w S01E01 NF 81234567
unshackle dl -w S01E01-S01E05 NF 81234567
unshackle dl -w S01E01-S02E03 NF 81234567
unshackle dl -w S01E01 EXAMPLE 81234567
unshackle dl -w S01E01-S01E05 EXAMPLE 81234567
unshackle dl -w S01E01-S02E03 EXAMPLE 81234567
```
=== "Exclusions"
```shell
# Seasons 1 through 5, but not season 3
unshackle dl -w S01-S05,-S03 NF 81234567
unshackle dl -w S01-S05,-S03 EXAMPLE 81234567
```
### Other selection flags
@@ -350,7 +350,7 @@ with `-` to exclude it.
| `--list-titles` | List the titles that would be downloaded, then stop. |
```shell title="Grab just the newest episode"
unshackle dl --latest-episode NF 81234567
unshackle dl --latest-episode EXAMPLE 81234567
```
## Including and excluding track types
@@ -380,11 +380,11 @@ Additional track-type flags:
than aborting the whole title. Video and audio failures remain fatal.
```shell title="Subtitles only"
unshackle dl -S -sl en NF 81234567
unshackle dl -S -sl en EXAMPLE 81234567
```
```shell title="Everything except chapters"
unshackle dl -nc NF 81234567
unshackle dl -nc EXAMPLE 81234567
```
!!! note
@@ -403,7 +403,7 @@ Before committing to a long download, inspect what unshackle *would* do:
| `--skip-dl` | Skip downloading but still acquire the decryption keys. |
```shell title="See the track selection without downloading"
unshackle dl -q 1080 -v H.265 -r HDR10 --list NF 81234567
unshackle dl -q 1080 -v H.265 -r HDR10 --list EXAMPLE 81234567
```
## Output and muxing
@@ -416,7 +416,7 @@ unshackle dl -q 1080 -v H.265 -r HDR10 --list NF 81234567
- `--no-source`: remove the service source tag from the filename and path.
```shell title="Send this download somewhere specific"
unshackle dl -o ~/Videos/incoming NF 81234567
unshackle dl -o ~/Videos/incoming EXAMPLE 81234567
```
### Muxing behaviour
@@ -426,7 +426,7 @@ flags change how the output is assembled:
| Flag | Behaviour | Default source |
| --- | --- | --- |
| `--no-mux` | Do not mux; keep the individual track files. | — |
| `--no-mux` | Do not mux; keep the individual track files. | - |
| `--split-audio` | Write a separate output file per audio codec instead of merging all audio. | config `muxing.merge_audio` (on) |
| `--merge-video` | Mux all selected video tracks into one file. | config `muxing.merge_video` (off) |
@@ -436,7 +436,7 @@ flags change how the output is assembled:
- `--repack`: add a `REPACK` tag to the output filename.
```shell title="Custom group tag and a REPACK label"
unshackle dl --tag MYGRP --repack NF 81234567
unshackle dl --tag MYGRP --repack EXAMPLE 81234567
```
## Proxies
@@ -445,9 +445,9 @@ unshackle dl --tag MYGRP --repack NF 81234567
configured proxy providers), or a `provider:region` form.
```shell title="Proxy forms"
unshackle dl --proxy us NF 81234567
unshackle dl --proxy nordvpn:ca NF 81234567
unshackle dl --proxy 'http://user:pass@host:8080' NF 81234567
unshackle dl --proxy us EXAMPLE 81234567
unshackle dl --proxy nordvpn:ca EXAMPLE 81234567
unshackle dl --proxy 'http://user:pass@host:8080' EXAMPLE 81234567
```
Two related flags:
@@ -468,11 +468,11 @@ Two related flags:
| `--reset-cache` | Clear the title cache before fetching. |
```shell title="Two tracks at a time, eight threads each"
unshackle dl --downloads 2 --workers 8 NF 81234567
unshackle dl --downloads 2 --workers 8 EXAMPLE 81234567
```
```shell title="Space out a season download"
unshackle dl -w S01 --slow 30-60 NF 81234567
unshackle dl -w S01 --slow 30-60 EXAMPLE 81234567
```
## Keys, vaults, and export
@@ -484,7 +484,7 @@ a key when the vault misses. You can force one side or the other:
- `--vaults-only`: only use key vaults (never license via the CDM); a missing key fails.
```shell title="Fetch keys only, no download"
unshackle dl --skip-dl NF 81234567
unshackle dl --skip-dl EXAMPLE 81234567
```
`--export` writes a JSON file, into the configured exports directory, containing track
@@ -492,7 +492,7 @@ info and the acquired content keys for each title. This is the format consumed b
`unshackle import` to reconstruct a download later.
```shell title="Export track info and keys"
unshackle dl --skip-dl --export NF 81234567
unshackle dl --skip-dl --export EXAMPLE 81234567
```
!!! note "Region is recorded only with a proxy"
@@ -509,10 +509,10 @@ tagging and naming:
| `--tmdb` | `--tmdb 27205` | Use this TMDB ID instead of automatic lookup. |
| `--imdb` | `--imdb tt1375666` | Use this IMDb ID. |
| `--animeapi` | `--animeapi mal:12345` | Resolve via AnimeAPI (`mal:`/`anilist:` prefix; defaults to MAL). |
| `--enrich` | — | Override the show title and year from an external source. **Requires** one of `--tmdb`, `--imdb`, or `--animeapi`. |
| `--enrich` | - | Override the show title and year from an external source. **Requires** one of `--tmdb`, `--imdb`, or `--animeapi`. |
```shell title="Force the right IMDb match and enrich the title"
unshackle dl --imdb tt1375666 --enrich NF 81234567
unshackle dl --imdb tt1375666 --enrich EXAMPLE 81234567
```
## Configuration defaults
+5 -5
View File
@@ -48,7 +48,7 @@ license-server handshake; the rest are special cases.
|--------|-------------|--------------|------------|
| **Widevine** (Google) | `.wvd` | CDM challenge → license server → CDM parses → keys | shaka-packager / mp4decrypt |
| **PlayReady** (Microsoft) | `.prd` | CDM challenge (WRM header) → license server → CDM parses → keys | shaka-packager / mp4decrypt |
| **ClearKey (CENC)**, W3C EME `org.w3.clearkey` | none | JSON `{"kids":[…],"type":"temporary"}` → license server returns a JWK Set. No CDM. | shaka-packager / mp4decrypt |
| **ClearKey (CENC)**, W3C EME `org.w3.clearkey` | none | JSON `{"kids":[...],"type":"temporary"}` → license server returns a JWK Set. No CDM. | shaka-packager / mp4decrypt |
| **ClearKey (HLS)**, AES-128 `EXT-X-KEY` | none | Key fetched directly from a URI or `data:` URL. No CDM, no challenge. | in-process AES-CBC |
| **MonaLisa** (proprietary, WASM) | `.mld` | Ticket from the service API; keys extracted locally via WASM. No license server. | ML-Worker binary + AES-ECB, per segment |
@@ -201,15 +201,15 @@ fallback:
```yaml title="unshackle.yaml"
cdm:
default: nexus_6p_26830_l3
AMZN: chromecdm_l3
NF: sm_g935f_l1
EXAMPLE1: chromecdm_l3
EXAMPLE2: sm_g935f_l1
```
Lookups are case-insensitive. On the command line you can override the configured
device for a single run:
```console
$ unshackle dl -w chromecdm_l3 AMZN B0ABCDEF
$ unshackle dl -w chromecdm_l3 EXAMPLE1 B0ABCDEF
```
!!! tip "The device name is the file name"
@@ -451,7 +451,7 @@ returns the keys as a JWK Set rather than a DRM-wrapped blob. unshackle builds a
EME request of the form:
```json
{"kids": ["<base64url-kid>", …], "type": "temporary"}
{"kids": ["<base64url-kid>", ...], "type": "temporary"}
```
It sends this to the manifest's license URL (or to whatever a service's ClearKey
+10 -10
View File
@@ -20,8 +20,8 @@ When a download finishes muxing, unshackle builds the final path from three piec
!!! example "A typical episode path"
```text
/home/user/Downloads/
└─ Show Name S01 1080p AMZN WEB-DL DDP5.1 H.264/
└─ Show.Name.S01E01.Pilot.1080p.AMZN.WEB-DL.DDP5.1.H.264-TAG.mkv
└─ Show Name S01 1080p EXAMPLE WEB-DL DDP5.1 H.264/
└─ Show.Name.S01E01.Pilot.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG.mkv
```
The folder name comes from the `series` folder template and the file from the `series` output template.
@@ -51,7 +51,7 @@ The recognized kinds are:
| `movies` | Movies | *(required for movie downloads to be named, no built-in default)* |
| `series` | TV episodes | *(required for episode downloads to be named)* |
| `songs` | Music tracks | `"{track_number}. {title}"` |
| `albums` | Album **folders** only (see below) | — |
| `albums` | Album **folders** only (see below) | - |
!!! note
`movies` and `series` have no hardcoded filename fallback. If you download those title types, define their templates. `songs` falls back to `"{track_number}. {title}"` when omitted.
@@ -80,7 +80,7 @@ unshackle looks at the characters you place *between* variables to decide the fi
movies: "{title}.{year}.{quality}.{source}.WEB-DL.{audio_full}.{video}-{tag}"
```
```text
The.Movie.2024.1080p.NF.WEB-DL.DDP5.1.H.264-TAG.mkv
The.Movie.2024.1080p.EXAMPLE.WEB-DL.DDP5.1.H.264-TAG.mkv
```
=== "Readable style (spaces)"
@@ -90,7 +90,7 @@ unshackle looks at the characters you place *between* variables to decide the fi
movies: "{title} ({year}) {quality} {source} WEB-DL {audio_full} {video}"
```
```text
The Movie (2024) 1080p NF WEB-DL DDP5.1 H.264.mkv
The Movie (2024) 1080p EXAMPLE WEB-DL DDP5.1 H.264.mkv
```
## Template variables
@@ -103,7 +103,7 @@ Every variable below is valid in both output and folder templates. Values are de
|---|---|---|
| `title` | Title name (movie/show/song name; `$` is rendered as `S`) | `The Show` |
| `year` | Release year | `2024` |
| `source` | Service tag / class name (empty with `--no-source`) | `NF` |
| `source` | Service tag / class name (empty with `--no-source`) | `EXAMPLE` |
| `quality` | Resolution with scan suffix | `1080p`, `2160p`, `576i` |
| `resolution` | Resolution number only | `1080` |
| `video` | Video codec | `H.264`, `H.265` |
@@ -249,13 +249,13 @@ tag_imdb_tmdb: true
You can override the tag per run without editing config:
```bash
unshackle dl --tag OTHERGROUP AMZN "..."
unshackle dl --tag OTHERGROUP EXAMPLE "..."
```
The `--repack` flag adds the `REPACK` marker (surfaced through the `{repack}` variable) to the filename for that run:
```bash
unshackle dl --repack NF "..."
unshackle dl --repack EXAMPLE "..."
```
!!! note "Empty tags collapse cleanly"
@@ -349,7 +349,7 @@ The fallback supports two placeholders: `{i}` (chapter number, starting at 1) an
```
```text
The Movie (2024)/
└─ The.Movie.2024.1080p.NF.WEB-DL.DDP5.1.Atmos.H.265.HDR-TAG.mkv
└─ The.Movie.2024.1080p.EXAMPLE.WEB-DL.DDP5.1.Atmos.H.265.HDR-TAG.mkv
```
=== "TV series"
@@ -362,7 +362,7 @@ The fallback supports two placeholders: `{i}` (chapter number, starting at 1) an
```
```text
The Show (2023)/Season S02/
└─ The.Show.S02E04.The.Reckoning.2160p.AMZN.WEB-DL.DDP5.1.H.265-TAG.mkv
└─ The.Show.S02E04.The.Reckoning.2160p.EXAMPLE.WEB-DL.DDP5.1.H.265-TAG.mkv
```
=== "Music"
+11 -11
View File
@@ -31,15 +31,15 @@ Proxying is controlled at download time by three options on the `dl` command:
| `--no-proxy-download` | Use the proxy for the manifest, licence, and authentication, but bypass it for the **segment downloads** themselves. |
```shell title="Explicit proxy URI"
unshackle dl --proxy http://user:pass@1.2.3.4:8080 NF 81234567
unshackle dl --proxy http://user:pass@1.2.3.4:8080 EXAMPLE 81234567
```
```shell title="Resolve a US server from your configured providers"
unshackle dl --proxy us NF 81234567
unshackle dl --proxy us EXAMPLE 81234567
```
```shell title="Target a specific provider"
unshackle dl --proxy nordvpn:us NF 81234567
unshackle dl --proxy nordvpn:us EXAMPLE 81234567
```
!!! tip "Set a default proxy in config"
@@ -55,7 +55,7 @@ proxy where it matters (passing the geo-check for the manifest and the licence)
pulling the actual audio and video segments over your normal connection for full speed.
```shell title="Proxy the manifest and licence, download segments direct"
unshackle dl --proxy gb --no-proxy-download ITV 10a1234
unshackle dl --proxy gb --no-proxy-download EXAMPLE 10a1234
```
!!! warning "When this is unsafe"
@@ -78,8 +78,8 @@ flowchart TD
D -- no --> F["Ask every provider in order,<br/>first match wins"]
```
1. **An explicit URI.** Anything shaped like `http://…`, `https://…`, or a `socks…`
URI is used exactly as given. unshackle logs `Using explicit Proxy: …` and does no
1. **An explicit URI.** Anything shaped like `http://...`, `https://...`, or a `socks...`
URI is used exactly as given. unshackle logs `Using explicit Proxy: ...` and does no
lookup.
2. **A provider-prefixed query**: `provider:query`, for example `nordvpn:us` or
`gluetun:windscribe:us`. unshackle finds the provider whose name matches the prefix
@@ -154,7 +154,7 @@ proxy_providers:
malformed URI is rejected up front rather than failing mid-download.
```shell
unshackle dl --proxy de2 NF 81234567
unshackle dl --proxy de2 EXAMPLE 81234567
```
## Gluetun
@@ -187,11 +187,11 @@ gluetun:<vpn-provider>:<region>
```
```shell title="A Windscribe US exit via Gluetun"
unshackle dl --proxy gluetun:windscribe:us NF 81234567
unshackle dl --proxy gluetun:windscribe:us EXAMPLE 81234567
```
```shell title="A NordVPN Germany exit via Gluetun"
unshackle dl --proxy gluetun:nordvpn:de NF 81234567
unshackle dl --proxy gluetun:nordvpn:de EXAMPLE 81234567
```
After unshackle strips the leading `gluetun:`, the provider receives exactly
@@ -437,7 +437,7 @@ The returned proxy is HTTPS on **port 89** (NordVPN disabled its plain-HTTP prox
port 80 in 2021).
```shell
unshackle dl --proxy nordvpn:us:seattle NF 81234567
unshackle dl --proxy nordvpn:us:seattle EXAMPLE 81234567
```
## Proton VPN
@@ -521,7 +521,7 @@ that binary is found on your `PATH`. If you query Hola but the binary is missing
provider raises an error telling you to install it.
```shell title="Install hola-proxy, then just query a country"
unshackle dl --proxy hola:us NF 81234567
unshackle dl --proxy hola:us EXAMPLE 81234567
```
**Query forms:** a two-letter country code (e.g. `us`, `gb`). unshackle asks `hola-proxy`
+9 -9
View File
@@ -82,7 +82,7 @@ By default (`--s-lang all`) unshackle keeps every subtitle language the service
To narrow it down, pass a comma-separated list of language tags:
```shell title="English and Spanish subtitles only"
unshackle dl --s-lang en,es NF 81234567
unshackle dl --s-lang en,es EXAMPLE 81234567
```
Language matching is fuzzy by default: `en` will match `en-US`, `en-GB`, and similar
@@ -93,7 +93,7 @@ For strict matching, where `es-419` matches only `es-419` and never `es-ES`, add
`--exact-lang`:
```shell title="Only Latin-American Spanish, no other Spanish variants"
unshackle dl --s-lang es-419 --exact-lang DSNP 'https://www.disneyplus.com/…'
unshackle dl --s-lang es-419 --exact-lang EXAMPLE 'https://www.example.com/...'
```
### Requiring languages before downloading
@@ -104,7 +104,7 @@ errors out. This is useful for batch jobs where a title without your must-have l
should fail loudly rather than silently produce a partial result.
```shell title="Fail unless both English and French subs exist, then grab everything"
unshackle dl --require-subs en,fr AMZN B0ABCDEFGH
unshackle dl --require-subs en,fr EXAMPLE B0ABCDEFGH
```
!!! warning "`--require-subs` and `--s-lang` are mutually exclusive"
@@ -118,7 +118,7 @@ to display even when you are watching in your own language. They are **excluded
default**. Add `-fs` / `--forced-subs` to include them:
```shell title="Include forced tracks alongside full subtitles"
unshackle dl --s-lang en --forced-subs NF 81234567
unshackle dl --s-lang en --forced-subs EXAMPLE 81234567
```
## Track types: forced, SDH, and CC
@@ -181,7 +181,7 @@ TTML to WebVTT for muxing, as noted above). To force a specific output format, u
`--sub-format`:
```shell title="Convert every subtitle to SRT"
unshackle dl --s-lang en,es --sub-format srt NF 81234567
unshackle dl --s-lang en,es --sub-format srt EXAMPLE 81234567
```
`--sub-format` accepts the common format names and aliases, including `srt`, `vtt`,
@@ -189,7 +189,7 @@ unshackle dl --s-lang en,es --sub-format srt NF 81234567
all conversion:
```shell title="Keep whatever the service delivered"
unshackle dl --sub-format original DSNP 'https://www.disneyplus.com/…'
unshackle dl --sub-format original EXAMPLE 'https://www.example.com/...'
```
Conversion only runs when the source format differs from the target, so
@@ -218,9 +218,9 @@ formats involved:
| Backend | Best at | Requires |
| --- | --- | --- |
| `subtitleedit` | Highest fidelity; preserves positioning and italics | SubtitleEdit installed |
| `subby` | Native SRT output with clean-up | — |
| `pysubs2` | Best fidelity for styled SSA/ASS | — (pure Python, always available) |
| `pycaption` | Last-resort fallback; flattens styling | — |
| `subby` | Native SRT output with clean-up | - |
| `pysubs2` | Best fidelity for styled SSA/ASS | - (pure Python, always available) |
| `pycaption` | Last-resort fallback; flattens styling | - |
With `conversion_method: auto`, unshackle ranks these automatically per conversion.
Setting it to a specific value pins that backend as the first choice, falling back to
+8 -8
View File
@@ -64,7 +64,7 @@ The debug log is created during a `dl` run (and by [`import`](cli-reference.md#i
<logs directory>/unshackle_debug_<service>_<timestamp>.jsonl
```
For example, `unshackle_debug_NETFLIX_20260703-142530.jsonl`. The `<service>` tag and the timestamp mean each download gets its own file, so runs never overwrite each other.
For example, `unshackle_debug_EXAMPLE_20260703-142530.jsonl`. The `<service>` tag and the timestamp mean each download gets its own file, so runs never overwrite each other.
!!! tip "Find your logs directory"
The logs directory defaults to a `logs` folder inside the package data directory, but it can be relocated with the `directories.logs` config key. To see the exact resolved path on your machine, run [`unshackle env info`](#env-info) and read the **Directories** table.
@@ -99,16 +99,16 @@ Because each line is independent JSON, `jq` is the natural tool:
```console
# Show only error-level entries
jq 'select(.level == "ERROR")' unshackle_debug_NETFLIX_20260703-142530.jsonl
jq 'select(.level == "ERROR")' unshackle_debug_EXAMPLE_20260703-142530.jsonl
# List every operation and whether it succeeded
jq -c '{operation, success}' unshackle_debug_NETFLIX_20260703-142530.jsonl
jq -c '{operation, success}' unshackle_debug_EXAMPLE_20260703-142530.jsonl
# Pull the traceback out of the first error
jq -r 'select(.error) | .error.traceback[]' unshackle_debug_NETFLIX_20260703-142530.jsonl
jq -r 'select(.error) | .error.traceback[]' unshackle_debug_EXAMPLE_20260703-142530.jsonl
# Show only DRM / licensing operations
jq 'select(.operation | startswith("drm_"))' unshackle_debug_NETFLIX_20260703-142530.jsonl
jq 'select(.operation | startswith("drm_"))' unshackle_debug_EXAMPLE_20260703-142530.jsonl
```
The session's binary-tool versions (Shaka Packager, mp4decrypt, mkvmerge, FFmpeg, FFprobe) are logged near the start of a `dl` run, which is often the fastest way to confirm a muxing or decryption failure is really a wrong-version problem.
@@ -168,7 +168,7 @@ unshackle redacts logged strings so that debug output is safe to share. Three pa
Path redaction is controlled by the `redact_paths` config key, which is **on by default**:
```yaml
redact_paths: true # default — mask local base directories in logged paths
redact_paths: true # default - mask local base directories in logged paths
```
Set `redact_paths: false` if you are debugging a path problem locally and want to see full, unmasked paths in the console and logs. Secret and URL redaction in the JSON debug log are always applied and are not affected by this toggle.
@@ -223,7 +223,7 @@ Stale cache or leftover temp files can cause confusing behaviour (an old cached
```console
unshackle env clear cache # clear the whole cache directory
unshackle env clear cache NETFLIX # clear just one service's cache subdirectory
unshackle env clear cache EXAMPLE # clear just one service's cache subdirectory
unshackle env clear temp # clear the temp working directory
```
@@ -287,7 +287,7 @@ The debug log is tuned for **developers troubleshooting pipeline flow** (maximum
```console
# Read the pipeline's high-level flow, one line per stage
jq 'select(.level == "INFO")' unshackle_debug_NETFLIX_20260703-142530.jsonl
jq 'select(.level == "INFO")' unshackle_debug_EXAMPLE_20260703-142530.jsonl
```
!!! warning "No raw dumps"
+3 -3
View File
@@ -13,7 +13,7 @@ Every key is stored as a **KID → KEY** pair, grouped by **service**:
- **KID** (Key ID): a 16-byte identifier for a specific encrypted stream, stored as 32 lowercase hex characters with no dashes.
- **KEY**: the 16-byte content key that decrypts that stream, also 32 hex characters.
- **Service**: the canonical service tag (for example `DSNP`, not `DisneyPlus`) that namespaces the key. Each service gets its own logical table.
- **Service**: the canonical service tag (for example `EXAMPLE`, not `ExampleService`) that namespaces the key. Each service gets its own logical table.
!!! note "Why keys are matched by KID"
Vaults match keys by KID, never by PSSH/CENC header. A KID does not change unless the underlying video file itself changes, whereas the PSSH box can vary between requests for the very same content. That makes the KID a far more reliable match key.
@@ -242,7 +242,7 @@ $ unshackle kv --help
Add `KID:KEY` pairs to one or more vaults for a given service. The file must contain one pair per line as `HEX:HEX` (32 hex characters each); lines that do not match are ignored.
```console
$ unshackle kv add keys.txt DSNP local shared
$ unshackle kv add keys.txt EXAMPLE local shared
```
```text title="keys.txt"
@@ -250,7 +250,7 @@ $ unshackle kv add keys.txt DSNP local shared
0e7cc1a4e2f9411db0f24a3fbb8f8b21:00112233445566778899aabbccddeeff
```
The service argument (`DSNP` above) is normalized to its canonical tag automatically. Keys that already exist in a vault are reported as skipped.
The service argument (`EXAMPLE` above) is normalized to its canonical tag automatically. Keys that already exist in a vault are reported as skipped.
### `kv search`: find a key by KID
+2 -2
View File
@@ -71,11 +71,11 @@ Every download is three parts: the `dl` command, a **service tag**, and the
service's title argument (a URL, ID, or slug).
```shell title="Download a 1080p title with English audio and subtitles"
unshackle dl -q 1080 -l en NF 81234567
unshackle dl -q 1080 -l en EXAMPLE 81234567
```
The `dl` command carries all the quality, language, and output flags; the service
tag (`NF` above) selects which streaming service to talk to, and the value after it
tag (`EXAMPLE` above) selects which streaming service to talk to, and the value after it
is passed to that service. See the [Quickstart](getting-started/quickstart.md) to go from a fresh
install to your first file.
+177 -27
View File
@@ -79,11 +79,11 @@ directories:
| `data` | path | `unshackle/` | ❌ protected | Base for the data subdirectories above. |
| `core_dir` | path | `unshackle/core` | ❌ protected | Package core. |
| `namespace_dir` | path | `unshackle/` | ❌ protected | Package root. |
| `app_dirs` | — | `AppDirs("unshackle", False)` | ❌ protected | Internal AppDirs instance. |
| `app_dirs` | - | `AppDirs("unshackle", False)` | ❌ protected | Internal AppDirs instance. |
!!! note "The `services` directory is special"
`services` may be a **list**, and each entry can be either a local directory or a
**repository spec**: a git URL (`https://…`, `ssh://…`, `git@…`, or anything ending in
**repository spec**: a git URL (`https://...`, `ssh://...`, `git@...`, or anything ending in
`.git`) or `owner/repo` shorthand. Repo specs are cloned and updated automatically; plain
paths are used as-is. **List order is priority**: the first source to define a service
tag wins, so put your own local service directories **last** to make them fallbacks.
@@ -142,8 +142,8 @@ runtime.
- **Type:** `dict` keyed by service tag &nbsp;·&nbsp; **Default:** `{}`
Per-service configuration, keyed by the canonical service tag (for example `AMZN`, `NF`,
`DSNP`). unshackle reads several well-known sub-keys out of each service's block:
Per-service configuration, keyed by the canonical service tag (for example `EXAMPLE1`, `EXAMPLE2`,
`EXAMPLE3`). unshackle reads several well-known sub-keys out of each service's block:
- **`proxy_map`**: a dict mapping `"provider:query"` or `"query"` to a proxy value, used to
auto-select a proxy for that service.
@@ -163,11 +163,11 @@ the service as `self.config`.
```yaml
services:
AMZN:
EXAMPLE1:
proxy_map:
default: us
title_map:
"The Grand Tour: The Movie": "The Grand Tour Presents The Movie"
"My Show: The Movie": "My Show Presents The Movie"
```
### `credentials`
@@ -180,8 +180,8 @@ objects; the credential's SHA-1 is also used as an account hash for cache keys.
```yaml
credentials:
NF: user@example.com:hunter2
AMZN:
EXAMPLE2: user@example.com:hunter2
EXAMPLE1:
- primary@example.com:pw1
- secondary@example.com:pw2
```
@@ -230,13 +230,46 @@ CLI commands that run against the remote server.
- **Type:** `dict` &nbsp;·&nbsp; **Default:** `{}`
Configuration for the `serve` command (the built-in REST API server).
Configuration for the `serve` command (the built-in REST API server). The full server guide
is the [REST API](../dev/rest-api/index.md) section; these are the config keys.
| Sub-key | Type | Default | Description |
|---------|------|---------|-------------|
| `api_secret` | str | *(unset)* | Master secret accepted in the `X-Secret-Key` header. |
| `users` | dict | `{}` | Per-user API keys and their allowlists (see below). |
| `services` | list | *(unset)* | Global service allowlist. Omit to allow all. |
| `remote_only` | bool | `false` | Run without a local `output_template` (CORS/Cloudflare-friendly). |
| `session_ttl` | int (s) | `300` | Lifetime of an interactive auth session. |
| `max_sessions` | int | `100` | Maximum concurrent sessions. |
| `history_limit` | int | `100` | How many finished jobs to retain in history. |
| `compression_level` | int | `1` | gzip level for responses. |
| `cdm_overrides` | dict | *(unset)* | Allowed per-request CDM overrides. |
| `allow_job_credentials` | bool | `false` | Permit clients to supply credentials per job. |
| `devices` | list | *(auto)* | Widevine devices offered; auto-filled from `directories.wvds`. |
| `playready_devices` | list | *(auto)* | PlayReady devices; auto-filled from `directories.prds`. |
| `country` / `locations` | str / dict | *(unset)* | Advertised region metadata. |
Each entry under `users` is keyed by that user's API key and may set its own `services`,
`devices`, and `playready_devices` allowlists, narrowing the global ones.
```yaml
serve:
api_secret: change-me
remote_only: true
services: [EXAMPLE1, EXAMPLE2]
# server-wide download defaults (same keys as the `dl:` block)
downloads: 3
best_available: true
users:
a1b2c3d4: # this user's API key
services: [EXAMPLE1] # may only use EXAMPLE1
```
!!! tip "Declaring `dl` defaults under `serve`"
You can nest `dl` flags (`downloads`, `workers`, `best_available`, and so on) inside
`serve`. The point is to raise concurrency and behaviour defaults **server-wide** (every
request the server handles picks them up) without having to change each client call
individually.
You can set any [`dl`](#dl) flag key (`downloads`, `workers`, `best_available`, and so on)
directly inside `serve`. The point is to raise concurrency and behaviour defaults
**server-wide** (every request the server handles picks them up) without having to change
each client call individually.
---
@@ -246,15 +279,117 @@ Configuration for the `serve` command (the built-in REST API server).
- **Type:** `dict` &nbsp;·&nbsp; **Default:** `{}`
Default options forwarded to the `dl` command. Anything you would otherwise pass as a `dl`
flag can be given a persistent default here. See [Downloading](../guide/downloading.md) for
the flags themselves.
Persistent defaults for the `dl` command. This block is used as Click's `default_map`, so
**any** `dl` flag can be given a default here and it applies to every download without you
typing it. See [Downloading](../guide/downloading.md) and the
[CLI Reference](../guide/cli-reference.md) for what each flag does.
**Key naming.** A key is the flag's long name with dashes replaced by underscores
(`--best-available` → `best_available`, `--sub-format` → `sub_format`). A few keys are named
after the flag's internal destination rather than its visible name; set these exact keys:
| Flag | Config key |
|------|-----------|
| `-r` / `--range` | `range` |
| `--list` | `list` |
| `--tmdb` | `tmdb_id` |
| `--imdb` | `imdb_id` |
| `--animeapi` | `animeapi_id` |
| `-naa` / `--noatmos` | `no_atmos` |
| `-o` / `--output` | `output_dir` |
| `--cdm-only` / `--vaults-only` | `cdm_only` |
**Precedence** (highest first): an explicit CLI flag or environment variable → a per-service
[`services.<TAG>.dl`](#services-auth) override → this global `dl:` block → the built-in
default. In other words, config only fills in options you did not set on the command line.
Common keys (a useful subset; every `dl` flag works):
| Key | Type | Default | Sets |
|-----|------|---------|------|
| `lang` | list | `["orig"]` | Video/audio language(s); `orig` = original language. |
| `a_lang` / `v_lang` | list | `[]` | Audio- / video-only language override. |
| `s_lang` | list | `["all"]` | Subtitle language(s). |
| `quality` | list | `[]` (best) | Resolution(s), e.g. `[1080]`. |
| `vcodec` | list | `[]` (any) | Video codec(s), e.g. `[H265]`. |
| `acodec` | list | `[]` (any) | Audio codec(s), e.g. `[EC3]`. |
| `range` | list | `["SDR"]` | Colour range(s): `SDR`, `HDR10`, `HDR10+`, `DV`. |
| `channels` | float | *(unset)* | Audio channels, e.g. `6` for 5.1. |
| `sub_format` | str | *(unset)* | Convert subtitles to this format (`srt`, `vtt`, `original`, ...). |
| `forced_subs` | bool | `false` | Include forced subtitle tracks. |
| `no_subs` / `no_audio` / `no_chapters` | bool | `false` | Skip that track type. |
| `downloads` | int | `1` | Tracks downloaded concurrently. |
| `workers` | int | *(downloader default)* | Threads per track. |
| `slow` | str | *(unset)* | Inter-title delay, e.g. `"20-40"`. |
| `best_available` | bool | `false` | Fall back to best quality if the request is unavailable. |
| `proxy` | str | *(unset)* | Default proxy URI or 2-letter country. |
| `no_folder` | bool | `false` | Do not create a per-title folder. |
```yaml title="Global download defaults"
dl:
lang: [en]
quality: [1080]
range: [HDR10]
vcodec: [H265]
sub_format: srt
downloads: 2
```
!!! tip "Per-service overrides"
Nest a `dl` block under a service in [`services`](#services-auth) to override these defaults
for just that service. It uses the same keys and wins over the global `dl:` block (but still
loses to an explicit CLI flag).
```yaml
dl:
lang: [en] # global default
services:
EXAMPLE1:
dl:
lang: [en, ja] # EXAMPLE1 downloads both; everything else stays English
range: [DV]
```
!!! note "`serve` uses these same keys"
The [`serve`](#serve) block accepts the same `dl` option keys at its top level to set
server-wide download defaults for every request it handles.
### `subtitle`
- **Type:** `dict` &nbsp;·&nbsp; **Default:** `{}`
Subtitle handling options. See [Subtitles](../guide/subtitles.md).
Subtitle handling: SDH stripping, format conversion, and whether subtitles are muxed in or
written as sidecar files. See [Subtitles](../guide/subtitles.md) for the full guide.
| Sub-key | Type | Default | Description |
|---------|------|---------|-------------|
| `strip_sdh` | bool | `true` | Strip SDH/CC cues (hearing-impaired annotations) into a clean track. |
| `sdh_method` | str | `"auto"` | SDH-stripping backend to use. |
| `preserve_formatting` | bool | `true` | Keep styling/positioning when converting or stripping. |
| `convert_before_strip` | bool | `true` | Convert to the working format before stripping SDH. |
| `conversion_method` | str | `"auto"` | Subtitle conversion backend. |
| `preferred_conversion_method` | str | *(unset)* | Preferred converter when several are available. |
| `output_mode` | str | `"mux"` | `mux` embeds subtitles in the MKV; `sidecar` writes separate files. |
| `sidecar_format` | str | `"srt"` | Format for sidecar files when `output_mode: sidecar`. |
| `type_priority` | list | *(unset)* | Ordered ranking of subtitle types (`forced`, `normal`, `sdh`; CC counts as SDH) that sorts the variants within each language. Types you leave out fall to the end. |
```yaml
subtitle:
strip_sdh: true
output_mode: sidecar
sidecar_format: srt
```
!!! note "`type_priority` also picks the default subtitle"
`type_priority` sorts the tracks within each language, and at mux time the first track
in the default subtitle language gets the `default` flag. The built-in order is `forced`,
`normal`, `sdh`, which means a forced track becomes default whenever one exists. If you
want the full dialogue track as default instead, set:
```yaml
subtitle:
type_priority: [normal, sdh, forced]
```
### `audio`
@@ -284,6 +419,21 @@ audio:
Matroska (MKV) muxing options.
| Sub-key | Type | Default | Description |
|---------|------|---------|-------------|
| `set_title` | bool | `true` | Write a human-readable title into the MKV container. |
| `default_language` | dict | `{}` | Force which language is flagged *default* per track type, e.g. `{audio: en, subtitle: en}`. |
| `merge_audio` | bool | `true` | Merge all audio into one file. `--split-audio` on the CLI flips this off. |
| `merge_video` | bool | `false` | Merge all video tracks into one file. `--merge-video` on the CLI flips this on. |
```yaml
muxing:
set_title: true
default_language:
audio: en
subtitle: en
```
### `language_tags`
- **Type:** `dict` &nbsp;·&nbsp; **Default:** `{}`
@@ -381,7 +531,7 @@ then `default`.
```yaml
cdm:
default: chromecdm_l3
NF: android_l1
EXAMPLE2: android_l1
```
A value may also be a **nested dict** for advanced selection by quality, DRM system, or
@@ -389,7 +539,7 @@ profile:
```yaml
cdm:
AMZN:
EXAMPLE1:
">=1080": android_l1 # by track height
"<1080": chromecdm_l3
widevine: android_l1 # by DRM system
@@ -515,13 +665,13 @@ the full provider guide. Recognised providers and their exit ports:
| Provider | Config key | Credentials | Proxy scheme/port |
|----------|-----------|-------------|-------------------|
| Basic (static) | `basic` | country → URI(s) | as specified |
| NordVPN | `nordvpn` | 48-char **service** credentials | `https://…:89` |
| Surfshark | `surfsharkvpn` | 48-char **service** credentials | `https://…:443` |
| Windscribe | `windscribevpn` | service credentials | `https://…:443` |
| ExpressVPN | `expressvpn` | browser cookies / token cache | `https://cat:…@…:443` |
| ProtonVPN | `protonvpn` | TV login or exported cookies | `https://…:4443` (or `:443` Secure Core) |
| NordVPN | `nordvpn` | 48-char **service** credentials | `https://...:89` |
| Surfshark | `surfsharkvpn` | 48-char **service** credentials | `https://...:443` |
| Windscribe | `windscribevpn` | service credentials | `https://...:443` |
| ExpressVPN | `expressvpn` | browser cookies / token cache | `https://cat:...@...:443` |
| ProtonVPN | `protonvpn` | TV login or exported cookies | `https://...:4443` (or `:443` Secure Core) |
| Gluetun | `gluetun` | per-VPN keys/creds | `http://localhost:{port}` (local Docker) |
| Hola | *(none, auto)* | none | `http://…:{peer}` |
| Hola | *(none, auto)* | none | `http://...:{peer}` |
```yaml
proxy_providers:
@@ -696,12 +846,12 @@ headers:
cdm:
default: chromecdm_l3
NF: android_l1
EXAMPLE2: android_l1
decryption: shaka
credentials:
NF: user@example.com:hunter2
EXAMPLE2: user@example.com:hunter2
output_template:
movies: "{title}.{year}.{quality?}.{source}-{tag}"
+98
View File
@@ -0,0 +1,98 @@
#!/usr/bin/env python3
"""
Benchmark subtitle conversion backends to (re-)tune the preference ranks in
``unshackle/core/tracks/subtitle_convert.py``.
Runs every backend that can read each input file, converting to a target format (default
SRT), and reports cue count, leaked ASS override tags, and output size — so you can compare
fidelity per (source, target) pair on real files. Read-only: copies inputs to a temp dir.
Usage:
uv run python scripts/bench_subtitle_backends.py <file-or-dir> [<file-or-dir> ...] [--target SRT]
Example:
uv run python scripts/bench_subtitle_backends.py downloads/
"""
from __future__ import annotations
import argparse
import re
import shutil
import tempfile
from pathlib import Path
from unshackle.core.tracks import subtitle_convert as sc
from unshackle.core.tracks.subtitle import Subtitle
Codec = Subtitle.Codec
EXT_TO_CODEC = {
".srt": Codec.SubRip,
".vtt": Codec.WebVTT,
".ass": Codec.SubStationAlphav4,
".ssa": Codec.SubStationAlpha,
".ttml": Codec.TimedTextMarkupLang,
".smi": Codec.SAMI,
".sami": Codec.SAMI,
}
def gather(paths: list[str]) -> list[Path]:
files: list[Path] = []
for p in paths:
path = Path(p)
if path.is_dir():
files.extend(f for f in path.rglob("*") if f.suffix.lower() in EXT_TO_CODEC)
elif path.suffix.lower() in EXT_TO_CODEC:
files.append(path)
return sorted(files)
def metrics(text: str) -> tuple[int, int, int]:
cues = len(re.findall(r"-->", text))
ass_residue = len(re.findall(r"\{\\", text))
return cues, ass_residue, len(text)
def main() -> None:
ap = argparse.ArgumentParser()
ap.add_argument("paths", nargs="+", help="subtitle files or directories")
ap.add_argument("--target", default="SRT", help="target codec value (SRT, VTT, ASS, ...)")
args = ap.parse_args()
target = Codec(args.target.upper())
files = gather(args.paths)
if not files:
print("No subtitle files found.")
return
tmp = Path(tempfile.mkdtemp(prefix="subbench_"))
print(f"{'file':40} {'source':10} {'backend':12} {'ok':3} {'cues':>5} {'resid':>5} {'bytes':>7}")
for f in files:
source = EXT_TO_CODEC[f.suffix.lower()]
if source == target:
continue
for backend in sc.REGISTRY:
if not (backend.is_available() and backend.can_convert(source, target)):
continue
work = tmp / f"{f.stem}.{backend.name}{f.suffix}"
shutil.copy2(f, work)
sub = Subtitle(url="x", language="en", codec=source)
sub.path = work
try:
# Call the backend directly so each row reflects only that backend (no fallback).
out = work.with_suffix(f".{target.value.lower()}")
backend.convert(sub, target, out)
cues, resid, size = metrics(out.read_text("utf8", errors="replace"))
print(
f"{f.name[:40]:40} {source.name[:10]:10} {backend.name:12} {'Y':3} {cues:>5} {resid:>5} {size:>7}"
)
except Exception as e: # noqa: BLE001 - benchmark reports failures, does not raise
print(
f"{f.name[:40]:40} {source.name[:10]:10} {backend.name:12} {'N':3} {'-':>5} {'-':>5} {'-':>7} {type(e).__name__}"
)
if __name__ == "__main__":
main()
-81
View File
@@ -1,81 +0,0 @@
"""Tests for the FairPlay -> PlayReady bridge DRM type and skd KID extraction.
FairPlay HLS (SAMPLE-AES / cbcs) carries a content KID but no PlayReady PSSH. The
``FairPlay`` DRM synthesizes a PlayReady header from that KID so a PlayReady CDM can
license it; it is a PlayReady subclass so the pipeline reuses CDM/decrypt logic and
only differs in routing the request to ``get_fairplay_license``.
"""
from __future__ import annotations
from typing import Optional
from uuid import UUID
import pytest
from unshackle.core.drm import FairPlay, PlayReady
from unshackle.core.drm.fairplay import fairplay_kid_from_skd
def test_fairplay_is_playready_subclass() -> None:
# Pipeline relies on isinstance(drm, PlayReady) (get_drm_for_cdm, prepare_drm branch).
fp = FairPlay.from_kid(UUID("279926a3-d9b9-4b6f-8b2c-1a2b3c4d5e6f"))
assert isinstance(fp, PlayReady)
assert isinstance(fp, FairPlay)
def test_from_kid_round_trips_kid_and_sets_pssh() -> None:
kid = UUID("279926a3-d9b9-4b6f-8b2c-1a2b3c4d5e6f")
fp = FairPlay.from_kid(kid)
assert fp.pssh_b64
assert [k.hex for k in fp.kids] == [kid.hex]
@pytest.mark.parametrize(
("skd", "expected"),
[
# hyphenated GUID (with optional :IV)
("skd://72ea9ec1-abb4-40d8-b3a9-e0bd1833bd58:0123456789ABCDEF", "72ea9ec1abb440d8b3a9e0bd1833bd58"),
# GUID as a query param
("skd://lic.example/fairplay?KID=4376a4b3-d8ef-4f21-9a6b-faa81a2e59e3", "4376a4b3d8ef4f219a6bfaa81a2e59e3"),
# bare 32-hex path segment
("skd://0000000069176cc2af6f93cce3515ced/clip/x", "0000000069176cc2af6f93cce3515ced"),
],
)
def test_kid_from_skd_common_forms(skd: str, expected: str) -> None:
kid = fairplay_kid_from_skd(skd)
assert kid is not None
assert kid.hex == expected
@pytest.mark.parametrize(
"skd",
[
"skd://example.com/p123456/c1", # service-specific encoding, not a GUID/32-hex
"skd://opaque-asset-token-abc",
"",
],
)
def test_kid_from_skd_returns_none_for_non_kid_forms(skd: str) -> None:
# Services with non-standard skd encodings derive the KID themselves; the generic
# helper must not mis-parse them.
assert fairplay_kid_from_skd(skd) is None
def test_base_get_fairplay_license_delegates_to_playready() -> None:
captured: dict = {}
class FakeService:
# Bind the unbound base methods to a minimal stand-in.
from unshackle.core.service import Service
get_fairplay_license = Service.get_fairplay_license
def get_playready_license(self, *, challenge: bytes, title, track) -> Optional[bytes]:
captured["called"] = (challenge, title, track)
return b"LICENSE"
svc = FakeService()
out = svc.get_fairplay_license(challenge=b"chal", title="T", track="K")
assert out == b"LICENSE"
assert captured["called"] == (b"chal", "T", "K")
-58
View File
@@ -1,58 +0,0 @@
"""Tests for the FairPlay->PlayReady KID bridge.
FairPlay/cbcs HLS ships a tenc DEFAULT_KID but no PlayReady/Widevine PSSH.
``build_pr_header_from_kid`` synthesizes a PlayReady Object (PRO) from that bare
KID so a PlayReady license can be requested keyed on it. These pins ensure the
synthesized header parses back through pyplayready and yields the same KID.
"""
from __future__ import annotations
from uuid import UUID
import pytest
from pyplayready.system.pssh import PSSH
from unshackle.core.drm.playready import PlayReady, build_pr_header_from_kid
@pytest.mark.parametrize(
"kid",
[
UUID("279926a3-d9b9-4b6f-8b2c-1a2b3c4d5e6f"),
UUID("00000000-0000-0000-0000-000000000001"),
UUID("ffffffff-ffff-ffff-ffff-ffffffffffff"),
],
)
def test_synth_header_parses_and_round_trips_kid(kid: UUID) -> None:
pssh_b64 = build_pr_header_from_kid(kid)
# pyplayready parses the synthesized PRO as a single WRMHEADER record.
parsed = PSSH(pssh_b64)
assert len(parsed.wrm_headers) == 1
# PlayReady DRM object recovers the original KID from the synthesized header.
drm = PlayReady(pssh=parsed, pssh_b64=pssh_b64)
assert [k.hex for k in drm.kids] == [kid.hex]
def test_synth_header_is_v4_0_aesctr() -> None:
import base64
pssh_b64 = build_pr_header_from_kid(UUID("279926a3-d9b9-4b6f-8b2c-1a2b3c4d5e6f"))
xml = base64.b64decode(pssh_b64).decode("utf-16-le", errors="ignore")
assert "PlayReadyHeader" in xml
assert 'version="4.0.0.0"' in xml
assert "<ALGID>AESCTR</ALGID>" in xml
def test_cbcs_header_v4_3_round_trips_kid() -> None:
kid = UUID("279926a3-d9b9-4b6f-8b2c-1a2b3c4d5e6f")
pssh_b64 = build_pr_header_from_kid(kid, scheme="cbcs", version="4.3")
drm = PlayReady(pssh=PSSH(pssh_b64), pssh_b64=pssh_b64)
assert [k.hex for k in drm.kids] == [kid.hex]
def test_cbcs_requires_v4_3() -> None:
with pytest.raises(ValueError, match="4.3"):
build_pr_header_from_kid(UUID(int=1), scheme="cbcs", version="4.0")
+1
View File
@@ -32,6 +32,7 @@ def test_api_error_default_http_status_per_code() -> None:
APIErrorCode.JOB_NOT_FOUND: 404,
APIErrorCode.SESSION_NOT_FOUND: 404,
APIErrorCode.TRACK_NOT_FOUND: 404,
APIErrorCode.CONFLICT: 409,
APIErrorCode.RATE_LIMITED: 429,
APIErrorCode.INTERNAL_ERROR: 500,
APIErrorCode.DOWNLOAD_ERROR: 500,
+68
View File
@@ -0,0 +1,68 @@
import pytest
from unshackle.core.tracks import Subtitle, Tracks
def sub(lang: str, forced: bool = False, sdh: bool = False, cc: bool = False) -> Subtitle:
return Subtitle(
url=f"https://example.test/{lang}-{forced}-{sdh}-{cc}",
language=lang,
codec=Subtitle.Codec.SubRip,
forced=forced,
sdh=sdh,
cc=cc,
)
def shape(tracks: Tracks) -> list[tuple[str, str]]:
return [
(str(s.language), "forced" if s.forced else "sdh" if (s.sdh or s.cc) else "normal") for s in tracks.subtitles
]
@pytest.fixture
def tracks() -> Tracks:
t = Tracks()
t.add([sub("en", sdh=True), sub("en", forced=True), sub("en"), sub("it", forced=True), sub("it")])
return t
def test_default_order_is_forced_normal_sdh(tracks: Tracks) -> None:
tracks.sort_subtitles(by_language=["en"])
assert shape(tracks) == [
("en", "forced"),
("en", "normal"),
("en", "sdh"),
("it", "forced"),
("it", "normal"),
]
def test_type_priority_overrides_group_order(tracks: Tracks) -> None:
tracks.sort_subtitles(by_language=["en"], type_priority=["normal", "sdh", "forced"])
assert shape(tracks) == [
("en", "normal"),
("en", "sdh"),
("en", "forced"),
("it", "normal"),
("it", "forced"),
]
def test_type_priority_unlisted_types_fall_to_end(tracks: Tracks) -> None:
tracks.sort_subtitles(by_language=["en"], type_priority=["normal"])
# unlisted types keep their pre-sort relative order (stable sort)
assert shape(tracks) == [
("en", "normal"),
("en", "sdh"),
("en", "forced"),
("it", "normal"),
("it", "forced"),
]
def test_cc_counts_as_sdh() -> None:
t = Tracks()
t.add([sub("en", cc=True), sub("en")])
t.sort_subtitles(by_language=["en"], type_priority=["normal", "sdh"])
assert shape(t) == [("en", "normal"), ("en", "sdh")]
+15 -17
View File
@@ -46,7 +46,7 @@ from unshackle.core.config import config, resolve_cdm_name, resolve_decryption
from unshackle.core.console import console
from unshackle.core.constants import DOWNLOAD_CANCELLED, DOWNLOAD_LICENCE_ONLY, AnyTrack, context_settings
from unshackle.core.credential import Credential
from unshackle.core.drm import DRM_T, ClearKeyCENC, FairPlay, MonaLisa, PlayReady, Widevine
from unshackle.core.drm import DRM_T, ClearKeyCENC, MonaLisa, PlayReady, Widevine
from unshackle.core.events import events
from unshackle.core.music import (MusicAudioIntegrityError, MusicMetadataResult, MusicPlanner, MusicRenderer,
file_md5, verify_music_audio, write_music_manifest, write_music_metadata)
@@ -842,19 +842,27 @@ class dl:
try:
if name == "shaka_packager":
r = subprocess.run(
[str(binary), "--version"], capture_output=True, text=True, timeout=5
[str(binary), "--version"],
capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5,
)
version = (r.stdout or r.stderr or "").strip()
elif name in ("ffmpeg", "ffprobe"):
r = subprocess.run([str(binary), "-version"], capture_output=True, text=True, timeout=5)
r = subprocess.run(
[str(binary), "-version"],
capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5,
)
version = (r.stdout or "").split("\n")[0].strip()
elif name == "mkvmerge":
r = subprocess.run(
[str(binary), "--version"], capture_output=True, text=True, timeout=5
[str(binary), "--version"],
capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5,
)
version = (r.stdout or "").strip()
elif name == "mp4decrypt":
r = subprocess.run([str(binary)], capture_output=True, text=True, timeout=5)
r = subprocess.run(
[str(binary)],
capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5,
)
output = (r.stdout or "") + (r.stderr or "")
lines = [line.strip() for line in output.split("\n") if line.strip()]
version = " | ".join(lines[:2]) if lines else None
@@ -2221,7 +2229,7 @@ class dl:
by_language=processed_audio_sort_lang,
codec_priority=config.audio.get("codec_priority"),
)
title.tracks.sort_subtitles(by_language=s_lang)
title.tracks.sort_subtitles(by_language=s_lang, type_priority=config.subtitle.get("type_priority"))
if list_:
available_tracks, _ = title.tracks.tree()
@@ -2839,11 +2847,6 @@ class dl:
title=title,
track=track,
),
fairplay_licence=partial(
service.get_fairplay_license,
title=title,
track=track,
),
clearkey_licence=partial(
service.get_clearkey_license,
title=title,
@@ -3564,7 +3567,6 @@ class dl:
title: Title_T,
certificate: Callable,
licence: Callable,
fairplay_licence: Optional[Callable] = None,
clearkey_licence: Optional[Callable] = None,
track_kid: Optional[UUID] = None,
table: Table = None,
@@ -3966,12 +3968,8 @@ class dl:
if need_license and not vaults_only:
from_vaults = drm.content_keys.copy()
# FairPlay tracks are licensed through the PlayReady CDM but route their
# license request to the service's get_fairplay_license.
pr_licence = fairplay_licence if (fairplay_licence and isinstance(drm, FairPlay)) else licence
try:
drm.get_content_keys(cdm=self.cdm, licence=pr_licence, certificate=certificate)
drm.get_content_keys(cdm=self.cdm, licence=licence, certificate=certificate)
except Exception as e:
if drm.content_keys:
self.log.debug(f"License call failed but keys already in content_keys: {e}")
+4 -1
View File
@@ -1,3 +1,4 @@
import hmac
import logging
import subprocess
@@ -135,7 +136,9 @@ def serve(
secret_key = request.headers.get("X-Secret-Key")
if not secret_key:
return web.json_response({"status": 401, "message": "Secret Key is Empty."}, status=401)
if secret_key not in request.app["config"]["users"]:
# Constant-time compare against every configured key so a valid key can't be
# recovered byte-by-byte from response timing.
if not any(hmac.compare_digest(secret_key, k) for k in request.app["config"]["users"]):
return web.json_response({"status": 401, "message": "Secret Key is Invalid."}, status=401)
return await handler(request)
+2
View File
@@ -282,6 +282,8 @@ def test(path: Path, map_: str) -> None:
],
stderr=subprocess.PIPE,
universal_newlines=True,
encoding="utf-8",
errors="replace",
)
reached_output = False
errors = 0
+17
View File
@@ -3,9 +3,26 @@
from __future__ import annotations
import gzip
import zlib
from aiohttp import web
# Cap the inflated size of a peer-supplied compressed blob (cookies, session cache,
# serialized manifests) so a tiny payload cannot expand without bound (zip-bomb DoS).
MAX_INFLATE_BYTES = 64 * 1024 * 1024 # 64 MiB
def safe_inflate(data: bytes, max_size: int = MAX_INFLATE_BYTES) -> bytes:
"""zlib-decompress *data*, raising ValueError if the result would exceed *max_size*."""
decompressor = zlib.decompressobj()
out = decompressor.decompress(data, max_size + 1)
if len(out) > max_size or decompressor.unconsumed_tail:
raise ValueError("compressed payload expands beyond allowed size")
out += decompressor.flush()
if len(out) > max_size:
raise ValueError("compressed payload expands beyond allowed size")
return out
@web.middleware
async def compression_middleware(request: web.Request, handler) -> web.Response:
+7 -1
View File
@@ -127,6 +127,9 @@ class DownloadJob:
# Guards against writing the same job to the persistent history file twice.
history_recorded: bool = False
# X-Secret-Key that created the job; scopes per-caller access, never serialized into to_dict().
owner_key: Optional[str] = None
def to_dict(self, include_full_details: bool = False) -> Dict[str, Any]:
"""Convert job to dictionary for JSON response."""
result = {
@@ -617,7 +620,9 @@ class DownloadQueueManager:
f"Initialized download queue manager: max_concurrent={max_concurrent_downloads}, retention_hours={job_retention_hours}"
)
def create_job(self, service: str, title_id: str, **parameters) -> DownloadJob:
def create_job(
self, service: str, title_id: str, owner_key: Optional[str] = None, **parameters
) -> DownloadJob:
"""Create a new download job and add it to the queue."""
job_id = str(uuid.uuid4())
job = DownloadJob(
@@ -627,6 +632,7 @@ class DownloadQueueManager:
service=service,
title_id=title_id,
parameters=parameters,
owner_key=owner_key,
)
self._jobs[job_id] = job
+64 -17
View File
@@ -8,9 +8,10 @@ from typing import Any, Dict, List, Optional
from aiohttp import web
from unshackle.core.api.compression import safe_inflate
from unshackle.core.api.errors import APIError, APIErrorCode, handle_api_exception
from unshackle.core.api.input_bridge import AuthStatus, InputBridge
from unshackle.core.api.sanitize import sanitize_log
from unshackle.core.api.sanitize import safe_cache_key, sanitize_log
from unshackle.core.config import config
from unshackle.core.constants import AUDIO_CODEC_MAP, DYNAMIC_RANGE_MAP, VIDEO_CODEC_MAP
from unshackle.core.proxies.resolve import initialize_proxy_providers, resolve_proxy
@@ -275,6 +276,25 @@ def get_allowed_services(request: Optional[web.Request] = None) -> Optional[List
return list(result)
def caller_key(request: Optional[web.Request] = None) -> str:
"""The authenticating X-Secret-Key for a request, or 'anonymous' when unauthenticated."""
return request.headers.get("X-Secret-Key", "anonymous") if request else "anonymous"
def owns_job(job: Any, request: Optional[web.Request] = None) -> bool:
"""Whether the calling key owns this job.
Jobs created without an owner (no-key mode / legacy) stay shared; otherwise a job is
only visible to the key that created it (constant-time compare).
"""
import hmac
owner = getattr(job, "owner_key", None)
if owner is None:
return True
return hmac.compare_digest(owner, caller_key(request))
def validate_service(service_tag: str, request: Optional[web.Request] = None) -> Optional[str]:
"""Validate, normalize, and check allowlist for service tag."""
try:
@@ -985,7 +1005,9 @@ async def download_handler(data: Dict[str, Any], request: Optional[web.Request]
**service_specific_defaults,
**filtered_params,
}
job = manager.create_job(normalized_service, title_id, **params_with_defaults)
job = manager.create_job(
normalized_service, title_id, owner_key=caller_key(request), **params_with_defaults
)
return web.json_response(
{"job_id": job.job_id, "status": job.status.value, "created_time": job.created_time.isoformat()}, status=202
@@ -1009,7 +1031,7 @@ async def list_download_jobs_handler(data: Dict[str, Any], request: Optional[web
try:
manager = get_download_manager()
jobs = manager.list_jobs()
jobs = [job for job in manager.list_jobs() if owns_job(job, request)]
status_filter = data.get("status")
if status_filter:
@@ -1080,7 +1102,7 @@ async def get_download_job_handler(job_id: str, request: Optional[web.Request] =
manager = get_download_manager()
job = manager.get_job(job_id)
if not job:
if not job or not owns_job(job, request):
raise APIError(
APIErrorCode.JOB_NOT_FOUND,
"Job not found",
@@ -1109,7 +1131,7 @@ async def cancel_download_job_handler(job_id: str, request: Optional[web.Request
manager = get_download_manager()
job = manager.get_job(job_id)
if not job:
if not job or not owns_job(job, request):
raise APIError(
APIErrorCode.JOB_NOT_FOUND,
"Job not found",
@@ -1173,7 +1195,7 @@ async def retry_download_job_handler(job_id: str, request: Optional[web.Request]
manager = get_download_manager()
job = manager.get_job(job_id)
if not job:
if not job or not owns_job(job, request):
raise APIError(
APIErrorCode.JOB_NOT_FOUND,
"Job not found",
@@ -1200,7 +1222,7 @@ async def retry_download_job_handler(job_id: str, request: Optional[web.Request]
await manager.start_workers()
# Reuse the raw in-memory parameters; redaction only ever applies to serialized copies.
new_job = manager.create_job(job.service, job.title_id, **job.parameters)
new_job = manager.create_job(job.service, job.title_id, owner_key=caller_key(request), **job.parameters)
return web.json_response(
{"job_id": new_job.job_id, "status": new_job.status.value, "created_time": new_job.created_time.isoformat()},
@@ -1227,7 +1249,7 @@ async def prioritize_download_job_handler(job_id: str, request: Optional[web.Req
manager = get_download_manager()
job = manager.get_job(job_id)
if not job:
if not job or not owns_job(job, request):
raise APIError(
APIErrorCode.JOB_NOT_FOUND,
"Job not found",
@@ -1482,7 +1504,9 @@ def _binary_version(path: Any) -> Optional[str]:
for flag in ("--version", "-version"):
try:
proc = subprocess.run([str(path), flag], capture_output=True, text=True, timeout=5)
proc = subprocess.run(
[str(path), flag], capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5
)
except (OSError, subprocess.SubprocessError, ValueError):
return None
match = _VERSION_RE.search(proc.stdout or "") or _VERSION_RE.search(proc.stderr or "")
@@ -1626,10 +1650,9 @@ def _create_service_instance(
if cookie_text and isinstance(cookie_text, str):
import base64
import tempfile
import zlib
from http.cookiejar import MozillaCookieJar
cookie_str = zlib.decompress(base64.b64decode(cookie_text)).decode("utf-8")
cookie_str = safe_inflate(base64.b64decode(cookie_text)).decode("utf-8")
with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False, encoding="utf-8") as f:
f.write(cookie_str)
tmp_path = f.name
@@ -1700,13 +1723,16 @@ async def session_create_handler(data: Dict[str, Any], request: Optional[web.Req
cache_data = data.get("cache", {})
if cache_data:
import base64
import zlib
cache_dir = app_config.directories.cache / session_cache_tag
cache_dir.mkdir(parents=True, exist_ok=True)
for key, content in cache_data.items():
decompressed = zlib.decompress(base64.b64decode(content)).decode("utf-8")
(cache_dir / key).with_suffix(".json").write_text(decompressed, encoding="utf-8")
safe_name = safe_cache_key(key)
if not safe_name:
log.warning(f"Rejecting unsafe session cache key: {sanitize_log(key)}")
continue
decompressed = safe_inflate(base64.b64decode(content)).decode("utf-8")
(cache_dir / safe_name).with_suffix(".json").write_text(decompressed, encoding="utf-8")
bridge = InputBridge()
service_instance._input_bridge = bridge
@@ -1718,6 +1744,7 @@ async def session_create_handler(data: Dict[str, Any], request: Optional[web.Req
session_id=session_id,
)
session.creator_ip = request.remote if request else None
session.owner_key = api_key
session.cache_tag = session_cache_tag
session.input_bridge = bridge
session.auth_status = AuthStatus.AUTHENTICATING
@@ -2138,7 +2165,14 @@ async def session_prompt_post_handler(
async def _get_validated_session(session_id: str, request: Optional[web.Request]) -> Any:
"""Fetch a session and verify the requesting IP matches the creator."""
"""Fetch a session and verify the caller owns it.
Ownership is bound to the authenticating X-Secret-Key rather than the source IP:
behind a reverse proxy every caller shares the proxy's address, so the IP check
(kept as defence in depth) cannot distinguish users on its own.
"""
import hmac
from unshackle.core.api.session_store import get_session_store
store = get_session_store()
@@ -2149,6 +2183,13 @@ async def _get_validated_session(session_id: str, request: Optional[web.Request]
f"Session not found or expired: {session_id}",
details={"session_id": session_id},
)
if session.owner_key is not None and request is not None:
caller_key = request.headers.get("X-Secret-Key", "anonymous")
if not hmac.compare_digest(caller_key, session.owner_key):
raise APIError(
APIErrorCode.FORBIDDEN,
"Session access denied",
)
if session.creator_ip and request and request.remote != session.creator_ip:
raise APIError(
APIErrorCode.FORBIDDEN,
@@ -2407,11 +2448,14 @@ def _handle_single_server_cdm(
pr_pssh = PlayReadyPSSH(base64.b64decode(pssh_b64))
pr_drm = PlayReady(pssh=pr_pssh, pssh_b64=pssh_b64)
# Gate on the caller's CDM device first so a caller with no device cannot
# harvest server-side keys from the vault fallback below.
device_name = _resolve_device_name(user_config, drm_type, service.__class__.__name__)
vault_keys = _check_vaults(pr_drm.kids, service.__class__.__name__)
if vault_keys:
return vault_keys
device_name = _resolve_device_name(user_config, drm_type, service.__class__.__name__)
cdm = load_cdm(device_name, service_name=service.__class__.__name__)
pr_drm.get_content_keys(
cdm=cdm,
@@ -2427,11 +2471,14 @@ def _handle_single_server_cdm(
wv_pssh = WvPSSH(pssh_b64)
wv_drm = Widevine(pssh=wv_pssh)
# Gate on the caller's CDM device first so a caller with no device cannot
# harvest server-side keys from the vault fallback below.
device_name = _resolve_device_name(user_config, drm_type, service.__class__.__name__)
vault_keys = _check_vaults(wv_drm.kids, service.__class__.__name__)
if vault_keys:
return vault_keys
device_name = _resolve_device_name(user_config, drm_type, service.__class__.__name__)
cdm = load_cdm(device_name, service_name=service.__class__.__name__)
wv_drm.get_content_keys(
cdm=cdm,
+18 -1
View File
@@ -1,8 +1,25 @@
"""Helpers for safely logging user-provided values."""
"""Helpers for safely logging and handling user-provided values."""
from __future__ import annotations
from pathlib import Path
from typing import Optional
def sanitize_log(value: object) -> str:
"""Sanitize a value for safe logging by removing newlines and control characters."""
return str(value).replace("\n", "").replace("\r", "").replace("\x00", "")
def safe_cache_key(key: object) -> Optional[str]:
"""Return a bare filename for a peer-supplied cache key, or None if it escapes its directory.
Cache keys are written as ``<key>.json`` inside a fixed directory. A key containing a
path separator, ``..``, or an absolute path would let the peer write outside that
directory, so anything that is not already a plain filename is rejected.
"""
text = str(key)
name = Path(text).name
if not name or name != text or name in {".", ".."}:
return None
return name
+1
View File
@@ -35,6 +35,7 @@ class SessionEntry:
tracks_by_title: Dict[str, Dict[str, Track]] = field(default_factory=dict) # title_key -> {track_id -> Track}
chapters_by_title: Dict[str, List[Any]] = field(default_factory=dict) # title_key -> [Chapter]
creator_ip: Optional[str] = None
owner_key: Optional[str] = None # X-Secret-Key that owns this session
cache_tag: Optional[str] = None # per-session cache directory tag
input_bridge: Optional[InputBridge] = None
auth_status: AuthStatus = AuthStatus.AUTHENTICATED
+2 -4
View File
@@ -4,13 +4,11 @@ from uuid import UUID
from unshackle.core.drm.clearkey import ClearKey
from unshackle.core.drm.clearkey_cenc import ClearKeyCENC
from unshackle.core.drm.fairplay import FairPlay
from unshackle.core.drm.monalisa import MonaLisa
from unshackle.core.drm.playready import PlayReady
from unshackle.core.drm.widevine import Widevine
# FairPlay is a PlayReady subclass; listed for explicit isinstance/type use.
DRM_T = Union[ClearKey, ClearKeyCENC, Widevine, PlayReady, FairPlay, MonaLisa]
DRM_T = Union[ClearKey, ClearKeyCENC, Widevine, PlayReady, MonaLisa]
def drm_from_dict(data: dict[str, Any]) -> Union[Widevine, PlayReady, ClearKeyCENC]:
@@ -46,4 +44,4 @@ def drm_from_dict(data: dict[str, Any]) -> Union[Widevine, PlayReady, ClearKeyCE
return drm
__all__ = ("ClearKey", "ClearKeyCENC", "Widevine", "PlayReady", "FairPlay", "MonaLisa", "DRM_T", "drm_from_dict")
__all__ = ("ClearKey", "ClearKeyCENC", "Widevine", "PlayReady", "MonaLisa", "DRM_T", "drm_from_dict")
+6 -1
View File
@@ -223,7 +223,10 @@ class ClearKeyCENC:
]
try:
subprocess.run(cmd, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8")
subprocess.run(
cmd, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
encoding="utf-8", errors="replace",
)
except subprocess.CalledProcessError as e:
error_msg = e.stderr if e.stderr else f"mp4decrypt failed with exit code {e.returncode}"
raise subprocess.CalledProcessError(e.returncode, cmd, output=e.stdout, stderr=error_msg)
@@ -262,6 +265,8 @@ class ClearKeyCENC:
stdout=subprocess.DEVNULL,
stderr=subprocess.PIPE,
universal_newlines=True,
encoding="utf-8",
errors="replace",
)
stream_skipped = False
-46
View File
@@ -1,46 +0,0 @@
from __future__ import annotations
import re
from typing import Optional
from uuid import UUID
from pyplayready.system.pssh import PSSH
from unshackle.core.drm.playready import PlayReady, build_pr_header_from_kid
def fairplay_kid_from_skd(skd_uri: str) -> Optional[UUID]:
"""Extract the content KID from a FairPlay ``skd://`` key URI.
Handles the common multi-DRM packager forms where the KID appears in the URI as
a hyphenated GUID (optionally followed by ``:<iv>`` or as a ``?KID=<guid>`` query)
or as a bare 32-hex string in a path segment. Services whose skd URI encodes the
KID differently (e.g. an asset number plus content id) should derive it themselves
and use ``FairPlay.from_kid``.
"""
# Prefer a hyphenated GUID; fall back to a bare 32-hex run.
guid = re.search(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}", skd_uri)
if guid:
return UUID(hex=guid.group(0))
match = re.search(r"(?<![0-9a-fA-F])([0-9a-fA-F]{32})(?![0-9a-fA-F])", skd_uri)
if not match:
return None
return UUID(hex=match.group(1))
class FairPlay(PlayReady):
"""FairPlay track licensed through a PlayReady CDM (FairPlay -> PlayReady bridge).
FairPlay HLS (SAMPLE-AES / cbcs) carries a content KID but no PlayReady PSSH.
We synthesize a PlayReady header from that KID, so a PlayReady CDM can issue a
challenge and the resulting license decrypts the cbcs stream. This subclasses
PlayReady so the CDM challenge and decrypt logic are reused unchanged; the only
difference is that the download pipeline routes its license request to the
service's ``get_fairplay_license`` instead of ``get_playready_license``.
"""
@classmethod
def from_kid(cls, kid: UUID, scheme: str = "cbcs", version: str = "4.3") -> FairPlay:
"""Build a FairPlay DRM from a bare content KID via a synthesized PlayReady header."""
pssh_b64 = build_pr_header_from_kid(kid, scheme=scheme, version=version)
return cls(pssh=PSSH(pssh_b64), kid=kid, pssh_b64=pssh_b64)
+2
View File
@@ -247,6 +247,8 @@ class MonaLisa:
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
encoding="utf-8",
errors="replace",
startupinfo=startupinfo,
timeout=worker_timeout_s,
)
+16 -62
View File
@@ -2,7 +2,6 @@ from __future__ import annotations
import base64
import shutil
import struct
import subprocess
import textwrap
import time
@@ -25,42 +24,6 @@ from unshackle.core.constants import AnyTrack
from unshackle.core.utilities import get_boxes, log_event
from unshackle.core.utils.subprocess import ffprobe
# CENC/CBC scheme -> PlayReady ALGID (AESCTR for ctr schemes, AESCBC for cbc schemes).
PR_SCHEME_ALGID = {"cenc": "AESCTR", "cens": "AESCTR", "cbc1": "AESCBC", "cbcs": "AESCBC"}
def build_pr_header_from_kid(kid: UUID, scheme: str = "cenc", version: str = "4.0") -> str:
"""Synthesize a base64 PlayReady Object from a bare KID.
For FairPlay/cbcs HLS streams that carry a content KID but no PlayReady or
Widevine PSSH, this lets us request a PlayReady license keyed on that KID.
``scheme`` selects the ALGID (cbcs -> AESCBC). ``version`` selects the WRMHEADER
layout: 4.0 uses a bare ``<KID>``, 4.3 uses the ``<KIDS><KID ALGID VALUE>`` form
used for cbcs content.
"""
algid = PR_SCHEME_ALGID.get(scheme.lower())
if not algid:
raise ValueError(f"Unsupported encryption scheme for PlayReady: {scheme}")
if algid == "AESCBC" and version < "4.3":
raise ValueError("AESCBC (cbcs) requires PlayReady WRMHEADER 4.3 or higher")
# PlayReady stores the KID as a little-endian GUID; UUID.bytes_le applies that byte order.
xml_kid = base64.b64encode(kid.bytes_le).decode()
if version == "4.0":
protect_info = f"<KEYLEN>16</KEYLEN><ALGID>{algid}</ALGID></PROTECTINFO><KID>{xml_kid}</KID>"
else:
protect_info = f'<KIDS><KID ALGID="{algid}" VALUE="{xml_kid}"></KID></KIDS></PROTECTINFO>'
header_xml = (
f'<WRMHEADER xmlns="http://schemas.microsoft.com/DRM/2007/03/PlayReadyHeader" version="{version}.0.0">'
f"<DATA><PROTECTINFO>{protect_info}</DATA></WRMHEADER>"
)
header_utf16 = header_xml.encode("utf-16-le")
# PlayReady Object: one WRMHEADER record (type 1) behind the PRO length+count prefix.
rm_record = struct.pack("<HH", 1, len(header_utf16)) + header_utf16
pro = struct.pack("<IH", len(rm_record) + 6, 1) + rm_record
return base64.b64encode(pro).decode()
class PlayReady:
"""PlayReady DRM System."""
@@ -234,22 +197,16 @@ class PlayReady:
pssh_boxes.extend(list(get_boxes(init_data, b"pssh")))
tenc_boxes.extend(list(get_boxes(init_data, b"tenc")))
pssh = next((b for b in pssh_boxes if b.system_ID == PSSH.SYSTEM_ID), None)
if not pssh:
raise PlayReady.Exceptions.PSSHNotFound("PSSH was not found in track data.")
tenc = next(iter(tenc_boxes), None)
if not kid and tenc and tenc.key_ID.int != 0:
kid = tenc.key_ID
pssh = next((b for b in pssh_boxes if b.system_ID == PSSH.SYSTEM_ID), None)
if pssh:
pssh_bytes = Box.build(pssh)
return cls(pssh=PSSH(pssh_bytes), kid=kid, pssh_b64=base64.b64encode(pssh_bytes).decode())
# FairPlay/cbcs: no PSSH of any DRM system, but a tenc KID is present — synthesize a
# PlayReady header from it. Gated on zero pssh boxes so Widevine-bearing tracks fall through.
if not pssh_boxes and kid:
pssh_b64 = build_pr_header_from_kid(kid)
return cls(pssh=PSSH(pssh_b64), kid=kid, pssh_b64=pssh_b64)
raise PlayReady.Exceptions.PSSHNotFound("PSSH was not found in track data.")
pssh_bytes = Box.build(pssh)
return cls(pssh=PSSH(pssh_bytes), kid=kid, pssh_b64=base64.b64encode(pssh_bytes).decode())
@classmethod
def from_init_data(cls, init_data: bytes) -> PlayReady:
@@ -269,22 +226,16 @@ class PlayReady:
if enc_key_id:
kid = UUID(bytes=base64.b64decode(enc_key_id))
pssh = next((b for b in pssh_boxes if b.system_ID == PSSH.SYSTEM_ID), None)
if not pssh:
raise PlayReady.Exceptions.PSSHNotFound("PSSH was not found in track data.")
tenc = next(iter(tenc_boxes), None)
if not kid and tenc and tenc.key_ID.int != 0:
kid = tenc.key_ID
pssh = next((b for b in pssh_boxes if b.system_ID == PSSH.SYSTEM_ID), None)
if pssh:
pssh_bytes = Box.build(pssh)
return cls(pssh=PSSH(pssh_bytes), kid=kid, pssh_b64=base64.b64encode(pssh_bytes).decode())
# FairPlay/cbcs: no PSSH of any DRM system, but a tenc KID is present — synthesize a
# PlayReady header from it. Gated on zero pssh boxes so Widevine-bearing tracks fall through.
if not pssh_boxes and kid:
pssh_b64 = build_pr_header_from_kid(kid)
return cls(pssh=PSSH(pssh_b64), kid=kid, pssh_b64=pssh_b64)
raise PlayReady.Exceptions.PSSHNotFound("PSSH was not found in track data.")
pssh_bytes = Box.build(pssh)
return cls(pssh=PSSH(pssh_bytes), kid=kid, pssh_b64=base64.b64encode(pssh_bytes).decode())
@property
def pssh(self) -> PSSH:
@@ -487,7 +438,10 @@ class PlayReady:
]
try:
subprocess.run(cmd, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8")
subprocess.run(
cmd, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
encoding="utf-8", errors="replace",
)
except subprocess.CalledProcessError as e:
error_msg = e.stderr if e.stderr else f"mp4decrypt failed with exit code {e.returncode}"
raise subprocess.CalledProcessError(e.returncode, cmd, output=e.stdout, stderr=error_msg)
-369
View File
@@ -1,369 +0,0 @@
"""Apple HLS SAMPLE-AES decryptor for MPEG-TS elementary streams.
SAMPLE-AES (``METHOD=SAMPLE-AES``) encrypts only parts of each elementary-stream sample
rather than the whole TS, so neither Shaka Packager (rejects stream type ``0xDB``) nor
mp4decrypt (ISO-BMFF only) can decrypt it. This module implements the scheme directly,
matching the four reference implementations (hls.js, mchelnokov/decrypt-mpegts,
iori-rs/iori, N_m3u8DL-RE) and Apple's specification:
- H.264 (AVC, stream type ``0xDB``): NAL types 1 and 5 only. Remove emulation-prevention
bytes, skip the first 32 bytes, then a 1:9 pattern — decrypt 16 bytes, skip ``min(144,
remaining)`` — with AES-128-CBC chaining continuously across the encrypted blocks and the
IV reset per NAL unit. Emulation-prevention bytes are reinserted afterwards.
- AAC (ADTS, stream type ``0xCF``): per frame, skip the ADTS header plus 16 leader bytes,
decrypt the remaining complete 16-byte blocks, IV reset per frame.
- AC-3 (stream type ``0xC1``): per syncframe, skip 16 leader bytes, decrypt the remaining
complete 16-byte blocks, IV reset per frame.
All decryption is AES-128-CBC with no padding; trailing bytes shorter than a block stay clear.
The IV is supplied by the caller. HLS signals it in the ``EXT-X-KEY`` ``IV`` attribute; when
absent the conventional default is all zeros (used by every reference tool). FairPlay
(``KEYFORMAT="com.apple.streamingkeydelivery"``) streams may instead carry the IV in the CKC,
in which case the caller must provide it — see ``decrypt_sample_aes``.
"""
from __future__ import annotations
import struct
from typing import Optional
from Crypto.Cipher import AES
# MPEG-TS stream type bytes: encrypted -> standard.
STREAM_TYPE_H264 = 0x1B
STREAM_TYPE_AAC = 0x0F
STREAM_TYPE_AC3 = 0x81
ENCRYPTED_TO_CLEAR = {0xDB: STREAM_TYPE_H264, 0xCF: STREAM_TYPE_AAC, 0xC1: STREAM_TYPE_AC3}
PACKET_LENGTH = 188
SYNC_BYTE = 0x47
BLOCK = 16
def remove_epb(data: bytes) -> bytes:
"""Strip H.264 emulation-prevention bytes (``00 00 03 XX`` -> ``00 00 XX``, ``XX <= 03``)."""
out = bytearray()
i = 0
n = len(data)
while i < n:
if i + 3 < n and data[i] == 0 and data[i + 1] == 0 and data[i + 2] == 3 and data[i + 3] <= 3:
out += b"\x00\x00"
i += 3
else:
out.append(data[i])
i += 1
return bytes(out)
def insert_epb(data: bytes) -> bytes:
"""Reinsert H.264 emulation-prevention bytes to produce a valid Annex B / byte-stream NAL."""
out = bytearray()
zeros = 0
for b in data:
if zeros >= 2 and b <= 3:
out.append(3)
zeros = 0
out.append(b)
zeros = zeros + 1 if b == 0 else 0
return bytes(out)
def aes_cbc_decrypt(key: bytes, iv: bytes, data: bytes) -> bytes:
"""AES-128-CBC decrypt with no padding; ``data`` length must be a multiple of 16."""
return AES.new(key, AES.MODE_CBC, iv).decrypt(data)
def decrypt_h264_nal(nal: bytes, key: bytes, iv: bytes) -> bytes:
"""Decrypt a single H.264 NAL unit (no start code) per SAMPLE-AES; return re-escaped bytes."""
rbsp = bytearray(remove_epb(nal))
n = len(rbsp)
if n <= 48:
return nal
# Gather the encrypted blocks (1:9 pattern from offset 32) into one continuous CBC stream.
encrypted = bytearray()
offset = 32
positions = []
while True:
remaining = n - offset
if remaining <= BLOCK:
break
positions.append(offset)
encrypted += rbsp[offset : offset + BLOCK]
offset += BLOCK + min(144, remaining - BLOCK)
decrypted = aes_cbc_decrypt(key, iv, bytes(encrypted))
for idx, pos in enumerate(positions):
rbsp[pos : pos + BLOCK] = decrypted[idx * BLOCK : (idx + 1) * BLOCK]
return insert_epb(bytes(rbsp))
def split_nals(es: bytes) -> list[tuple[int, int, int]]:
"""Return (start_code_len, nal_start, nal_end) for each Annex B NAL unit in ``es``."""
nals = []
i = 0
n = len(es)
starts = []
while i + 3 <= n:
if es[i] == 0 and es[i + 1] == 0 and es[i + 2] == 1:
sc = 4 if i >= 1 and es[i - 1] == 0 else 3
starts.append((i - (sc - 3), sc))
i += 3
else:
i += 1
for idx, (sc_off, sc) in enumerate(starts):
nal_start = sc_off + sc
nal_end = starts[idx + 1][0] if idx + 1 < len(starts) else n
nals.append((sc, nal_start, nal_end))
return nals
def decrypt_h264_es(es: bytes, key: bytes, iv: bytes) -> bytes:
"""Decrypt all coded-slice NAL units (types 1, 5) in an Annex B H.264 elementary stream."""
out = bytearray()
prev_end = 0
for sc, nal_start, nal_end in split_nals(es):
out += es[prev_end:nal_start]
nal = es[nal_start:nal_end]
prev_end = nal_end
if nal and (nal[0] & 0x1F) in (1, 5):
out += decrypt_h264_nal(nal, key, iv)
else:
out += nal
out += es[prev_end:]
return bytes(out)
def decrypt_aac_es(es: bytes, key: bytes, iv: bytes) -> bytes:
"""Decrypt ADTS AAC: per frame skip header + 16 leader bytes, decrypt remaining full blocks."""
out = bytearray()
i = 0
n = len(es)
while i + 7 <= n:
if es[i] != 0xFF or (es[i + 1] & 0xF0) != 0xF0:
out.append(es[i])
i += 1
continue
header_len = 7 if (es[i + 1] & 1) else 9
frame_len = ((es[i + 3] & 3) << 11) | (es[i + 4] << 3) | (es[i + 5] >> 5)
if frame_len < header_len or i + frame_len > n:
out += es[i:]
i = n
break
frame = bytearray(es[i : i + frame_len])
payload = frame[header_len:]
if len(payload) > BLOCK:
enc_len = ((len(payload) - BLOCK) // BLOCK) * BLOCK
if enc_len:
frame[header_len + BLOCK : header_len + BLOCK + enc_len] = aes_cbc_decrypt(
key, iv, bytes(payload[BLOCK : BLOCK + enc_len])
)
out += frame
i += frame_len
out += es[i:]
return bytes(out)
def decrypt_ac3_es(es: bytes, key: bytes, iv: bytes) -> bytes:
"""Decrypt AC-3: per syncframe skip 16 leader bytes, decrypt remaining full blocks.
AC-3 syncframes start with ``0B 77``; frame size derives from the frmsizecod table. To keep
this dependency-free the whole ES (minus a 16-byte leader) is treated as one CBC region,
matching the reference behaviour for single-program AC-3 PES payloads.
"""
if len(es) <= BLOCK:
return es
enc_len = ((len(es) - BLOCK) // BLOCK) * BLOCK
if not enc_len:
return es
out = bytearray(es)
out[BLOCK : BLOCK + enc_len] = aes_cbc_decrypt(key, iv, bytes(out[BLOCK : BLOCK + enc_len]))
return bytes(out)
def crc32_mpeg(data: bytes) -> int:
"""MPEG-2 systems CRC-32 (poly 0x04C11DB7, init 0xFFFFFFFF, no final xor)."""
crc = 0xFFFFFFFF
for byte in data:
crc ^= byte << 24
for _ in range(8):
crc = ((crc << 1) ^ 0x04C11DB7) & 0xFFFFFFFF if crc & 0x80000000 else (crc << 1) & 0xFFFFFFFF
return crc
def packet_pid(pkt: bytes) -> int:
return ((pkt[1] & 0x1F) << 8) | pkt[2]
def payload_offset(pkt: bytes) -> int:
"""Byte offset of the payload within a TS packet, or -1 if the packet carries none."""
afc = (pkt[3] >> 4) & 0x3
off = 4
if afc & 0x2:
off += 1 + pkt[4]
if not afc & 0x1 or off >= PACKET_LENGTH:
return -1
return off
def parse_pmt(section: bytes) -> dict[int, int]:
"""Map elementary PID -> stream_type from a PMT section (starting at table_id)."""
section_length = ((section[1] & 0x0F) << 8) | section[2]
program_info_length = ((section[10] & 0x0F) << 8) | section[11]
pos = 12 + program_info_length
end = 3 + section_length - 4 # up to (excluding) CRC32
result = {}
while pos + 5 <= end:
stream_type = section[pos]
es_pid = ((section[pos + 1] & 0x1F) << 8) | section[pos + 2]
es_info_length = ((section[pos + 3] & 0x0F) << 8) | section[pos + 4]
result[es_pid] = stream_type
pos += 5 + es_info_length
return result
def patch_pmt_section(section: bytes) -> bytes:
"""Rewrite encrypted stream-type bytes to their clear equivalents and fix the CRC."""
section = bytearray(section)
section_length = ((section[1] & 0x0F) << 8) | section[2]
program_info_length = ((section[10] & 0x0F) << 8) | section[11]
pos = 12 + program_info_length
end = 3 + section_length - 4
while pos + 5 <= end:
if section[pos] in ENCRYPTED_TO_CLEAR:
section[pos] = ENCRYPTED_TO_CLEAR[section[pos]]
es_info_length = ((section[pos + 3] & 0x0F) << 8) | section[pos + 4]
pos += 5 + es_info_length
crc = crc32_mpeg(bytes(section[:end]))
section[end : end + 4] = struct.pack(">I", crc)
return bytes(section)
def repacketize(pid: int, pes: bytes, continuity: dict[int, int]) -> bytes:
"""Split a PES packet into 188-byte TS packets for ``pid`` with stuffing on the final one."""
out = bytearray()
pos = 0
first = True
n = len(pes)
while pos < n:
remaining = n - pos
cc = continuity[pid]
continuity[pid] = (cc + 1) & 0x0F
if remaining >= 184:
header = bytes([SYNC_BYTE, (0x40 if first else 0x00) | (pid >> 8), pid & 0xFF, 0x10 | cc])
out += header + pes[pos : pos + 184]
pos += 184
else:
stuffing = 184 - remaining
header = bytes([SYNC_BYTE, (0x40 if first else 0x00) | (pid >> 8), pid & 0xFF, 0x30 | cc])
if stuffing == 1:
adaptation = bytes([0x00])
else:
adaptation = bytes([stuffing - 1, 0x00]) + b"\xFF" * (stuffing - 2)
out += header + adaptation + pes[pos:]
pos = n
first = False
return out
def split_pes_payload(pes: bytes) -> tuple[bytes, bytes]:
"""Split a PES packet into (header_prefix_including_optional_header, elementary_payload)."""
if pes[:3] != b"\x00\x00\x01":
return pes, b""
stream_id = pes[3]
# Stream ids without an optional PES header (padding, private_2, etc.) carry payload directly.
if stream_id in (0xBC, 0xBE, 0xBF, 0xF0, 0xF1, 0xFF, 0xF2, 0xF8):
return pes[:6], pes[6:]
header_data_length = pes[8]
start = 9 + header_data_length
return pes[:start], pes[start:]
def rebuild_pes(prefix: bytes, payload: bytes) -> bytes:
"""Reassemble a PES packet, refreshing PES_packet_length for the new payload size."""
prefix = bytearray(prefix)
body_length = (len(prefix) - 6) + len(payload)
prefix[4:6] = struct.pack(">H", body_length if body_length <= 0xFFFF else 0)
return bytes(prefix) + payload
def decrypt_sample_aes(data: bytes, key: bytes, iv: Optional[bytes] = None) -> bytes:
"""Decrypt a SAMPLE-AES MPEG-TS byte string and return a clean (standard) MPEG-TS.
``key`` is the 16-byte content key. ``iv`` is the 16-byte initialization vector; when not
given it defaults to all zeros (the HLS convention for an absent ``EXT-X-KEY`` IV). The
output has its PMT stream types patched to the standard values, so it muxes like any TS.
"""
if iv is None:
iv = b"\x00" * BLOCK
sync = data.find(bytes([SYNC_BYTE]))
if sync < 0:
raise ValueError("Not an MPEG-TS stream (no sync byte found)")
packets = [data[i : i + PACKET_LENGTH] for i in range(sync, len(data) - PACKET_LENGTH + 1, PACKET_LENGTH)]
# First pass: locate the PMT and the elementary stream types.
pmt_pid: Optional[int] = None
pid_types: dict[int, int] = {}
for pkt in packets:
if pkt[0] != SYNC_BYTE:
continue
pid = packet_pid(pkt)
off = payload_offset(pkt)
if off < 0:
continue
if pid == 0 and pkt[1] & 0x40: # PAT
section = pkt[off + 1 + pkt[off] :]
pmt_pid = ((section[10] & 0x1F) << 8) | section[11]
elif pmt_pid is not None and pid == pmt_pid and pkt[1] & 0x40:
section = pkt[off + 1 + pkt[off] :]
pid_types = parse_pmt(section)
break
decrypters = {
0xDB: decrypt_h264_es,
0xCF: decrypt_aac_es,
0xC1: decrypt_ac3_es,
}
encrypted_pids = {pid: t for pid, t in pid_types.items() if t in decrypters}
if not encrypted_pids:
return data # nothing SAMPLE-AES encrypted
# Second pass: rebuild the stream, decrypting elementary PIDs and patching the PMT.
out = bytearray()
continuity: dict[int, int] = {pid: 0 for pid in encrypted_pids}
pending: dict[int, bytearray] = {}
def flush(pid: int) -> None:
pes = bytes(pending.pop(pid))
prefix, payload = split_pes_payload(pes)
decrypted = decrypters[encrypted_pids[pid]](payload, key, iv)
out.extend(repacketize(pid, rebuild_pes(prefix, decrypted), continuity))
for pkt in packets:
if pkt[0] != SYNC_BYTE:
continue
pid = packet_pid(pkt)
if pid in encrypted_pids:
off = payload_offset(pkt)
if pkt[1] & 0x40: # PUSI -> new PES
if pid in pending:
flush(pid)
pending[pid] = bytearray(pkt[off:] if off >= 0 else b"")
elif pid in pending and off >= 0:
pending[pid] += pkt[off:]
continue
if pmt_pid is not None and pid == pmt_pid and pkt[1] & 0x40:
off = payload_offset(pkt)
pointer = pkt[off]
head = pkt[: off + 1 + pointer]
section = pkt[off + 1 + pointer :]
patched = patch_pmt_section(section)
packet = head + patched
packet = packet[:PACKET_LENGTH] + b"\xFF" * (PACKET_LENGTH - len(packet))
out += packet[:PACKET_LENGTH]
continue
out += pkt
for pid in list(pending):
flush(pid)
return bytes(out)
+6 -1
View File
@@ -378,7 +378,10 @@ class Widevine:
]
try:
subprocess.run(cmd, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8")
subprocess.run(
cmd, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
encoding="utf-8", errors="replace",
)
except subprocess.CalledProcessError as e:
error_msg = e.stderr if e.stderr else f"mp4decrypt failed with exit code {e.returncode}"
raise subprocess.CalledProcessError(e.returncode, cmd, output=e.stdout, stderr=error_msg)
@@ -426,6 +429,8 @@ class Widevine:
stdout=subprocess.DEVNULL,
stderr=subprocess.PIPE,
universal_newlines=True,
encoding="utf-8",
errors="replace",
)
stream_skipped = False
+3 -25
View File
@@ -29,8 +29,7 @@ from requests import Session
from unshackle.core import binaries
from unshackle.core.cdm.detect import is_playready_cdm, is_widevine_cdm
from unshackle.core.constants import DOWNLOAD_CANCELLED, DOWNLOAD_LICENCE_ONLY, AnyTrack
from unshackle.core.drm import DRM_T, ClearKey, FairPlay, MonaLisa, PlayReady, Widevine
from unshackle.core.drm.fairplay import fairplay_kid_from_skd
from unshackle.core.drm import DRM_T, ClearKey, MonaLisa, PlayReady, Widevine
from unshackle.core.events import events
from unshackle.core.session import RnetResponse, RnetSession
from unshackle.core.tracks import Audio, DownloadContext, Subtitle, Tracks, Video
@@ -38,9 +37,6 @@ from unshackle.core.utilities import get_extension, is_close_match, log_event, t
from unshackle.core.utils.redact import safe_display_url
from unshackle.core.utils.subprocess import log_tool_run
# FairPlay HLS (cbcs) EXT-X-KEY keyformat; bridged to PlayReady (see drm/fairplay.py).
FAIRPLAY_KEYFORMAT = "com.apple.streamingkeydelivery"
class HLS:
SUPP_CODECS_RE = re.compile(r'SUPPLEMENTAL-CODECS="([^"]+)"', re.IGNORECASE)
@@ -906,16 +902,8 @@ class HLS:
if key is None:
encryption_data = None
elif not encryption_data or encryption_data[0] != key:
if (
key.keyformat
and key.keyformat.lower() == FAIRPLAY_KEYFORMAT
and isinstance(session_drm, FairPlay)
):
# Reuse already-licensed service FairPlay; skd KID encoding is service-specific.
drm = session_drm
else:
drm = HLS.get_drm(key, session)
if isinstance(drm, (Widevine, PlayReady)) and not getattr(drm, "content_keys", None):
drm = HLS.get_drm(key, session)
if isinstance(drm, (Widevine, PlayReady)):
try:
if map_data:
track_kid = track.get_key_id(map_data[1])
@@ -1259,9 +1247,6 @@ class HLS:
"com.microsoft.playready",
}:
return key
elif key.keyformat and key.keyformat.lower() == FAIRPLAY_KEYFORMAT:
# FairPlay (cbcs) bridged to PlayReady; key licensed via FairPlay DRM.
return key
else:
unsupported_systems.append(key.method + (f" ({key.keyformat})" if key.keyformat else ""))
else:
@@ -1302,13 +1287,6 @@ class HLS:
pssh=PR_PSSH(key.uri.split(",")[-1]),
pssh_b64=key.uri.split(",")[-1],
)
elif key.keyformat and key.keyformat.lower() == FAIRPLAY_KEYFORMAT:
# FairPlay -> PlayReady: synthesize FairPlay DRM from the skd KID. Services whose skd
# KID isn't a plain GUID/hex should supply the DRM via get_track_drm instead.
kid = fairplay_kid_from_skd(key.uri)
if not kid:
raise NotImplementedError(f"Could not derive a FairPlay content KID from key: {key}")
drm = FairPlay.from_kid(kid)
else:
raise NotImplementedError(f"The key system is not supported: {key}")
+18
View File
@@ -544,6 +544,8 @@ class Gluetun(Proxy):
["docker", "ps", "--format", "{{.Ports}}"],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=5,
)
if result.returncode == 0:
@@ -892,6 +894,8 @@ class Gluetun(Proxy):
],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=5,
)
if result.returncode != 0:
@@ -926,6 +930,8 @@ class Gluetun(Proxy):
["docker", "inspect", container_name, "--format", "{{.NetworkSettings.Ports}}"],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=5,
)
@@ -1109,6 +1115,8 @@ class Gluetun(Proxy):
["docker", "inspect", container_name, "--format", "{{.State.ExitCode}}:{{.State.Error}}"],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=5,
)
if result.returncode == 0:
@@ -1310,6 +1318,8 @@ class Gluetun(Proxy):
["docker", "ps", "-a", "--filter", f"name=^{container_name}$", "--format", "{{.Names}}:{{.Status}}"],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=5,
)
@@ -1328,6 +1338,8 @@ class Gluetun(Proxy):
["docker", "rm", "-f", container_name],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=10,
)
return True
@@ -1346,6 +1358,8 @@ class Gluetun(Proxy):
["docker", "rm", "-f", container_name],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=10,
)
else:
@@ -1354,6 +1368,8 @@ class Gluetun(Proxy):
["docker", "stop", container_name],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=10,
)
except subprocess.TimeoutExpired:
@@ -1363,6 +1379,8 @@ class Gluetun(Proxy):
["docker", "rm", "-f", container_name],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=5,
)
except subprocess.TimeoutExpired:
+2 -2
View File
@@ -35,7 +35,7 @@ class Hola(Proxy):
p = subprocess.check_output(
[self.binary, "-country", query, "-list-proxies"], stderr=subprocess.STDOUT
).decode()
).decode("utf-8", errors="replace")
if "Transaction error: temporary ban detected." in p:
raise ConnectionError("Hola banned your IP temporarily from it's services. Try change your IP.")
@@ -55,6 +55,6 @@ class Hola(Proxy):
def get_countries(self) -> list[dict[str, str]]:
"""Get a list of available Countries."""
p = subprocess.check_output([self.binary, "-list-countries"]).decode("utf8")
p = subprocess.check_output([self.binary, "-list-countries"]).decode("utf-8", errors="replace")
return [{code: name} for country in p.splitlines() for (code, name) in [country.split(" - ", maxsplit=1)]]
+12 -6
View File
@@ -207,7 +207,8 @@ def _resolve_manifest_data(tracks: Tracks, manifests: list) -> None:
to copy track.data. HLS is skipped as it re-fetches from track.url.
"""
import base64 as b64
import zlib
from unshackle.core.api.compression import safe_inflate
if not manifests:
return
@@ -223,7 +224,7 @@ def _resolve_manifest_data(tracks: Tracks, manifests: list) -> None:
continue
try:
raw = zlib.decompress(b64.b64decode(m_data))
raw = safe_inflate(b64.b64decode(m_data))
if m_type == "dash":
from lxml import etree
@@ -836,17 +837,22 @@ class RemoteService:
if not cache_data:
return
import zlib
from unshackle.core.api.compression import safe_inflate
from unshackle.core.api.sanitize import safe_cache_key
cache_dir = config.directories.cache / self.service_tag
cache_dir.mkdir(parents=True, exist_ok=True)
for key, content in cache_data.items():
safe_name = safe_cache_key(key)
if not safe_name:
self.log.warning(f"Rejecting unsafe cache filename from server: {key!r}")
continue
try:
decompressed = zlib.decompress(base64.b64decode(content))
(cache_dir / key).with_suffix(".json").write_bytes(decompressed)
decompressed = safe_inflate(base64.b64decode(content))
(cache_dir / safe_name).with_suffix(".json").write_bytes(decompressed)
except Exception as e:
self.log.warning(f"Failed to save returned cache file '{key}': {e}")
self.log.warning(f"Failed to save returned cache file '{safe_name}': {e}")
self.log.info(f"Saved {len(cache_data)} cache file(s) from server")
-22
View File
@@ -438,28 +438,6 @@ class Service(metaclass=ABCMeta):
# Delegates license handling to the Widevine license method by default if a service-specific PlayReady implementation is not provided.
return self.get_widevine_license(challenge=challenge, title=title, track=track)
def get_fairplay_license(
self, *, challenge: bytes, title: Title_T, track: AnyTrack
) -> Optional[Union[bytes, str]]:
"""
Get a license for a FairPlay track bridged through a PlayReady CDM.
The `challenge` is a PlayReady License Request generated by the PlayReady CDM
from a header synthesized off the FairPlay content KID (see `FairPlay`). The
response is the PlayReady license, read back by the CDM to recover the keys.
By default this delegates to `get_playready_license`, which is correct for
services whose PlayReady endpoint also serves FairPlay content (e.g. multi-DRM
backends). Override it when the FairPlay license request needs different
shaping (endpoint, headers, body) from the PlayReady one.
:param challenge: The license challenge from the PlayReady CDM.
:param title: The current `Title` from get_titles that is being executed.
:param track: The current `Track` needing decryption.
:return: The License response as Bytes or a Base64 string, returned as is.
"""
return self.get_playready_license(challenge=challenge, title=title, track=track)
def get_clearkey_license(
self, *, challenge: bytes, title: Title_T, track: AnyTrack
) -> Optional[Union[bytes, str, dict]]:
+8
View File
@@ -225,6 +225,8 @@ class Hybrid:
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
encoding="utf-8",
errors="replace",
)
if result_duration.returncode != 0:
@@ -257,6 +259,8 @@ class Hybrid:
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
encoding="utf-8",
errors="replace",
)
if result_streams.returncode != 0:
@@ -300,6 +304,8 @@ class Hybrid:
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
encoding="utf-8",
errors="replace",
)
# cropdetect outputs crop=w:h:x:y
@@ -603,6 +609,8 @@ class Hybrid:
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
encoding="utf-8",
errors="replace",
)
max_mdl = 1000
+20 -4
View File
@@ -277,7 +277,11 @@ class Tracks:
continue
self.audio.sort(key=lambda x: not is_close_match(language, [x.language]))
def sort_subtitles(self, by_language: Optional[Sequence[Union[str, Language]]] = None) -> None:
def sort_subtitles(
self,
by_language: Optional[Sequence[Union[str, Language]]] = None,
type_priority: Optional[Sequence[str]] = None,
) -> None:
"""
Sort subtitle tracks by various track attributes to a common P2P standard.
You may optionally provide a sequence of languages to prioritize to the top.
@@ -292,13 +296,25 @@ class Tracks:
- Normal
- Hard of Hearing (SDH/CC)
(Least to most captions expected in the subtitle)
type_priority overrides the Language Group Order with an explicit ranking of
"forced", "normal", and "sdh" (cc counts as sdh); unlisted types fall to the end.
The first track after sorting receives the default flag at mux time, so this also
controls which subtitle type becomes default.
"""
if not self.subtitles:
return
# language groups
self.subtitles.sort(key=lambda x: str(x.language))
self.subtitles.sort(key=lambda x: x.sdh or x.cc)
self.subtitles.sort(key=lambda x: x.forced, reverse=True)
if type_priority:
rank = {str(t).lower(): i for i, t in enumerate(type_priority)}
default_rank = len(rank)
self.subtitles.sort(
key=lambda x: rank.get("forced" if x.forced else "sdh" if (x.sdh or x.cc) else "normal", default_rank)
)
else:
self.subtitles.sort(key=lambda x: x.sdh or x.cc)
self.subtitles.sort(key=lambda x: x.forced, reverse=True)
# sections
for language in reversed(by_language or []):
if str(language) == "all":
@@ -697,7 +713,7 @@ class Tracks:
errors = []
warnings = []
mux_start_time = time.monotonic()
p = subprocess.Popen(full_command, text=True, stdout=subprocess.PIPE)
p = subprocess.Popen(full_command, text=True, encoding="utf-8", errors="replace", stdout=subprocess.PIPE)
for line in iter(p.stdout.readline, ""):
if line.startswith("#GUI#error") or line.startswith("#GUI#warning"):
errors.append(line)
+2
View File
@@ -456,6 +456,8 @@ class Video(Track):
],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
)
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"))
+3 -1
View File
@@ -84,7 +84,9 @@ def info_summary(rpu: Path) -> str:
"""Return the textual summary (`dovi_tool info -i ... -s`) for an RPU file."""
tool = _require_dovi_tool()
info_start = time.monotonic()
p = subprocess.run([tool, "info", "-i", str(rpu), "-s"], capture_output=True, text=True)
p = subprocess.run(
[tool, "info", "-i", str(rpu), "-s"], capture_output=True, text=True, encoding="utf-8", errors="replace"
)
log_tool_run(
"dovi_tool info",
"dovi_tool",
+1 -1
View File
@@ -66,7 +66,7 @@ def ffprobe(uri: Union[bytes, Path]) -> dict:
context={"tool": "ffprobe", "duration_ms": round((time.monotonic() - start) * 1000, 1)},
)
return {}
result = json.loads(ff.stdout.decode("utf8"))
result = json.loads(ff.stdout.decode("utf-8", errors="replace"))
if dl:
dl.log(
level="DEBUG",
+2
View File
@@ -41,6 +41,8 @@ def apply_tags(path: Path, tags: dict[str, str]) -> None:
check=False,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
)
log_tool_run(
"mkvpropedit tags",
-46
View File
@@ -10,14 +10,11 @@ from http.cookiejar import CookieJar
from typing import Any, Optional, Union
import click
import m3u8 # used by get_track_drm() to read the FairPlay skd key from a media playlist
from langcodes import Language
from unshackle.core.cdm.detect import is_playready_cdm, is_widevine_cdm
from unshackle.core.constants import AnyTrack
from unshackle.core.credential import Credential
from unshackle.core.drm import FairPlay # FairPlay->PlayReady bridge, see get_track_drm()
from unshackle.core.drm.fairplay import fairplay_kid_from_skd
from unshackle.core.manifests import DASH # also: HLS, ISM - see get_tracks() alternates
from unshackle.core.search_result import SearchResult
from unshackle.core.service import Service
@@ -65,8 +62,6 @@ class EXAMPLE(Service):
get_widevine_* service cert + license (per-segment PSSH via `track`)
get_playready_license PlayReady challenge POST
get_clearkey_license DASH org.w3.clearkey JWK Set POST (Laurl fallback)
get_track_drm FairPlay->PlayReady bridge: skd KID -> FairPlay DRM
get_fairplay_license license a FairPlay-bridged track (PlayReady challenge)
"""
# ALIASES: extra CLI tags that resolve to this service (e.g. `dl EX ...`).
@@ -503,47 +498,6 @@ class EXAMPLE(Service):
response.raise_for_status()
return response.json()
def get_track_drm(self, track: AnyTrack) -> Optional[list]:
# FairPlay -> PlayReady bridge (HLS only). FairPlay HLS (SAMPLE-AES / cbcs) ships a
# content KID in its `skd://` EXT-X-KEY but no PlayReady/Widevine PSSH. We derive
# that KID, synthesize a PlayReady header from it (FairPlay.from_kid) and license it
# through a PlayReady CDM. This only yields keys when the backend is multi-DRM (the
# same content key is licensable via PlayReady) - a FairPlay-only backend cannot be
# bridged. The framework calls this hook during DRM loading for tracks flagged
# needs_drm_loading; return None to fall back to the normal manifest-PSSH path.
if not is_playready_cdm(self.cdm):
return None # bridge needs a PlayReady CDM to build the challenge
playlist = m3u8.loads(self.session.get(track.url).text, track.url)
skd = next(
(k.uri for k in (playlist.keys or []) if k and k.keyformat == "com.apple.streamingkeydelivery"),
None,
)
if not skd:
return None
# Generic extractor handles GUID / ?KID= / 32-hex skd forms. If your service encodes
# the KID differently, parse the UUID yourself and call FairPlay.from_kid(kid) directly.
kid = fairplay_kid_from_skd(skd)
if not kid:
return None
return [FairPlay.from_kid(kid)]
def get_fairplay_license(
self, *, challenge: bytes, title: Title_T, track: AnyTrack
) -> Optional[Union[bytes, str]]:
# `challenge` is a PlayReady challenge built from the synthesized header. The base
# class defaults to get_playready_license, which is correct when one endpoint serves
# both FairPlay and PlayReady. Override (like this) only when the FairPlay license
# request needs a different endpoint, headers, or body from the PlayReady one.
license_url = self.config["endpoints"].get("fairplay_license") or self.config["endpoints"].get(
"playready_license"
)
if not license_url:
raise ValueError("FairPlay/PlayReady license endpoint not configured")
response = self.session.post(url=license_url, data=challenge)
response.raise_for_status()
return response.content
# For HLS AES-128 ClearKey or unencrypted content there is no license callback;
# the key comes from the manifest or a side endpoint and is attached to the
# track's DRM directly. Vaults (`self.cache` is separate) cache KID:KEY so repeat
-1
View File
@@ -11,7 +11,6 @@ endpoints:
widevine_license: https://api.domain.com/v1/license/widevine
playready_license: https://api.domain.com/v1/license/playready
clearkey_license: https://api.domain.com/v1/license/clearkey # DASH org.w3.clearkey (omit to use manifest Laurl)
fairplay_license: https://api.domain.com/v1/license/fairplay # FairPlay->PlayReady bridge (omit to reuse playready_license)
# Base64 Widevine service certificate (enables privacy-mode license requests).
certificate: null