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 Clear Key DRM System.
Generally IV should be provided where possible. If not provided, it will be set to of the same bit-size of the key.
classmethod
¶
Load a ClearKey from an M3U(8) Playlist's EXT-X-KEY.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
m3u_key
|
Key
|
A Key object parsed from a m3u(8) playlist using
the |
required |
session
|
Optional[Session]
|
Optional 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 content.
Distinct from the HLS AES-128 ClearKey class: keys here are delivered by a
license server as a JWK Set keyed by KID, and content is standard CENC
(decrypted with shaka-packager/mp4decrypt KID:KEY pairs, same as Widevine).
Serialise this DRM instance for export/import (KIDs + license URL).
Content keys are stored once at the export's track level, not duplicated here.
Build the W3C EME ClearKey JSON license request for the unkeyed KIDs.
Obtain Content Keys for this DRM Instance from a ClearKey license server.
The licence param is expected to be a function and will be provided with 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 provided a
Laurl, the challenge is POSTed 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 the track has not yet been downloaded. SubprocessError if the decryption process returned a non-zero exit code.
MonaLisa DRM System.
Unlike Widevine/PlayReady, MonaLisa does not use a challenge/response flow with a license server. Instead, the PSSH value (ticket) is provided directly by the service API, and keys are extracted locally via a WASM module.
Decryption is performed in two stages: 1. ML-Worker binary: Removes MonaLisa encryption layer (bbts -> ents) 2. AES-ECB decryption: Final decryption with service-provided key
Initialize 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 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 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 key hex string. |
Bases: Exception
Raised when no PSSH/ticket data is provided.
Bases: Exception
Raised when 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
¶
Create 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 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 via the on_segment_downloaded callback. By the time this method is called, the content has already been decrypted and muxed into a container.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Path to the file (ignored). |
required |
PlayReady DRM System.
Serialise this DRM instance for export/import (PSSH + KIDs).
Content keys are stored once at the export's track level, not duplicated here.
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 the track has not yet been downloaded. SubprocessError if the decryption process returned a non-zero exit code.
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.
Create a Widevine DRM System object from a track's information. This should only be used if a PSSH could not be provided directly. It is rare to need to use this.
You may provide your own requests session to be able to use custom headers and more.
classmethod
¶
Get PSSH and KID from within Initialization Segment Data.
This should only be used if a PSSH could not be provided directly. It is rare to need to use this.
Serialise this DRM instance for export/import (PSSH + KIDs).
Content keys are stored once at the export's track level, not duplicated here.
Create a CDM Session and obtain Content Keys for this DRM Instance. The certificate and license params are expected to be a function and will be provided with the challenge and session ID.
Create a CDM Session and obtain Content Keys for this DRM Instance. The certificate and license params are expected to be a function and will be provided with the challenge and 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 the track has not yet been downloaded. SubprocessError if the decryption process returned a non-zero exit code.
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.