MediaDevices.getUserMedia()

MediaDevices.getUserMedia()メソッドは、カメラやスクリーンシェアリング、マイクのようなビデオやオーディオ入力装置の使用許可をユーザーに要求します。ユーザーが許可を出した場合、返却されたPromise は結果として生成されたMediaStreamオブジェクトとして解決されます。ユーザーが許可を拒否した場合やメディアが使用できない場合、PromiseはそれぞれPermissionDeniedErrorまたはNotFoundError で拒否されます。ユーザーが選択をする必要がないように、返却されたPromiseが解決も拒絶もしない可能性があることに注意してください。

構文

navigator.mediaDevices.getUserMedia(constraints);

パラメーター

constraints

MediaStreamConstraints オブジェクトは各種類に対するなんらかの要求に沿って、要求するメディアの種類を特定します。

constraintsパラメーターは、2つのメンバー（要求するメディアの種類を表すvideoとaudio）を含むMediaStreamConstaints オブジェクトです。どちらかまたは両方が特定されないといけません。ブラウザが与えられたconstraintsを満たす特定のメディアトラックを発見できない場合、返却されたPromiseはNotFoundErrorで拒否されます。

次の例は特定の要求はせずに、audioとvideoの両方を要求しています。

{ audio: true, video: true }

ユーザーのカメラやマイクについての情報はプライバシー上の理由からアクセスできない一方、アプリケーションは必要に応じて追加のconstraintsを使用することで、カメラやマイクの機能を要求できます。次の例は、1280x720のカメラ解像度を求めています。

{ audio: true, video: { width: 1280, height: 720 } }

ブラウザはこれに忠実であろうとしますが、正確にマッチしたものが使用できない場合や、ユーザーがこれをオーバーライドした場合は、異なる解像度を返すかもしれません。

機能を要求するために、min、maxまたは、exact（min==maxと同じ）キーワードを使用できます。次の例は最小として1280x720の解像度を要求しています。

{ audio: true, video: { width: { min: 1280 }, height: { min: 720 } } }

この解像度以上のカメラがない場合、返却されたPromiseはNotFoundErrorとして拒否され、ユーザーには通知されません。

動作が異なる理由は、プレーン値とidealと呼ばれるキーワードはそうではない一方、min、maxまたは、exactキーワードは本質的に必須であるためです。より充実したサンプルを示します。

{
  audio: true,
  video: { width: { min: 1024, ideal: 1280, max: 1920 },
           height: { min: 776, ideal: 720, max: 1080 } }
}

ideal値が使用された場合、重要性があります。これはブラウザが与えられたideal値からもっとも近い最適距離で設定（と複数ある場合はカメラ）を見つけようとすることを意味します。

プレーン値は本質的にidealです。これは上述の解像度の例をこのように書くこともできることを意味します。

{ audio: true, video: { width: { ideal: 1280 }, height: { ideal: 720 } } }

すべてのconstraintが数字なわけではありません。たとえば、次の例はリアカメラよりもフロントカメラ（利用できるなら）を選好します。

{ audio: true, video: { width: { facingMode: "user" } } }

リアカメラの要求の仕方。

{ audio: true, video: { facingMode: { exact: "environment" } } }

戻り値

Promise<MediaStream>オブジェクトを返します。 次の例が示すように、MediaStreamオブジェクトを適切な要素に割り当て、それを使用できます。

var p = navigator.mediaDevices.getUserMedia({ audio: true, video: true });

p.then(function(stream) {
   var video = document.querySelector('video');
   video.src = window.URL.createObjectURL(mediaStream);
   video.onloadedmetadata = function(e) {
      // Do something with the video here.
   };
};

p.catch(function(e) { console.log(e.name); }); // always check for errors at the end.

エラー

返却されたpromiseの拒否は DOMExceptionに構成されたMediaStreamErrorとして生成されます。関連するエラーは以下の通りです。

PermissionDeniedError

ユーザーまたはシステムにメディアデバイスの使用許可を拒否された。

NotFoundError

constraintsで特定された機能を満たすメディアトラックの種類が見つからない。

例

幅と高さ

古いブラウザでも使用できるポリフィルを含むmediaDevices.getUserMedia()の使用例です。

navigator.mediaDevices = navigator.mediaDevices || ((navigator.mozGetUserMedia || navigator.webkitGetUserMedia) ? {
   getUserMedia: function(c) {
     return new Promise(function(y, n) {
       (navigator.mozGetUserMedia ||
        navigator.webkitGetUserMedia).call(navigator, c, y, n);
     });
   }
} : null);

if (!navigator.mediaDevices) {
  console.log("getUserMedia() not supported.");
  return;
}

// Prefer camera resolution nearest to 1280x720.

var constraints = { audio: true, video: { width: 1280, height: 720 } };

navigator.mediaDevices.getUserMedia(constraints)
.then(function(stream) {
  var video = document.querySelector('video');
  video.src = window.URL.createObjectURL(stream);
  video.onloadedmetadata = function(e) {
    video.play();
  };
})
.catch(function(err) {
  console.log(err.name + ": " + err.message);
});

フレームレート

帯域幅に制限のあるWebRTC通信のようなケースでは、低フレームレートが望ましいかもしれません。

var constraints = { video: { frameRate: { ideal: 10, max: 15 } } };

フロントとバックカメラ

モバイルフォンでの例。

var front = false;
document.getElementById('flip-button').onclick = function() { front = !front; };

var constraints = { video: { facingMode: (front? "user" : "environment") } };

認可

インストールできるアプリケーション（たとえば、Firefox OS app）でgetUserMedia()を使用するには、マニフェストファイルに一つまたは両方のフィールドを設定する必要があります。

"permissions": {
  "audio-capture": {
    "description": "Required to capture audio using getUserMedia()"
  },
  "video-capture": {
    "description": "Required to capture video using getUserMedia()"
  }
}

さらなる情報は、permission: audio-captureとpermission: video-captureを見てください。

使用

ブラウザ実装状況

Chrome、Operaと古いバージョンのFirefoxの場合、代わりにレガシーであるnavigator.getUserMediaを見てください。

ChromeとOperaの実装

• ChromeとOperaでは、このpromiseベースのインターフェイスをadapter.jsポリフィルを通して使用できます。
• ChromeとOperaは旧来のconstraint構文を使用していますが、adapter.jsポリフィルを通して、ここに記述している構文を使用できます。

Firefoxの実装

• ・ここに記述しているconstraint構文はFirefox38から使用できます。前のバージョン（32-37）では、旧来のconstraint構文を使用していますが、adapter.jsポリフィルを通して、ここに記述している構文を使用できます。

関連項目

• 古いnavigator.getUserMedia - レガシーAPI。
• navigator.enumerateDevices - ユーザーが使用できるデバイスの種類と数を知ることができる。
• WebRTC - APIの導入ページ
• MediaStream API - media streamオブジェクトのAPI
• Taking webcam photos - videoよりも写真を撮るためにgetUserMedia()を使用するためのチュートリアル