Dash JS

Module: ProtectionController

Provides access to media protection information and functionality. Each ProtectionController manages a single MediaPlayer.models.ProtectionModel which encapsulates a set of protection information (EME APIs, selected key system, key sessions). The APIs of ProtectionController mostly align with the latest EME APIs. Key system selection is mostly automated when combined with app-overrideable functionality provided in ProtectionKeyController.

Source:
To Do:
  • ProtectionController does almost all of its tasks automatically after init() is called. Applications might want more control over this process and want to go through each step manually (key system selection, session creation, session maintenance).

Methods

closeKeySession(sessionToken)

Closes the key session and releases all associated decryption keys. These keys will no longer be available for decrypting media

Parameters:
Name Type Description
sessionToken SessionToken

the session token
Source:
Fires:
  • ProtectionController#event:KeySessionClosed

createKeySession(initData)

Create a new key session associated with the given initialization data from the MPD or from the PSSH box in the media

Parameters:
Name Type Description
initData ArrayBuffer

the initialization data
Source:
To Do:
  • In older versions of the EME spec, there was a one-to-one relationship between initialization data and key sessions. That is no longer true in the latest APIs. This API will need to modified (and a new "generateRequest(keySession, initData)" API created) to come up to speed with the latest EME standard
Fires:
  • ProtectionController#event:KeySessionCreated

initialize(manifest [, aInfo] [, vInfo])

Initialize this protection system with a given manifest and optional audio and video stream information.

Parameters:
Name Type Argument Description
manifest Object

the json version of the manifest XML document for the desired content. Applications can download their manifest using module:MediaPlayer#retrieveManifest
aInfo StreamInfo <optional>

audio stream information
vInfo StreamInfo <optional>

video stream information
Source:
To Do:
  • This API will change when we have better support for allowing applications to select different adaptation sets for playback. Right now it is clunky for applications to create StreamInfo with the right information,

loadKeySession(sessionID)

Loads a key session with the given session ID from persistent storage. This essentially creates a new key session

Parameters:
Name Type Description
sessionID string
Source:
Fires:
  • ProtectionController#event:KeySessionCreated

removeKeySession(sessionToken)

Removes the given key session from persistent storage and closes the session as if ProtectionController#closeKeySession was called

Parameters:
Name Type Description
sessionToken SessionToken

the session token
Source:
Fires:
  • ProtectionController#event:KeySessionRemoved
  • ProtectionController#event:KeySessionClosed

reset()

Destroys all protection data associated with this protection set. This includes deleting all key sessions. In the case of persistent key sessions, the sessions will simply be unloaded and not deleted. Additionally, if this protection set is associated with a HTMLMediaElement, it will be detached from that element.

Source:

setMediaElement(element)

Associate this protection system with the given HTMLMediaElement. This causes the system to register for needkey/encrypted events from the given element and provides a destination for setting of MediaKeys

Parameters:
Name Type Description
element HTMLMediaElement

the media element to which the protection system should be associated
Source:

setProtectionData(data)

Attach KeySystem-specific data to use for license acquisition with EME

Parameters:
Name Type Description
data Object

an object containing property names corresponding to key system name strings (e.g. "org.w3.clearkey") and associated values being instances of ProtectionData
Source:

setRobustnessLevel(level)

Sets the robustness level for video and audio capabilities. Optional to remove Chrome warnings. Possible values are SW_SECURE_CRYPTO, SW_SECURE_DECODE, HW_SECURE_CRYPTO, HW_SECURE_CRYPTO, HW_SECURE_DECODE, HW_SECURE_ALL.

Parameters:
Name Type Description
level string

the robustness level
Source:

setServerCertificate(serverCertificate)

Sets a server certificate for use by the CDM when signing key messages intended for a particular license server. This will fire an error event if a key system has not yet been selected.

Parameters:
Name Type Description
serverCertificate ArrayBuffer

a CDM-specific license server certificate
Source:
Fires:
  • ProtectionController#event:ServerCertificateUpdated

setSessionType(value)

Sets the session type to use when creating key sessions. Either "temporary" or "persistent-license". Default is "temporary".

Parameters:
Name Type Description
value string

the session type
Source: