Digital Rights Management configuration for Widevine, FairPlay, PlayReady, and more
AdobePrimeTimeDRMConfig
Interface
Properties
headers?
optionalheaders?:HttpHeaders
An object which specifies custom HTTP headers.
indivURL
indivURL:
string
The URL for individualization requests.
keySystemPriority?
optionalkeySystemPriority?:string[]
Specify the priority of PrimeTime DRM key system strings for this source. Non-specified strings which the player knows
will be put at the end of the list. The first key system string of this list, which is supported on the current platform
is used.
Since: 8.143.0
LA_URL?
optionalLA_URL?:string
The URL to the Adobe PrimeTime license server for this content (optional).
Can be defined in the configuration or taken out from the video manifest if defined there.
If the config URL is defined it has precedence over the URL defined in the manifest.
licenseRequestRetryDelay?
optionallicenseRequestRetryDelay?:number
Specifies how long in milliseconds should be waited before a license request should be retried.
maxLicenseRequestRetries?
optionalmaxLicenseRequestRetries?:number
Specifies how often a license request should be retried if was not successful (e.g. the license
server was not reachable). Default is 1. 0 disables retries.
mediaKeySystemConfig?
optionalmediaKeySystemConfig?:Object
An object which allows to specify configuration options of the DRM key system, such as
distinctiveIdentifier or persistentState (refer to
MediaKeySystemConfiguration for more details). Please note that these settings need to be supported by the
browser or playback will fail.
withCredentials?
optionalwithCredentials?:boolean
Set to true to send credentials such as cookies or authorization headers along with the license requests.
Default is false.
AppleFairplayDRMConfig
Interface
EZDRM Specific Example:
fairplay: {
LA_URL: 'http://fps.ezdrm.com/api/licenses/YOUR-CONTENT-ID',
certificateURL: 'YOUR-CERTIFICATE',
prepareContentId: (contentId) => {
const uri = contentId;
const uriParts = uri.split('://', 1);
const protocol = uriParts[0].slice(-3);
uriParts = uri.split(';', 2);
contentId = uriParts.length>1?uriParts[1]:'';
return protocol.toLowerCase()=='skd' ? contentId : '';
},
prepareLicenseAsync: (ckc) => {
return new Promise((resolve, reject) => {
const reader = new FileReader();
reader.addEventListener('loadend', () => {
const array = new Uint8Array(reader.result);
resolve(array);
});
reader.addEventListener('error', () => {
reject(reader.error);
});
reader.readAsArrayBuffer(ckc);
});
},
prepareMessage: (event, session) => {
return new Blob([event.message], {type: 'application/octet-binary'});
},
headers: {
'content-type': 'application/octet-stream',
},
useUint16InitData: true,
licenseResponseType: 'blob'
}DRMtoday by castLabs Specific Example:
fairplay: {
LA_URL: 'https://license-server-url-provided-by-drmtoday',
certificateURL: 'https://certificate-url-provided-by-drmtoday',
headers: {
'dt-custom-data': 'INSERT-YOUR-BASE64-ENCODED-CUSTOMDATA',
},
prepareMessage : (event, session) => {
return 'spc=' + encodeURIComponent(event.messageBase64Encoded) + '&' + session.contentId;
},
prepareContentId : (contentId) => {
const pattern='skd://drmtoday?';
let parameters;
let idx = contentId.indexOf(pattern);
if (idx > -1) {
parameters = contentId.substring(idx + pattern.length);
parameters = parameters.replace(/assetid/gi, 'assetId');
parameters = parameters.replace(/variantid/gi, 'variantId');
return parameters;
} else {
return '';
}
}
}Vualto Specific Example (requires Bitmovin Player 6.0+):
fairplay: {
LA_URL: 'http://fairplay-license.drm.technology/license',
certificateURL: 'http://fairplay-license.drm.technology/certificate',
certificateHeaders: {
'x-vudrm-token': arrayParams['token'],
},
headers: {
'Content-Type': 'application/json',
},
prepareMessage: (keyMessageEvent, keySession) => {
return JSON.stringify({
token: 'VUALTO_TOKEN',
contentId: keySession.contentId,
payload: keyMessageEvent.messageBase64Encoded
});
},
prepareContentId: (rawContentId) => {
const tmp = rawContentId.split('/');
return tmp[tmp.length - 1];
},
prepareCertificate: (cert) => {
return new Uint8Array(cert);
},
prepareLicense: (license) => {
return new Uint8Array(license);
},
licenseResponseType: 'arraybuffer'
}Properties
certificateHeaders?
optionalcertificateHeaders?:HttpHeaders
An object which specify custom HTTP headers for the certificate request (optional).
certificateURL?
optionalcertificateURL?:string
The URL to the Fairplay certificate of the license server.
Note: either certificateURL or serverCertificate is required for Fairplay.
getLicenseServerUrl?
optionalgetLicenseServerUrl?: (skdUrl) =>string
A callback function which gets the URI (without the skd: part) from the HLS manifest passed as parameter.
The function needs to return a string which is used as LA_URL “as is”.
Parameters
skdUrl
string
Returns
string
headers?
optionalheaders?:HttpHeaders
An object which specify custom HTTP headers for the license request (optional).
keySystemPriority?
optionalkeySystemPriority?:string[]
Specify the priority of FairPlay DRM key system strings for this source. Non-specified strings which the player knows
will be put at the end of the list. The first key system string of this list, which is supported on the current platform
is used.
Since: 8.143.0
LA_URL?
optionalLA_URL?:string
The URL to the Fairplay license server for this content (optional).
Can be defined in the configuration or taken out from the video manifest if defined there.
If the config URL is defined it has precedence over the URL defined in the manifest.
licenseResponseType?
optionallicenseResponseType?:HttpResponseType
Sets an explicit response type for the license request. Default response type for this request is
TEXT, e.g. EZDRM requires BLOB.
maxCertificateRequestRetries?
optionalmaxCertificateRequestRetries?:number
Specifies how often a certificate request should be retried if was not successful (e.g. the certificate URL
returns a 404). Default is 1. 0 disables retries.
maxLicenseRequestRetries?
optionalmaxLicenseRequestRetries?:number
Specifies how often a license request should be retried if was not successful (e.g. the license server
was not reachable). Default is 1. 0 disables retries.
prepareCertificate?
optionalprepareCertificate?: (data) =>ArrayBuffer
A function to prepare the certificate before passing it into the browser. This is needed if the server
response with anything else than the certificate, e.g. if the certificate is wrapped into a JSON object.
The server response is passed as parameter “as is” and the return type is expected to be an ArrayBuffer.
Parameters
data
any
Returns
ArrayBuffer
prepareContentId?
optionalprepareContentId?: (url) =>string
A function to prepare the contentId, which is sent to the Fairplay license server as request body
(optional). As many DRM providers expect different, vendor-specific messages, this can be done using
this user-defined function. The parameter is the URI extracted from the HLS manifset (m3u8) and the
return value should be the contentID as string.
Parameters
url
string
Returns
string
prepareLicense?
optionalprepareLicense?: (data) =>string
A function to prepare the license before passing it into the browser. This is needed if the server
response with anything else than the license, e.g. if the license is wrapped into a JSON object.
The server response is passed as parameter “as is” and the return type is expected to be a
Base64-encoded string.
Parameters
data
any
Returns
string
prepareLicenseAsync?
optionalprepareLicenseAsync?: (data) =>Promise<Uint8Array<ArrayBufferLike>>
Similar to prepareLicense, this callback can be used to prepare the license before passing it to the
browser, but the license can be processed asynchronously. Please note that this function must return a
promise and the parameter for the resolve function needs to be the Uint8Array, which is passed “as is”
to the browser. Using this function prevents prepareLicense from being called.
Parameters
data
any
Returns
Promise<Uint8Array<ArrayBufferLike>>
prepareMessage?
optionalprepareMessage?: (event,session) =>any
A function to prepare the license acquisition message which will be sent to the license acquisition
server (optional). As many DRM providers expect different, vendor-specific messages, this can be done
using this user-defined function. The first parameter is the key message event object as given by the
Fairplay Content Decryption Module (CDM), enhanced by the messageBase64Encoded attribute, which contains
the key message encoded as base64 encoded string. The second parameter is the ssion object, enhanced by
a contentId attribute.
Parameters
event
any
session
any
Returns
any
serverCertificate?
optionalserverCertificate?:ArrayBuffer
Defaults to null, e.g., certificate will be requested from the license server if required.
A key-system-specific server certificate used to encrypt license requests. Its use is optional and is meant as
an optimization to avoid a round-trip to request a certificate.
Note: either certificateURL or serverCertificate is required for Fairplay.
Since: 7.2
useUint16InitData?
optionaluseUint16InitData?:boolean
A flag to change between Uint8Array (default, value false) and Uint16Array initialization data.
Depends on the fairplay license server, most use Uint8Array but e.g. EZDRM requires Uint16Array.
withCredentials?
optionalwithCredentials?:boolean
Set to true to send credentials such as cookies or authorization headers along with the license requests.
Default is false.
ClearKeyDRMConfig
Interface
ClearKey DRM config to specify one or more decryption keys.
Example:
clearkey: [{
kid: 'eb676abbcb345e96bbcf616630f1a3da',
key: '100b6c20940f779a4589152b57d2dacb'
}, {
kid: 'fc787bccdb345e96bbcf61674102b4eb',
key: '211c7d30940f779a4589152c68a1cfba'
}]Extends
Array<ClearKeyDRMConfigEntry>
Indexable
[
n:number]:ClearKeyDRMConfigEntry
ClearKeyDRMConfigEntry
Interface
Defines a decryption key.
Optionally specifies the key ID for the given key. This is needed in multi-key scenarios as it allows the player to
select the correct key when audio/video tracks are encrypted with different keys.
Properties
key
key:
string
The key in hex string format.
Example: 100b6c20940f779a4589152b57d2dacb
kid?
optionalkid?:string
The key ID in hex string format.
Example: eb676abbcb345e96bbcf616630f1a3da
Optional in single-key scenarios where all tracks of the content are encrypted with one single key.
Required in multi-key scenarios to allow key selection when tracks are encrypted with different keys.
ClearKeyDRMServerConfig
Interface
Properties
headers?
optionalheaders?:HttpHeaders
An object which specifies custom HTTP headers.
DRMtoday by castLabs Specific Example:
headers : {
'dt-custom-data': 'INSERT-YOUR-BASE64-ENCODED-CUSTOMDATA'
}LA_URL
LA_URL:
string
A URL to the ClearKey license server for this content.
licenseRequestRetryDelay?
optionallicenseRequestRetryDelay?:number
Specifies how long in milliseconds should be waited before a license request should be retried.
maxLicenseRequestRetries?
optionalmaxLicenseRequestRetries?:number
Specifies how often a license request should be retried if it was not successful (e.g. the license
server was not reachable). Default is 1. 0 disables retries.
withCredentials?
optionalwithCredentials?:boolean
Set to true to send credentials such as cookies or authorization headers along with the license requests.
Default is false.
DRMConfig
Interface
Contains the configuration of the different DRM systems related to the source.
Properties
clearkey?
optionalclearkey?:ClearKeyDRMConfig|ClearKeyDRMServerConfig
If no Hollywood-grade DRM is required, clear key can be an alternative.
The player supports MPEG-CENC (Common Encryption) compatible AES-128 CTR encryption.
fairplay?
optionalfairplay?:AppleFairplayDRMConfig
Apple Fairplay DRM is supported in Safari on Mac OS X only.
immediateLicenseRequest?
optionalimmediateLicenseRequest?:boolean
When set to true, the license requests are made as soon as init data is available.
Otherwise, the license requests are made once data segments are pushed into the buffer.
Default is false.
playready?
optionalplayready?:PlayReadyDRMConfig
Microsoft PlayReady is supported in Edge and Internet Explorer 11 on Windows 8.1+.
preferredKeySystems?
optionalpreferredKeySystems?:string[]
When set, defines the key system priority used by the player to choose the key system if multiple
key systems are supported by the platform. Default is unset.
Allowed key system strings: ['widevine', 'playready', 'fairplay', 'primetime', 'tvkey']
primetime?
optionalprimetime?:AdobePrimeTimeDRMConfig
Adobe PrimeTime DRM is supported in Firefox 42+ on Windows only.
tvkey?
optionaltvkey?:TVKeyDRMConfig
TVKey DRM is supported on Samsung Smart TVs (2019+ models) that include HbbTV support and a hardware root of trust for TVKey or TVKey Cloud.
widevine?
optionalwidevine?:WidevineModularDRMConfig
Widevine Modular is supported in Chrome and Chromium-based browsers with Widevine CDM (e.g. Opera 15+).
MediaKeySystemConfig.DistinctiveIdentifier
Enum
Enumeration Members
NotAllowed
NotAllowed:
"not-allowed"
Optional
Optional:
"optional"
MediaKeySystemConfig.PersistentState
Enum
Enumeration Members
Optional
Optional:
"optional"
Required
Required:
"required"
MediaKeySystemConfig.SessionType
Enum
Enumeration Members
PersistentLicense
PersistentLicense:
"persistent-license"
Temporary
Temporary:
"temporary"
PlayReadyDRMConfig
Interface
Properties
customData?
optionalcustomData?:string
A custom data string sent along with the license request. This is only supported in browsers using
the legacy Microsoft prefixed EME (IE, Edge legacy).
forceSSL?
optionalforceSSL?:boolean
Specifies whether to upgrade all license requests to use SSL.
headers?
optionalheaders?:HttpHeaders
An object which specifies custom HTTP headers.
DRMtoday by castLabs Specific Example:
headers : {
'dt-custom-data': 'INSERT-YOUR-BASE64-ENCODED-CUSTOMDATA'
}keySystemPriority?
optionalkeySystemPriority?:string[]
Specify the priority of PlayReady DRM key system strings for this source. Non-specified strings which the player knows
will be put at the end of the list. The first key system string of this list, which is supported on the current platform
is used.
Since: 8.143.0
LA_URL?
optionalLA_URL?:string
An URL to the PlayReady license server for this content (optional).
Can be defined in the configuration or taken out from the video manifest if defined there.
If the config URL is defined it has precedence over the URL defined in the manifest.
licenseRequestRetryDelay?
optionallicenseRequestRetryDelay?:number
Specifies how long in milliseconds should be waited before a license request should be retried.
maxLicenseRequestRetries?
optionalmaxLicenseRequestRetries?:number
Specifies how often a license request should be retried if was not successful (e.g. the license
server was not reachable). Default is 1. 0 disables retries.
mediaKeySystemConfig?
optionalmediaKeySystemConfig?:MediaKeySystemConfiguration
An object which allows to specify configuration options of the DRM key system, such as
distinctiveIdentifier or persistentState (refer to
MediaKeySystemConfiguration for more details). Please note that these settings need to be supported by the
browser or playback will fail.
plaintextChallenge?
optionalplaintextChallenge?:boolean
Specifies, whether the Challenge specified in the keymessage is provided in plaintext
rather than being Base64 encoded.
On most desktop browsers, the Challenge is Base64 encoded, which requires additional preprocessing
before a license request can be sent. Devices like smart TVs or set-top boxes often already provide a
plaintext challenge in the key message, so the preprocessing step can be skipped. Default value is false.
retryOtherKeysOnHttpStatusCode?
optionalretryOtherKeysOnHttpStatusCode?:number[]
Specifies HTTP status codes that should trigger a retry with other key IDs instead of throwing an error.
When a license request fails with one of the specified status codes, the player will emit a Warning
and attempt to request licenses for other key IDs, if available.
This allows handling various DRM server responses flexibly. The PlayReady spec mandates that 500 status
codes are returned for all errors, so this is commonly set to [500] for multi-key scenarios where
some keys may be denied while others succeed.
Default is undefined (no automatic retry).
Example:
retryOtherKeysOnHttpStatusCode: [500] // Retry on Internal Server Error (common for PlayReady)utf8message?
optionalutf8message?:boolean
Specifies, whether the keymessage provided by the browser is already UTF-8 encoded.
On most desktop browsers, the keymessage is UTF-16 encoded, which requires additional preprocessing
before a license request can be sent. Devices like smart TVs or set-top boxes often already provide a
UTF-8 encoded key messages, so the preprocessing step can be skipped. Default value is false.
withCredentials?
optionalwithCredentials?:boolean
Set to true to send credentials such as cookies or authorization headers along with the license requests.
Default is false.
TVKeyDRMConfig
Interface
Properties
headers?
optionalheaders?:HttpHeaders
An object which specifies custom HTTP headers.
Example:
headers: {
'Authorization': 'Bearer Here'
}keySystemPriority?
optionalkeySystemPriority?:string[]
Specify the priority of TVKey DRM key system strings for this source. Non-specified strings which the player knows
will be put at the end of the list. The player will use the first key system string from this list that is supported on
the current platform.
LA_URL?
optionalLA_URL?:string
A URL to the TVKey license server for this content (optional).
Can be defined in the configuration or taken out from the video manifest if defined there.
If the config URL is defined it has precedence over the URL defined in the manifest.
licenseRequestRetryDelay?
optionallicenseRequestRetryDelay?:number
Specifies how long (in milliseconds) it should be waited before a license request is retried.
maxLicenseRequestRetries?
optionalmaxLicenseRequestRetries?:number
Specifies how often a license request should be retried if not successful (e.g. the license server
was not reachable). Default is 1. 0 disables retries.
mediaKeySystemConfig?
optionalmediaKeySystemConfig?:MediaKeySystemConfiguration
An object which allows to specify configuration options of the DRM key system, such as
distinctiveIdentifier or persistentState (refer to
MediaKeySystemConfiguration for more details). Please note that these settings need to be supported by the
browser otherwise playback will fail.
prepareLicense?
optionalprepareLicense?: (licenseObject) =>any
A function which gets the TVKey license from the server response.
Parameters
licenseObject
any
Returns
any
prepareMessage?
optionalprepareMessage?: (keyMessage) =>any
A function to prepare the license acquisition message which will be sent to the license acquisition
server.
Parameters
keyMessage
any
Returns
any
withCredentials?
optionalwithCredentials?:boolean
Set to true to send credentials such as cookies or authorization headers along with the license requests.
Default is false.
WidevineModularDRMConfig
Interface
Properties
audioRobustness?
optionalaudioRobustness?:string
Sets the robustness level for audio. The robustness specifies the security level of the DRM key system. If a
string specifies a higher security level than the system is able to support playback will fail. The lowest
security level is the empty string. The strings are specific to a key system and currently only the values for
Widevine are known based on the Chromium source
code:
SW_SECURE_CRYPTO(Widevine L3)SW_SECURE_DECODE(Widevine L3)HW_SECURE_CRYPTO(Widevine L2)HW_SECURE_DECODE(Widevine L1)HW_SECURE_ALL(Widevine L1)
headers?
optionalheaders?:HttpHeaders
An object which specifies custom HTTP headers.
BuyDRM/KeyOS Specific Example:
headers : {
customdata: 'AUTHENTICATION-XML'
}DRMtoday by castLabs Specific Example:
headers : {
'dt-custom-data': 'INSERT-YOUR-BASE64-ENCODED-CUSTOMDATA'
}keySystemPriority?
optionalkeySystemPriority?:string[]
Specify the priority of Widevine DRM key system strings for this source. Non-specified strings which the player knows
will be put at the end of the list. The first key system string of this list, which is supported on the current platform
is used.
Since: 8.143.0
LA_URL?
optionalLA_URL?:string
An URL to the Widevine license server for this content (optional).
Can be defined in the configuration or taken out from the video manifest if defined there.
If the config URL is defined it has precedence over the URL defined in the manifest.
licenseRequestRetryDelay?
optionallicenseRequestRetryDelay?:number
Specifies how long in milliseconds should be waited before a license request should be retried.
maxLicenseRequestRetries?
optionalmaxLicenseRequestRetries?:number
Specifies how often a license request should be retried if was not successful (e.g. the license server
was not reachable). Default is 1. 0 disables retries.
mediaKeySystemConfig?
optionalmediaKeySystemConfig?:MediaKeySystemConfiguration
An object which allows to specify configuration options of the DRM key system, such as
distinctiveIdentifier or persistentState (refer to
MediaKeySystemConfiguration for more details). Please note that these settings need to be supported by the
browser or playback will fail.
prepareLicense?
optionalprepareLicense?: (licenseObject) =>any
A function which gets the widevine license from the server. Is needed for custom widevine servers where
not only the license itself is responded, but instead the license is e.g. wrapped in an JSON object.
DRMtoday by castLabs Specific Example:
prepareLicense : (licenseObj) => {
const license = {license: licenseObj.license};
try {
const drmTodayObj = JSON.parse(String.fromCharCode.apply(null, licenseObj.license));
if (drmTodayObj && drmTodayObj.status && drmTodayObj.license) {
if (drmTodayObj.status === 'OK') {
const str = window.atob(drmTodayObj.license);
const bufView = new Uint8Array(new ArrayBuffer(str.length));
for (let i = 0; i < str.length; i++) {
bufView[i] = str.charCodeAt(i);
}
license.license = bufView;
} else {
// license not okay
}
} else {
// no valid DRMtoday license
}
} catch (e) {
// no valid DRMtoday license
}
return license;
};Parameters
licenseObject
any
Returns
any
prepareMessage?
optionalprepareMessage?: (keyMessage) =>any
A function to prepare the license acquisition message which will be sent to the license acquisition
server. As many DRM provider expect different, vendor-specific message, this can be done using this
user-defined function (optional / depending on the DRM server). The parameter is the key message event
object as given by the Widevine Content Decryption Module (CDM).
Default Implementation Example:
prepareMessage : (keyMessage) => {
return keyMessage.message;
}This will send just the actual key message as provided by the CDM to the license server.
Vualto Specific Example:
prepareMessage : (keyMessage) => {
return JSON.stringify({
token: VUALTO_TOKEN,
drm_info: Array.apply(null, new Uint8Array(keyMessage.message)),
kid: 'VUALTO_KID'
});
}This will send a JSON object to the license server. This object contains the Vualto-specific token (token),
a pre-processed key message (drm_info), and the key ID (kid).
Parameters
keyMessage
any
Returns
any
retryOtherKeysOnForbiddenLicense?
optionalretryOtherKeysOnForbiddenLicense?:boolean
Specifies the behavior in case the license request fails with a 403 Forbidden error. If set to true, the player
will emit a Warning, and try to request a new license for other key IDs, if available. Otherwise, the player will
throw an error. Default is false.
Deprecated: Use retryOtherKeysOnHttpStatusCode instead for more flexible status code handling.
retryOtherKeysOnHttpStatusCode?
optionalretryOtherKeysOnHttpStatusCode?:number[]
Specifies HTTP status codes that should trigger a retry with other key IDs instead of throwing an error.
When a license request fails with one of the specified status codes, the player will emit a Warning
and attempt to request licenses for other key IDs, if available.
This allows handling various DRM server responses flexibly. For example, different DRM vendors may use
different status codes to signal denied licenses (e.g., 403, 404, 500).
Default is undefined (no automatic retry). If both this and retryOtherKeysOnForbiddenLicense are set,
this option takes precedence.
Example:
retryOtherKeysOnHttpStatusCode: [403, 404] // Retry on Forbidden and Not FoundserverCertificate?
optionalserverCertificate?:ArrayBuffer
A server certificate to be used to encrypt messages to the DRM license server. The contents are Key
System-specific. It allows an application to proactively provide a server certificate to implementations that
support it to avoid the additional round trip, should the Content Decryption Module (CDM) request it. It is
intended as an optimization, and applications are not required to use it. If not set but required by the CDM, the
CDM will request a certificate from the DRM license server.
videoRobustness?
optionalvideoRobustness?:string
Sets the robustness level for video. The robustness specifies the security level of the DRM key system. If a
string specifies a higher security level than the system is able to support playback will fail. The lowest
security level is the empty string. The strings are specific to a key system and currently only the values for
Widevine are known based on the Chromium source
code:
SW_SECURE_CRYPTO(Widevine L3)SW_SECURE_DECODE(Widevine L3)HW_SECURE_CRYPTO(Widevine L2)HW_SECURE_DECODE(Widevine L1)HW_SECURE_ALL(Widevine L1)
withCredentials?
optionalwithCredentials?:boolean
Set to true to send credentials such as cookies or authorization headers along with the license requests.
Default is false.
DrmAPI
Interface
Methods
renewLicense()
renewLicense(
drmLicenseId):Promise<void>
Starts a DRM license renewal request for the license with the specified ID.
Works with PlayReady DRM only. (Widevine DRM is managing license renewals on its own).
FairPlay DRM license renewals are not supported yet.
Parameters
drmLicenseId
string
The ID of the DrmLicense that shall be renewed.
Returns
Promise<void>
A promise that resolves, if the license renewal request was successful and rejects otherwise.
Since: 8.52
DrmLicense
Interface
Properties
id
id:
string
keyIds
keyIds:
string[]
keySystemString
keySystemString:
string