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

Browser compatibility

[1] The spec requires that the passed supportedConfigurations option contain at least one of audioCapabilities or videoCapabilities, and that said parameters include a codec string. The function does not exist in insecure contexts. 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

• Encrypted Media Extensions API
• Media Capture and Streams API
• WebRTC API