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 objects conforming to the object returned by MediaKeySystemAccess.getConfiguration. 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

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

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