MediaCapabilities: decodingInfo() メソッド

configuration

type プロパティと、適切な種類の構成を格納する video または audio プロパティ、および、オプションでキーシステムで暗号化されたメディアをデコードする際に使用する keySystemConfiguration を持つオブジェクトです。

type

検査対象のメディアの種類。これは 3 つの値のうちの 1 つを取ります。

file

プレーンなファイル再生に使用することを意味する構成を表します。

media-source

MediaSource の再生に使用することを意味する構成を表します。

webrtc

RTCPeerConnection を使用して受信することを意味する構成を表します（keySystemConfiguration が設定されている場合は許可されません）。

video

動画メディアソースの構成オブジェクト。 これは、以下のプロパティを持ちます。

contentType

有効な動画の MIME タイプ、および（オプションで）codecs 引数の入った文字列です。

width

映像の幅です。

height

映像の高さです。

bitrate

動画ファイルの 1 秒をエンコードするために使用するビット数。

framerate

動画再生の 1 秒を構成するフレーム数。

audio

音声メディアソースの構成オブジェクト。 これは、以下のプロパティを持ちます。

contentType

有効な音声の MIME タイプ、および（オプションで）codecs 引数の入った文字列です。

channels

音声トラックが使用するチャンネル数。

bitrate

音声ファイルの 1 秒をエンコードするのに用いるビット数。

samplerate

音声ファイルの 1 秒を構成する音声サンプルの数。

keySystemConfiguration 省略可

暗号化されたメディアのキーシステム構成を指定するオブジェクトです。

メモ: Navigator.requestMediaKeySystemAccess() は supportedConfigurations 引数内と同じデータ型の一部を取ります。

指定された場合、type は media-source または file である必要があります（webrtc は指定できません）。 これには以下のプロパティがあります。

keySystem

メディアキーシステムを識別する文字俺つです。 例えば org.w3.clearkey や com.widevine.alpha です。

initDataType 省略可

初期データ形式のデータ型名を示す文字列です。例えば "cenc"、"keyids"、"webm" です。 利用できる名前は、Encrypted Media Extensions Initialization Data Format Registry で定義されているものです。

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

コンテンツの型に関連付けられた堅牢性レベル。 空文字列は、コンテンツタイプを復号しデコードする能力であれば何でも受け入れられることを示します。

Promise で、以下の属性を持つオブジェクトで履行されます。

supported

メディアコンテンツがすべてデコードできる場合は true。そうでない場合は false。

smooth

メディアの再生が、フレームを落とすことなく構成で指定したフレームレートで再生できる場合は true、そうでない場合は false です。

powerEfficient

メディアの再生が電力効率的であれば true、そうでなければ false です。

keySystemAccess

MediaKeySystemAccess で、 MediaKeys オブジェクトを作成するのに使用することができ、暗号化された再生を設定します。または、指定された構成を使用したデコードに対応していない場合は null となります。

ブラウザーは、この端末の統計情報が記録されるまで、対応しているメディア構成をsmooth および powerEfficient と報告します。 対応している音声コーデックはすべて、powerEfficient を true と報告します。

TypeError

decodingInfo() メソッドに渡された configuration が不正な場合、つまり、型が映像または音声でない場合、contentType が有効なコーデック MIME タイプでない場合、メディアのデコード構成が type（ファイル、メディアソース、webrtc）の有効な値でない場合、またはメソッドに渡されたメディア構成に値の記載漏れなどその他のエラーがある場合に例外が発生します。

InvalidStateError DOMException

configuration.keySystemConfiguration が定義されている場合で、このメソッドがワーカーから呼び出された場合。

SecurityError DOMException

このメソッドが安全ではないコンテキストで呼び出され、configuration.keySystemConfiguration が定義されています。

decodingInfo() と Navigator.requestMediaKeySystemAccess() メソッド（Encrypted Media Extensions API ）は、暗号化されたメディアをデコードするための構成を選択する根本的に異なる手法を反映しています。

Navigator.requestMediaKeySystemAccess() の構成パラメーターは、利用可能な構成の配列を取り、システムが適切と考えるものを選べるようにします。

これに対して、decodingInfo() は一度に取る構成は 1 つです。 呼び出し側が decodingInfo() を複数回実行し、できれば最も推奨する構成から始め、スムーズで電力効率が良い、またはその両方というアプリケーションの要求を満たす構成をできるだけ早く探すことが期待されます。 言い換えれば、選択の決定は呼び出し側に委ねられます。

この例では、音声ファイルの場合のメディア構成を作成し、それを MediaCapabilities.decodingInfo() で使用する方法を示しています。

#log {
  height: 100px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

<pre id="log"></pre>

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

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

Similarly, the code below shows the configuration for a video file.

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(audioConfig).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 を指定します。

#log {
  height: 100px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

<pre id="log"></pre>

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

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() を使用して単一の構成に関する情報を取得する方法を示しました。 実際には、このメソッドは反復処理で複数の構成を呼び出すのが一般的であり、スムーズな再生や電力効率性など、アプリケーションの基準に一致する最初の対応構成を選択します。 これの動作する方法は後述します。

すでに orderedMediaConfigs という名前のメディア構成の配列 (Array) があり、最も望ましいものから望ましくないものへと順序付けされていると仮定すると、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()