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
ororg.w3.clearkey
. supportedConfigurations
-
A non-empty
Array
of objects conforming to the object returned byMediaKeySystemAccess.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 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
DOMException
-
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). SecurityError
DOMException
-
Use of this feature was blocked by a Permissions Policy.
TypeError
`-
Either
keySystem
is an empty string or thesupportedConfigurations
array is empty.
Specifications
Specification |
---|
Encrypted Media Extensions # navigator-extension-requestmediakeysystemaccess |
Browser compatibility
BCD tables only load in the browser
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.