Метод Navigator: requestMediaKeySystemAccess()

Метод requestMediaKeySystemAccess() интерфейса Navigator возвращает Promise, который предоставляет объект MediaKeySystemAccess, который можно использовать для доступа к конкретной системе ключей медиа, которая, в свою очередь, может использоваться для создания ключей для дешифрования потока медиа.

Этот метод является частью API расширений для зашифрованной медиа, который добавляет поддержку зашифрованной медиа и защищённого DRM видео на веб.

Этот метод может иметь видимые для пользователя эффекты, такие как запрос разрешения на доступ к одному или нескольким системным ресурсам. Учитывайте это, когда решаете, когда вызывать requestMediaKeySystemAccess(); вы не хотите, чтобы эти запросы происходили в неудобное время. Как общее правило, эту функцию следует вызывать только тогда, когда пора создавать и использовать объект MediaKeys с помощью метода возвращаемого объекта MediaKeySystemAccess - createMediaKeys().

keySystem

Строка, идентифицирующая систему ключей. Например, com.example.some-system или org.w3.clearkey.

supportedConfigurations

Непустой Array объектов, соответствующих объекту, возвращаемому методом MediaKeySystemAccess.getConfiguration. Будет использован первый элемент с удовлетворяющей конфигурацией.

Каждый объект может иметь следующие свойства:

Примечание: Либо videoCapabilities либо audioCapabilities может быть пустым, но не оба!

label Необязательно

Необязательная метка для конфигурации, которая по умолчанию равна "". Эта метка сохраняется для конфигураций, полученных с помощью MediaKeySystemAccess.getConfiguration.

initDataTypes

Массив строк, указывающих имена типов данных для поддерживаемых форматов начальных данных (по умолчанию — пустой массив). Эти имена, такие как "cenc", "keyids" и "webm", определены в реестре форматов начальных данных расширений для зашифрованной медиа.

audioCapabilities

Массив поддерживаемых возможностей аудио. Если массив пустой, тип контента не поддерживает возможности аудио.

Каждый объект в массиве имеет следующие свойства:

contentType

Строка, указывающая MIME-тип медиа-ресурса, например, "audio/mp4;codecs=\"mp4a.40.2\". Обратите внимание, что пустая строка недопустима, и если определение MIME-типа включает параметры, такие как codecs, они также должны быть включены.

encryptionScheme

Схема шифрования, связанная с типом контента, например, cenc, cbcs, cbcs-1-9. Это значение должно быть установлено приложением (по умолчанию null, указывая, что может быть использована любая схема шифрования).

robustness

Уровень надёжности, связанный с типом контента. Пустая строка означает, что любая возможность дешифровки и декодирования типа контента приемлема.

videoCapabilities

Массив поддерживаемых возможностей видео. Объекты в массиве имеют ту же форму, что и в audioCapabilities.

distinctiveIdentifier

Строка, указывающая, может ли реализация использовать «уникальные идентификаторы» (или уникальные постоянные идентификаторы) для любых операций, связанных с любым объектом, созданным из этой конфигурации. Разрешённые значения:

required

Возвращаемый объект должен поддерживать эту функцию.

optional

Возвращаемый объект может поддерживать эту функцию. Это значение по умолчанию.

not-allowed

Возвращаемый объект не должен поддерживать или использовать эту функцию.

persistentState

Строка, указывающая, должен ли возвращаемый объект уметь сохранять данные сеанса или любой другой тип состояния. Значения такие же, как для distinctiveIdentifier, и имеют такое же значение: required, optional (по умолчанию), not-allowed. Только сеансы «временного» типа могут быть созданы, когда сохранение состояния не разрешено.

sessionTypes

Массив строк, указывающих типы сеансов, которые должны быть поддерживаемы. Разрешённые значения включают:

temporary

Сеанс, для которого лицензия, ключ(и) и запись о сеансе или данные, связанные с сеансом, не сохраняются. Приложению не нужно управлять таким хранилищем. Реализации должны поддерживать этот вариант, и он является значением по умолчанию.

persistent-license

Сеанс, для которого лицензия (и, возможно, другие данные, связанные с сеансом) будут сохранены. Запись о лицензии и связанных ключах сохраняется даже если лицензия уничтожена, предоставляя подтверждение, что лицензия и связанные с ней ключ(и) больше не могут быть использованы клиентом.

A Promise, который выполняется с объектом MediaKeySystemAccess, представляющим конфигурацию системы ключей медиа, описанную keySystem и supportedConfigurations.

В случае ошибки возвращаемый Promise отклоняется с DOMException, имя которого указывает вид произошедшей ошибки.

NotSupportedError DOMException

Указанная keySystem не поддерживается платформой или браузером, или ни одна из конфигураций, указанных в supportedConfigurations, не может быть удовлетворена (например, если ни одна из codecs в contentType недоступна).

SecurityError DOMException

Использование этой функции было заблокировано Permissions-Policy: encrypted-media.

TypeError

Либо keySystem является пустой строкой, либо массив supportedConfigurations пустой.

В примере ниже показано, как использовать requestMediaKeySystemAccess(), указав систему ключей и конфигурацию.

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 */
  });

• API расширений для защищённого мультимедиа
• API захвата мультимедиа и потоков
• API WebRTC
• MediaCapabilities.decodingInfo()