Navigator: requestMediaKeySystemAccess() method
===============================================

 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
------


```js
requestMediaKeySystemAccess(keySystem, supportedConfigurations)
```

### Parameters

`keySystem`

 A string 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` `DOMException`

 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).


`SecurityError` `DOMException`

Use of this feature was blocked by a Permissions Policy.

`TypeError``

 Either `keySystem` is an empty string or the
 `supportedConfigurations` array is empty.


Specifications
--------------

| Specification |
| --- |
| Encrypted Media Extensions # navigator-extension-requestmediakeysystemaccess |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### 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:


```js
const clearKeyOptions = [
  {
    initDataTypes: ["keyids", "webm"],
    audioCapabilities: [{ contentType: "audio/webm" }],
    videoCapabilities: [{ contentType: "video/webm" }],
  },
];

navigator
  .requestMediaKeySystemAccess("org.w3.clearkey", clearKeyOptions)
  .then((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:


```js
const 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((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