MDN wants to learn about developers like you: https://qsurvey.mozilla.com/s3/MDN-dev-survey

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.
Working Draft Initial definition

Browser compatibility

Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 42 [1] (Yes) ?[2] ? 29 [1] ?
Feature Android Webview Chrome for Android Edge Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile
Basic support 43 [1] 42 [1] (Yes) ?[2] ? ? 29 ?

[1] The spec requires that the passed supportedConfigurations option contain at least one of audioCapabilities or videCapabilities, and that said parameters include a codec string. This was not enforced until Chrome 58/Opera45.

[2] Starting in Firefox 55, if neither audioCapabilities nor videoCapabilities is specified, a warning is output to the web console reminding developers that the specification has changed to require at a minimum audioCapabilities or videoCapabilities is specified, and that in the future, a NotSupported exception will be thrown in this situation.

In addition, Firefox 55 now 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 specified by the "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 in version 55 does begin to 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 posisble codecs which should be permitted, and therefore are valid requests.

See also

Document Tags and Contributors

 Contributors to this page: Sheppy, rillian, jpmedley, abbycar, rolfedh, Sebastianz, sjakthol, teoli
 Last updated by: Sheppy,