MediaStreamTrack: applyConstraints() メソッド

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.

* Some parts of this feature may have varying levels of support.

applyConstraints()MediaStreamTrack インターフェイスのメソッドで、トラックに一連の制約を適用します。これらの制約により、ウェブサイトやアプリは、フレームレート、サイズ、エコーキャンセルなど、トラックの制約可能なプロパティに対して、理想的な値や受け入れられる範囲を設定することができます。

制約を使用することで、メディアが特定のガイドラインを満たすように保証することができます。 例えば、高密度の動画を推奨しますが、ネットワークに負担をかけないようにデータレートを低く保つためにフレームレートを少し低くする必要があるかもしれません。 また、理想的なサイズや受け入れられるサイズ、またはその範囲を指定することもできます。 推奨する制約を適用する方法の詳細については、能力と制約と設定制約の適用を参照してください。

構文

js
applyConstraints()
applyConstraints(constraints)

引数

constraints 省略可

トラックの制約可能プロパティに適用する制約を列挙した MediaTrackConstraints です。既存の制約は指定した新しい値で置き換えられ、含まれない制約可能プロパティは既定の制約に戻されます。 この引数を除外すると、現在設定されているカスタム制約はすべてクリアされます。 このオブジェクトは、プロミス (Promise) が解決するために適用しなければならない制約の基本設定を表します。 このオブジェクトは追加の MediaTrackConstraints オブジェクトの配列を含む高度なプロパティを格納することができます。

返値

制約が正常に適用されたときに解決するプロミス (Promise)。制約が適用できない場合、プロミス OverconstrainedError で拒否されます。これは、DOMException に追加引数として OverconstrainedError という名前を設定したもので、制約に合うものがなかったことを示します。 これは、指定する制約が厳しすぎて、トラックを構成しようとしたときに一致するものが見つからなかった場合に発生する可能性があります。

次の例では、基本的な制約と高度な制約を設定する方法を示します。 これは、ページまたはウェブアプリの幅が 640 ~ 1280 の間、高さが 480 ~ 720の間である必要があることを指定します。高度なプロパティではさらに、画像サイズは 1920 x 1280 が推奨され、利用できない場合は 1.333 のアスペクト比を指定します。なお、これらの制約は、仕様が「バックオフ戦略」と呼んでいるものも参照しています。

js
const constraints = {
  width: { min: 640, ideal: 1280 },
  height: { min: 480, ideal: 720 },
  advanced: [{ width: 1920, height: 1280 }, { aspectRatio: 1.333 }],
};

navigator.mediaDevices.getUserMedia({ video: true }).then((mediaStream) => {
  const track = mediaStream.getVideoTracks()[0];
  track
    .applyConstraints(constraints)
    .then(() => {
      // 画像キャプチャ API を使用するなど、トラックで何かを行う
    })
    .catch((e) => {
      // 利用できる端末では制約を満たすことができない
    });
});

仕様書

Specification
Media Capture and Streams
# dom-mediastreamtrack-applyconstraints

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
applyConstraints
aspectRatio constraint
autoGainControl constraint
channelCount constraint
deviceId constraint
displaySurface constraint
echoCancellation constraint
facingMode constraint
frameRate constraint
groupId constraint
height constraint
latency constraint
logicalSurface constraint
noiseSuppression constraint
resizeMode constraint
sampleRate constraint
sampleSize constraint
suppressLocalAudioPlayback constraint
Experimental
volume constraint
DeprecatedNon-standard
width constraint

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.
Deprecated. Not for use in new websites.
See implementation notes.
Requires a vendor prefix or different name for use.
Has more compatibility info.

関連情報