feat(drm): add native DASH ClearKey (org.w3.clearkey) support

unshackle's DASH parser only recognised Widevine and PlayReady ContentProtection, so services using W3C EME ClearKey had to fake a Widevine object and monkey-patch get_content_keys. Add a first-class ClearKeyCENC DRM type so services just implement a license callback.

- ClearKeyCENC (core/drm/clearkey_cenc.py): KID-based, no CDM/PSSH; builds the W3C JSON license request (unpadded base64url), parses the JWK Set response (dict/str/bytes), falls back to POSTing the manifest Laurl when the service returns None, decrypts via the same shaka/ mp4decrypt CENC path as Widevine
- DASH.get_drm emits ClearKeyCENC for scheme e2719d58-...; KID from own or sibling mp4protection cenc:default_KID, Laurl across dashif/legacy/ bare namespaces
- track.download dispatches prepare_drm for ClearKeyCENC; dl.prepare_drm gains a clearkey branch (cache/vault lookup, license-failure tolerated when content_keys pre-populated, vault push, export)
- Service.get_clearkey_license base callback (default None -> Laurl); drm_from_dict reconstructs ClearKeyCENC for export/import round-trip
- EXAMPLE service + config demo the callback
- Tests: tests/core/test_clearkey_cenc.py and an export round-trip case
- Docs: DRM_CONFIG.md ClearKey section
This commit is contained in:
imSp4rky
2026-06-11 12:26:57 -06:00
parent dd1633e603
commit 466bf610cc
11 changed files with 836 additions and 17 deletions

View File

@@ -344,6 +344,34 @@ that use MonaLisa handle ticket/key retrieval and CDM initialization internally.
---
## ClearKey DRM
Two distinct ClearKey mechanisms are supported; neither needs a CDM device or any DRM config:
### HLS AES-128 ClearKey
The key is fetched from (or near) the M3U8 `EXT-X-KEY` URI and segments are decrypted with
pure-Python AES-CBC. Fully automatic — nothing to configure.
### DASH ClearKey (`org.w3.clearkey`)
W3C EME ClearKey for DASH CENC content. The DASH parser recognises the clearkey
ContentProtection scheme (`urn:uuid:e2719d58-a985-b3c9-781a-b030af78d30e`), takes the KID from
`cenc:default_KID`, and reads the license server URL from the manifest's `<Laurl>` element when
present.
License flow: the W3C JSON license request (`{"kids": [...], "type": "temporary"}`) is POSTed to
the license server, which returns the content key as a JWK Set. Keys land in the same vault and
`--export` paths as Widevine/PlayReady, and decryption uses the same shaka-packager/mp4decrypt
CENC backends (`decryption` config option applies).
Service integration (simplest first):
1. Manifest carries a `<Laurl>` — works with zero service code.
2. Custom endpoint/headers — service overrides `get_clearkey_license`.
3. Bespoke key delivery — service pre-populates the DRM object's keys in `get_tracks`.
---
## key_vaults (list\[dict])
Key Vaults store your obtained Content Encryption Keys (CEKs) and Key IDs per-service.