Navigator.requestMediaKeySystemAccess()

The Navigator.requestMediaKeySystemAccess() method returns a Promise which delivers a MediaKeySystemAccess object that can be used to access a particular media key system, which can in turn be used to create keys for decrypting a media stream. This method is part of the Encrypted Media Extensions API, which brings support for encrypted media and DRM-protected video to the web.

This method may have user-visible effects such as asking for permission to access one or more system resources. Consider that when deciding when to call requestMediaKeySystemAccess(); you don't want those requests to happen at inconvenient times. As a general rule, this function should be called only when it's about time to create and use a MediaKeys object by calling the returned MediaKeySystemAccess object's createMediaKeys() method.

Syntax

Promise = Navigator.requestMediaKeySystemAccess(keySystem, supportedConfigurations);

Parameters

keySystem
A DOMString identifying the key system. For example com.example.somesystem or org.w3.clearkey.
supportedConfigurations
A non-empty Array of MediaKeySystemConfiguration objects. The first element with a satisfiable configuration will be used.

Return value

A Promise that, when resolved, delivers a MediaKeySystemAccess object to your fulfillment handler function. The fulfillment handler receives as input just one parameter:

mediaKeySystemAccess
A MediaKeySystemAccess object representing the media key system configuration described by keySystem and supportedConfigurations

Exceptions

In case of an error, the returned Promise is rejected with a DOMException whose name indicates what kind of error occurred.

NotSupportedError
Either the specified keySystem isn't supported by the platform or the browser, or none of the configurations specified by supportedConfigurations can be satisfied (if, for example, none of the codecs specified in contentType are available).
TypeError
Either keySystem is an empty string or the supportedConfigurations array is empty.

Specifications

Specification Status Comment
Encrypted Media Extensions
The definition of 'requestMediaKeySystemAccess()' in that specification.
Recommendation Initial definition

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung Internet
Basic supportChrome Full support 42
Notes
Full support 42
Notes
Notes The spec requires that the passed supportedConfigurations option contain at least one of audioCapabilities or videoCapabilities, and that said parameters include a codec string.
Notes The function does not exist in insecure contexts. This was not enforced until Chrome 58.
Edge Full support YesFirefox Full support Yes
Notes
Full support Yes
Notes
Notes Starting in Firefox 55, if neither audioCapabilities nor videoCapabilities is specified in supportedConfigurations, a warning is output to the web console.
Notes In addition, starting in Firefox 55, if in supportedConfigurations, either audioCapabilities's or videoCapabilities's contentType value doesn't specify a "codecs" substring to define allowed codecs within the media wrapper, a warning is output to the web console. See note below table for example and correction.
Notes In the future, if neither audioCapabilities nor videoCapabilities is specified in the supportedConfigurations, a NotSupported exception will be thrown.
IE ? Opera Full support 29
Notes
Full support 29
Notes
Notes The spec requires that the passed supportedConfigurations option contain at least one of audioCapabilities or videoCapabilities, and that said parameters include a codec string.
Notes The function does not exist in insecure contexts. This was not enforced until Opera 45.
Safari ? WebView Android Full support 43
Notes
Full support 43
Notes
Notes The spec requires that the passed supportedConfigurations option contain at least one of audioCapabilities or videoCapabilities, and that said parameters include a codec string.
Notes The function does not exist in insecure contexts. This was not enforced until version 58.
Chrome Android Full support 42
Notes
Full support 42
Notes
Notes The spec requires that the passed supportedConfigurations option contain at least one of audioCapabilities or videoCapabilities, and that said parameters include a codec string.
Notes The function does not exist in insecure contexts. This was not enforced until Chrome 58.
Edge Mobile Full support YesFirefox Android Full support Yes
Notes
Full support Yes
Notes
Notes Starting in Firefox 55, if neither audioCapabilities nor videoCapabilities is specified in supportedConfigurations, a warning is output to the web console.
Notes In addition, starting in Firefox 55, if in supportedConfigurations, either audioCapabilities's or videoCapabilities's contentType value doesn't specify a "codecs" substring to define allowed codecs within the media wrapper, a warning is output to the web console. See note below table for example and correction.
Notes In the future, if neither audioCapabilities nor videoCapabilities is specified in the supportedConfigurations, a NotSupported exception will be thrown.
Opera Android Full support 29
Notes
Full support 29
Notes
Notes The spec requires that the passed supportedConfigurations option contain at least one of audioCapabilities or videoCapabilities, and that said parameters include a codec string.
Notes The function does not exist in insecure contexts. This was not enforced until Opera 45.
Safari iOS ? Samsung Internet Android ?

Legend

Full support  
Full support
Compatibility unknown  
Compatibility unknown
See implementation notes.
See implementation notes.

Firefox compatibility notes

Firefox 55 outputs a warning to the console if a candidate MediaKeySystemConfiguration included in supportedConfigurations includes an audioCapabilities or videoCapabilities object whose value of contentType doesn't specify a "codecs" substring defining which codecs within the media wrapper format should be allowed.

For example:

let clearKeyOptions = [
  {
    initDataTypes: ['keyids', 'webm'],
    audioCapabilities: [
      { contentType: 'audio/webm' }
    ],
    videoCapabilities: [
      { contentType: 'video/webm' }
    ]
  }
];

navigator.requestMediaKeySystemAccess('org.w3.clearkey', clearKeyOptions)
.then(function(keySystemAccess) {
  /* use the access to get create keys */
});

The code above works in Firefox up to version 55, but version 55 onwards will output a warning to console, because "codecs" is not included in the contentType strings. This could be corrected as follows:

let clearKeyOptions = [
  {
    initDataTypes: ['keyids', 'webm'],
    audioCapabilities: [
      { contentType: 'audio/webm; codecs="opus"' },
      { contentType: 'audio/webm; codecs="vorbis"' }
    ],
    videoCapabilities: [
      { contentType: 'video/webm; codecs="vp9"' },
      { contentType: 'video/webm; codecs="vp8"' }
    ]
  }
];

navigator.requestMediaKeySystemAccess('org.w3.clearkey', clearKeyOptions)
.then(function(keySystemAccess) {
  /* use the access to get create keys */
});

In this revised example, the audio and video capabilities include possible codecs which should be permitted, and therefore are valid requests.

See also