DRM API¶
Auto-generated reference for the DRM systems: Widevine, PlayReady, ClearKey, and related helpers. For configuring DRM as a user, see DRM & CDM Setup.
AES-128 ClearKey (HLS) DRM system.
Give the IV where possible. If you do not give an IV, unshackle sets it to of the same bit-size as the content key.
Warn once per track that unshackle passed a segment through undecrypted.
classmethod
¶
Load a ClearKey from an M3U(8) Playlist's EXT-X-KEY.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
m3u_key
|
Key
|
A |
required |
session
|
Optional[Session]
|
Optional HTTP session used to request external URIs with. Useful to set headers, proxies, cookies, and so forth. |
None
|
W3C EME ClearKey (org.w3.clearkey) DRM System over MPEG-CENC tracks.
Distinct from the HLS AES-128 ClearKey class: a license server gives the keys
here as a JWK Set keyed by KID, and the media is standard CENC
(decrypted with shaka-packager/mp4decrypt KID:KEY pairs, same as Widevine).
Serialise this DRM instance for export/import (KIDs + license URL).
unshackle stores the content keys once at the export's track level, and does not duplicate them here.
Assemble the W3C EME ClearKey JSON license request for the unkeyed KIDs.
Get Content Keys for this DRM Instance from a ClearKey license server.
The licence param is a function. unshackle gives it the W3C JSON license
request as challenge. It may return the JWK Set license as a dict, JSON str,
or bytes. If it returns None and the manifest gave a Laurl, unshackle POSTs the
challenge there directly instead.
Decrypt a Track with ClearKey DRM (standard CENC). Args: path: Path to the encrypted file to decrypt Raises: EnvironmentError if the required decryption executable could not be found. ValueError if unshackle has not yet downloaded the track. SubprocessError if the decryption process returned a non-zero exit code.
Build the mp4decrypt --key arguments for every content key.
MonaLisa DRM System.
Unlike Widevine/PlayReady, MonaLisa does not use a challenge/response flow with a license server. Instead, the service API gives the PSSH value (ticket) directly, and a WASM module extracts the content keys locally.
Decryption has two stages: 1. ML-Worker binary: Removes MonaLisa encryption layer (bbts -> ents) 2. AES-ECB decryption: Final decryption with the service-supplied content key
Initialise MonaLisa DRM.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ticket
|
Union[str, bytes]
|
PSSH value from service API (base64 string or raw bytes). |
required |
aes_key
|
Union[str, bytes]
|
AES-ECB content key for second-stage decryption (hex string or bytes). |
required |
device_path
|
Path
|
Path to the CDM device file (.mld). |
required |
**kwargs
|
Any
|
Additional metadata stored in self.data. |
{}
|
Raises:
| Type | Description |
|---|---|
TicketNotFound
|
If ticket/PSSH is empty. |
KeyExtractionFailed
|
If content key extraction fails. |
property
¶
Get the raw PSSH/ticket value as a string.
Returns:
| Type | Description |
|---|---|
str
|
The raw PSSH value as a base64 string. |
property
¶
Extract the Content ID from the PSSH for display.
The PSSH contains an embedded Content ID at bytes 21-75 with format: H5DCID-V3-P1-YYYYMMDD-HHMMSS-MEDIAID-TIMESTAMP-SUFFIX
Returns:
| Type | Description |
|---|---|
Optional[str]
|
The Content ID string if extractable, None otherwise. |
property
¶
Get content keys in the same format as Widevine/PlayReady.
Returns:
| Type | Description |
|---|---|
dict[UUID, str]
|
Dictionary mapping KID to the content key hex string. |
Bases: Exception
Raised when the caller gives no PSSH/ticket data.
Bases: Exception
Raised when content key extraction from the ticket fails.
Bases: Exception
Raised when the ML-Worker binary is not found.
Bases: Exception
Raised when segment decryption fails.
classmethod
¶
Make a MonaLisa DRM instance from a PSSH/ticket.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ticket
|
Union[str, bytes]
|
PSSH value from service API. |
required |
aes_key
|
Union[str, bytes]
|
AES-ECB content key for second-stage decryption. |
required |
device_path
|
Path
|
Path to the CDM device file (.mld). |
required |
Returns:
| Type | Description |
|---|---|
MonaLisa
|
MonaLisa DRM instance with extracted keys. |
Decrypt a single segment using two-stage decryption.
Stage 1: ML-Worker binary (bbts -> ents) Stage 2: AES-ECB decryption (ents -> ts)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
segment_path
|
Path
|
Path to the encrypted segment file. |
required |
Raises:
| Type | Description |
|---|---|
WorkerNotFound
|
If ML-Worker binary is not available. |
DecryptionFailed
|
If decryption fails at any stage. |
MonaLisa uses per-segment decryption during download, through the on_segment_downloaded callback. When the caller calls this method, unshackle has already decrypted the media and muxed it into a container.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
_path
|
Path
|
Path to the file (ignored). |
required |
PlayReady DRM System.
Extract all KIDs from base64-encoded PSSH data.
Serialise this DRM instance for export/import (PSSH + KIDs).
unshackle stores the content keys once at the export's track level, and does not duplicate them here.
Extract keys from CDM session with cross-library compatibility.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cdm
|
Cdm
|
CDM instance |
required |
session_id
|
bytes
|
Session identifier |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary mapping KID UUIDs to hex keys |
staticmethod
¶
Return the decoded error string if a revocation HRESULT is present, else None.
Reads the code from the raw SOAP body (
Decrypt a Track with PlayReady DRM. Args: path: Path to the encrypted file to decrypt Raises: EnvironmentError if the required decryption executable could not be found. ValueError if unshackle has not yet downloaded the track. SubprocessError if the decryption process returned a non-zero exit code.
Build the mp4decrypt --key arguments for every content key.
Decrypt with shaka-packager (original method)
Widevine DRM System.
Bases: Exception
PSSH (Protection System Specific Header) was not found.
Bases: Exception
KID (Encryption Key ID) was not found.
Bases: Exception
CEK (Content Encryption Key) for KID was not found in License.
Bases: Exception
License returned no Content Encryption Keys.
classmethod
¶
Get PSSH and KID from within the Initiation Segment of the Track Data. It also tries to get PSSH and KID from other track data like M3U8 data as well as through FFprobe.
Make a Widevine DRM System object from a track's information. Use this method only when a PSSH cannot be given directly. It is rare to need to use this.
You can give your own requests.Session to use custom headers
and more.
Raises:
| Type | Description |
|---|---|
PSSHNotFound
|
If the PSSH was not found within the data. |
KIDNotFound
|
If the KID was not found within the data or PSSH. |
classmethod
¶
Get PSSH and KID from within Initialization Segment Data.
Use this method only when a PSSH cannot be given directly. It is rare to need to use this.
Raises:
| Type | Description |
|---|---|
PSSHNotFound
|
If the PSSH was not found within the data. |
KIDNotFound
|
If the KID was not found within the data or PSSH. |
Serialise this DRM instance for export/import (PSSH + KIDs).
unshackle stores the content keys once at the export's track level, and does not duplicate them here.
Make a CDM Session and get Content Keys for this DRM Instance. The certificate and license params are functions. unshackle gives them the challenge and the session ID.
Make a CDM Session and get Content Keys for this DRM Instance. The certificate and license params are functions. unshackle gives them the challenge and the session ID.
Decrypt a Track with Widevine DRM. Args: path: Path to the encrypted file to decrypt Raises: EnvironmentError if the required decryption executable could not be found. ValueError if unshackle has not yet downloaded the track. SubprocessError if the decryption process returned a non-zero exit code.
Build the mp4decrypt --key arguments for every content key.
Decrypt with shaka-packager (original method)
Reconstruct a Widevine/PlayReady/ClearKeyCENC DRM instance from its to_dict() form.
Rebuilds the PSSH from the stored base64 (KIDs for ClearKey, which has no PSSH) and re-injects any saved content keys so the resulting object can decrypt without contacting a license server.