MediaCapabilities: метод decodingInfo()

Метод decodingInfo() интерфейса MediaCapabilities возвращает промис, который выполняется с информацией о том, насколько хорошо пользовательский агент может декодировать/отображать медиа с заданной конфигурацией.

Разрешенный объект содержит три булевых свойства supported, smooth, и powerefficient, которые указывают, будет ли поддерживаться декодирование описанного медиа и, если да, будет ли декодирование плавным и энергоэффективным.

Метод также может использоваться для проверки возможностей пользовательского агента по декодированию медиа, закодированных с использованием системы ключей, но только когда он вызывается в основном потоке и в безопасном контексте. Если конфигурация, переданная в свойстве configuration.keySystemConfiguration, поддерживается для декодирования данных, разрешенный промис также включает объект MediaKeySystemAccess, который можно использовать для создания объекта MediaKeys для настройки зашифрованного воспроизведения.

configuration

Объект со свойством type, либо свойством video или audio, содержащим конфигурацию соответствующего типа, и необязательно свойством keySystemConfiguration при декодировании защищённых ключом систем медиа:

type

Тип проверяемого медиа. Принимает одно из трёх значений:

file

Представляет конфигурацию, предназначенную для воспроизведения обычного файла.

media-source

Представляет конфигурацию, предназначенную для воспроизведения MediaSource.

webrtc

Представляет конфигурацию, предназначенную для получения данных с помощью RTCPeerConnection (не разрешено, когда keySystemConfiguration установлено).

video

Объект конфигурации для видеоисточника медиа. Он имеет следующие свойства:

contentType

Строка, содержащая допустимый тип MIME видео и (необязательно) codecs параметр.

width

Ширина видео.

height

Высота видео.

bitrate

Количество бит, используемых для кодирования одной секунды видеофайла.

framerate

Количество кадров в секунду для воспроизведения видео.

audio

Объект конфигурации для аудиоисточника медиа. Он имеет следующие свойства:

contentType

Строка, содержащая допустимый тип MIME аудио и (необязательно) codecs параметр.

channels

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

bitrate

Количество бит, используемых для кодирования одной секунды аудиофайла.

samplerate

Количество аудиосэмплов в секунду для аудиофайла.

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

Объект, определяющий конфигурацию системы ключей для защищённого медиа.

Примечание: Navigator.requestMediaKeySystemAccess() принимает массивы некоторых типов данных в аргументе supportedConfigurations.

Если указано, type должно быть media-source или file (не webrtc). Он имеет следующие свойства:

keySystem

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

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

Строка, указывающая имя типа данных для формата инициализирующих данных, например, "cenc", "keyids" и "webm". Разрешённые имена определены в Регистре форматов инициализирующих данных расширений защищённого медиа.

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

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

required

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

optional

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

not-allowed

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

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

Строка, указывающая, должен ли возвращаемый объект иметь возможность сохранять данные сессии или любой другой тип состояния. Допустимые значения:

required

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

optional

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

not-allowed

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

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

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

temporary

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

persistent-license

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

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

Конфигурация аудиодорожки системы ключей, связанная с audio конфигурацией выше. Если установлено, то audio конфигурация также должна быть установлена.

encryptionScheme

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

robustness

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

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

Конфигурация видеодорожки системы ключей, связанная с video конфигурацией выше. Если установлено, то video конфигурация также должна быть установлена.

encryptionScheme

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

robustness

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

A Promise, выполняющий с объектом, содержащим следующие атрибуты:

supported

true если медиаконтент может быть декодирован. В противном случае, это false.

smooth

true если воспроизведение медиа может быть воспроизведено со скоростью кадров, указанной в конфигурации, без необходимости пропуска кадров. В противном случае, это false.

powerEfficient

true если воспроизведение медиа будет экономичным с точки зрения потребления энергии. В противном случае, это false.

keySystemAccess

A MediaKeySystemAccess который может быть использован для создания объекта MediaKeys для настройки защищённого воспроизведения, или null если декодирование не поддерживается с использованием предоставленной конфигурации.

Браузеры будут отображать поддерживаемую конфигурацию медиа как smooth и powerEfficient до тех пор, пока не будут записаны статистические данные об этом устройстве. Все поддерживаемые аудиокодеки сообщают, что powerEfficient равно true.

TypeError

Выбрасывается, если configuration, переданное методу decodingInfo(), является недопустимым, либо из-за того, что тип не видео или аудио, либо contentType не является допустимым кодеком MIME, либо конфигурация декодирования медиа не является допустимым значением для type (файл, медиа-источник или webrtc), либо по любой другой ошибке в конфигурации медиа, переданной методу, включая пропуск значений.

InvalidStateError DOMException

Метод вызывается в рабочем потоке, когда configuration.keySystemConfiguration определён.

SecurityError DOMException

Метод вызывается вне защищённого контекста, и configuration.keySystemConfiguration определён.

decodingInfo() и метод Navigator.requestMediaKeySystemAccess() расширения API для зашифрованных медиа отражают принципиально разные подходы к выбору конфигурации для декодирования зашифрованных медиа.

Параметр конфигурации для Navigator.requestMediaKeySystemAccess() принимает массив возможных конфигураций и позволяет системе выбрать наиболее подходящую.

В отличие от этого, decodingInfo() принимает одну конфигурацию за раз. Ожидается, что вызывающий код выполнит decodingInfo() несколько раз, начиная с наиболее предпочтительных конфигураций и останавливаясь, как только найдёт конфигурацию, удовлетворяющую требованиям приложения к плавности воспроизведения, энергоэффективности или обоим параметрам. Другими словами, решение о выборе конфигурации возложено на вызывающий код.

Этот пример демонстрирует, как создать конфигурацию медиа для аудиофайла и использовать её в MediaCapabilities.decodingInfo().

//Create media configuration to be tested
const audioConfig = {
  type: "file", // or 'media-source' or 'webrtc'
  audio: {
    contentType: "audio/ogg; codecs=vorbis", // valid content type
    channels: 2, // audio channels used by the track
    bitrate: 132700, // number of bits used to encode 1s of audio
    samplerate: 5200, // number of audio samples making up that 1s.
  },
};

// check support and performance
navigator.mediaCapabilities.decodingInfo(audioConfig).then((result) => {
  if (result.supported) {
    log(
      `The audio configuration is supported${result.smooth ? ", smooth" : ", not smooth"}${result.powerEfficient ? ", power efficient" : ", not power efficient"}.`,
    );
  } else {
    log("The audio configuration is not supported");
  }
});

Аналогично, код ниже показывает конфигурацию для видеофайла.

const videoConfig = {
  type: "file",
  video: {
    contentType: "video/webm;codecs=vp8", // valid content type
    width: 800, // width of the video
    height: 600, // height of the video
    bitrate: 10000, // number of bits used to encode 1s of video
    framerate: 30, // number of frames making up that 1s.
  },
};

// check support and performance
navigator.mediaCapabilities.decodingInfo(videoConfig).then((result) => {
  if (result.supported) {
    log(
      `The video configuration is supported${result.smooth ? ", smooth" : ", not smooth"}${result.powerEfficient ? ", power efficient" : ", not power efficient"}.`,
    );
  } else {
    log("The video configuration is not supported");
  }
});

Этот пример показывает, как использовать decodingInfo() для выбора конфигурации медиа для зашифрованного контента.

Как и в предыдущем примере, мы определяем конфигурацию медиа, но на этот раз используем type от media-source (а не file), и указываем аудио- и видеоконтент. Мы также указываем простую keySystemConfiguration.

const encryptedMediaConfig = {
  type: "media-source", // or 'file'
  audio: {
    contentType: "audio/webm; codecs=opus",
    channels: 2, // audio channels used by the track
    bitrate: 132700, // number of bits used to encode 1s of audio
    samplerate: 48000, // number of audio samples making up that 1s.
  },
  video: {
    contentType: 'video/webm; codecs="vp09.00.10.08"',
    width: 800, // width of the video
    height: 600, // height of the video
    bitrate: 10000, // number of bits used to encode 1s of video
    framerate: 30, // number of frames making up that 1s.
  },
  keySystemConfiguration: {
    keySystem: "org.w3.clearkey",
    initDataType: "webm",
    distinctiveIdentifier: "required",
  },
};

В предыдущем примере мы использовали цепочку промисов, чтобы дождаться результата. Здесь мы выбрали использование async и await, чтобы дождаться результата, а затем вывести его.

getDecodingInfo(encryptedMediaConfig);

async function getDecodingInfo(mediaConfig) {
  const result = await navigator.mediaCapabilities.decodingInfo(mediaConfig);
  console.log(result);
  if (!result.supported) {
    log("This encrypted media configuration is not supported.");
    return;
  }

  // keySystemAccess is returned if decoding encrypted media is supported
  // This can be used to decrypt and playback the media
  if (!result.keySystemAccess) {
    log("Encrypted media support is not available.");
    return;
  }

  log(
    `The encrypted media configuration is supported${result.smooth ? ", smooth" : ", not smooth"}${result.powerEfficient ? ", power efficient" : ", not power efficient"}.`,
  );
}

Выводимый результат показан ниже.

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

Предполагая, что у нас уже есть Array медиа-конфигураций под названием orderedMediaConfigs, которые мы упорядочили от наиболее желаемых к наименее желаемым, мы можем использовать Array.prototype.map() для вызова decodingInfo() для каждой конфигурации и получить массив, содержащий все возвращённые объекты Promise.

const capabilitiesPromises = orderedMediaConfigs.map((mediaConfig) =>
  navigator.mediaCapabilities.decodingInfo(mediaConfig),
);

Затем мы используем for await...of цикл для итерации по промисам по мере их разрешения. В цикле мы сохраняем последнюю поддерживаемую конфигурацию в nonSmoothConfig, и выходим из цикла, как только найдём плавную конфигурацию, установив её как bestConfig.

// Assume this app wants a supported && smooth config.
let bestConfig = null;
let nonSmoothConfig = null;
for await (const mediaCapabilityInfo of capabilitiesPromises) {
  if (!mediaCapabilityInfo.supported) continue;

  if (!mediaCapabilityInfo.smooth) {
    nonSmoothConfig = mediaCapabilityInfo;
    continue;
  }

  bestConfig = mediaCapabilityInfo;
  break;
}

Если мы нашли плавную и поддерживаемую конфигурацию во время итерации (bestConfig), мы используем её для создания наших медиа-ключей и декодирования медиа. Если мы не обнаружили плавных конфигураций, мы можем вместо этого использовать nonSmoothConfig для декодирования медиа. Это будет последняя найденная поддерживаемая конфигурация, которая, из-за способа упорядочивания исходного orderedMediaConfigs, должна быть конфигурацией с наименьшей частотой кадров.

let keys = null;
if (bestConfig) {
  keys = await bestConfig.keySystemAccess.createMediaKeys();
  // ... use keys to decode media using best config
} else if (nonSmoothConfig) {
  console.log(
    "No smooth configs found. Using lowest resolution configuration!",
  );
  keys = await nonSmoothConfig.keySystemAccess.createMediaKeys();
  // ... use keys to decode media using lowest framerate config
} else {
  console.log("No supported configs!");
  // Fail!
}

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

• MediaCapabilities.encodingInfo()
• HTMLMediaElement.canPlayType() для файлов
• MediaSource.isTypeSupported() для медиа-источников
• Navigator.requestMediaKeySystemAccess()