MediaCapabilities: decodingInfo() メソッド
decodingInfo()
は MediaCapabilities
インターフェイスのメソッドで、指定された構成でユーザーエージェントがメディアをどれだけデコード/表示できるかに関する情報で履行するプロミスを返します。
解決されたオブジェクトには、記述されているメディアのデコードに対応しているかどうか、また対応している場合は場合はデコードがスムーズかつ電力効率的に行われるかどうかを示す、3 つの論理値プロパティ supported
, smooth
, powerefficient
が格納されています。
このメソッドは、キーシステムでエンコードされたメディアをデコードするためのユーザーエージェントの能力を調べるためにも使用できますが、メインスレッドで安全なコンテキストで呼び出された場合のみです。
configuration.keySystemConfiguration
プロパティに渡された構成が、データのデコードに対応している場合、解決されたプロミスには MediaKeySystemAccess
オブジェクトも含まれることがあります。これは、暗号化された再生を設定するために使用できる MediaKeys
オブジェクトを作成するために使用できます。
メモ:
このプロパティで decodingInfo()
を呼び出すと、1 つ以上のシステムリソースにアクセスする許可を求めるなど、ユーザーに視認できる効果をもたらす可能性があります。
そのため、この関数は、アプリケーションが指定された構成で MediaKeys
オブジェクトを作成し、使用する準備ができたときにのみ呼び出すべきです。
構文
decodingInfo(configuration)
引数
configuration
-
type
プロパティと、適切な種類の構成を格納するvideo
またはaudio
プロパティ、および、オプションでキーシステムで暗号化されたメディアをデコードする際に使用するkeySystemConfiguration
を持つオブジェクトです。type
-
検査対象のメディアの種類。これは 3 つの値のうちの 1 つを取ります。
file
-
プレーンなファイル再生に使用することを意味する構成を表します。
media-source
-
MediaSource
の再生に使用することを意味する構成を表します。 webrtc
-
RTCPeerConnection
を使用して受信することを意味する構成を表します(keySystemConfiguration
が設定されている場合は許可されません)。
video
-
動画メディアソースの構成オブジェクト。 これは、以下のプロパティを持ちます。
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
が定義されています。
使用上のメモ
Navigator.requestMediaKeySystemAccess() との比較
decodingInfo()
と Navigator.requestMediaKeySystemAccess()
メソッド(Encrypted Media Extensions API )は、暗号化されたメディアをデコードするための構成を選択する根本的に異なる手法を反映しています。
Navigator.requestMediaKeySystemAccess()
の構成パラメーターは、利用可能な構成の配列を取り、システムが適切と考えるものを選べるようにします。
これに対して、decodingInfo()
は一度に取る構成は 1 つです。
呼び出し側が 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");
}
});
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
を指定します。
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!
}
対応している構成がない場合は、失敗してユーザーに通知するしかありません。
仕様書
Specification |
---|
Media Capabilities # ref-for-dom-mediacapabilities-decodinginfo |
ブラウザーの互換性
BCD tables only load in the browser