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 examplecom.example.somesystem
ororg.w3.clearkey
. supportedConfigurations
- A non-empty
Array
ofMediaKeySystemConfiguration
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 bykeySystem
andsupportedConfigurations
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 bysupportedConfigurations
can be satisfied (if, for example, none of thecodecs
specified incontentType
are available). TypeError
- Either
keySystem
is an empty string or thesupportedConfigurations
array is empty.
Specifications
Specification | Status | Comment |
---|---|---|
Encrypted Media Extensions The definition of 'requestMediaKeySystemAccess()' in that specification. |
Recommendation | Initial definition |
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.