MediaStream画像キャプチャ

1. はじめに

この文書で定義されているAPIは、有効なMediaStreamTrack [GETUSERMEDIA]を介して参照される写真撮影デバイスから画像をキャプチャします。生成された画像はBlob （takePhoto()メソッド参照）や、ImageBitmap （grabFrame()参照）として取得できます。

機能や設定の取得、制約の適用は、対象が動画MediaStreamTrack かどうかによって2通りの方法があります。写真固有の機能や現在の設定はgetPhotoCapabilities()やgetPhotoSettings() で取得でき、takePhoto()の PhotoSettings 引数で設定できます。動画関連の機能・設定・制約の操作はMediaStreamTrackの拡張メカニズムを通じて行います。

2. セキュリティとプライバシーに関する考慮事項

プライバシーとセキュリティの考慮事項は[GETUSERMEDIA]で議論されており、この拡張仕様にも適用されます。

さらに、実装者はキャプチャされた画像からプライバシーに関わるデータの漏洩が追加で発生しないよう注意すべきです。たとえば、デジタル画像のメタデータ（例：EXIF）にユーザーの位置情報が埋め込まれると、ユーザーが予期しないプライベート情報が送信される可能性があります。

3. 画像キャプチャAPI

ユーザーエージェントはImage Capture APIを実装するためにPromiseをサポートしなければなりません。すべてのPromise オブジェクトには、resolve()およびreject()メソッドを持つリゾルバオブジェクトがあるものとします。

[Exposed=Window, SecureContext]
interface ImageCapture {
   constructor(MediaStreamTrack videoTrack);
   Promise<Blob>              takePhoto(optional PhotoSettings photoSettings = {});
   Promise<PhotoCapabilities> getPhotoCapabilities();
   Promise<PhotoSettings>     getPhotoSettings();

   Promise<ImageBitmap>       grabFrame();

   readonly attribute MediaStreamTrack track;
};

takePhoto() は、Blob形式でエンコードされたキャプチャ画像を返し、 grabFrame() はtrack の動画フィードから非エンコードのImageBitmapスナップショットを返します。

3.1. 属性

track, 型 MediaStreamTrack, 読み取り専用: コンストラクタに渡されたMediaStreamTrackです。

3.2. メソッド

ImageCapture(MediaStreamTrack videoTrack)

パラメータ	型	Nullable	Optional	説明
videoTrack	`MediaStreamTrack`	✘	✘	データのソースとして使用される`MediaStreamTrack`です。これは`track` 属性の値になります。コンストラクタに渡された`MediaStreamTrack` の`kind` 属性が`"video"`でなければ、`DOMException` の`NotSupportedError` 型がスローされます。

takePhoto(optional PhotoSettings photoSettings)

takePhoto() は、track をソースとするビデオキャプチャデバイスを用いて、設定されたPhotoSettings を含めて、単一の写真露光の結果を生成し、成功した場合はBlob 形式でエンコードされた画像を返します。このメソッドが呼び出された際、ユーザーエージェントは以下の手順を実行しなければなりません：

コンストラクターで提供されたreadyStateがtrackに対してliveでない場合、a promise rejected with、名前がInvalidStateErrorの新しいDOMExceptionを返し、これらの手順を中止する。
pを新しいプロミスとする。
以下の手順を並列で実行する：
1. trackの基盤となるソースから定義されたphotoSettingsを用いて、Blobに単一の静止画像としてデータを収集する。この方法は基盤となるデバイスによって異なる。
  デバイスは一時的にデータのストリーミングを停止し、適切な写真設定で再構成し、写真を撮影し、その後ストリーミングを再開してもよい（MAY）。この場合、ストリーミングの停止と再開は、該当するtrackでonmuteおよびonunmuteイベントが発火するべきである（SHOULD）。
2. 何らかの理由で操作が完了できない場合（例えば、takePhoto()メソッド呼び出しが短時間に複数回行われた場合など）、pを名前がUnknownErrorの新しいDOMExceptionで拒否し、これらの手順を中止する。
3. pをBlobオブジェクトで解決する。
pを返す。

パラメータ	型	Nullable	Optional	説明
settings	`PhotoSettings`	✔	✘	適用される`PhotoSettings` 辞書。

getPhotoCapabilities()

getPhotoCapabilities() は、利用可能な設定オプションの範囲を取得するために使用されます（存在する場合）。このメソッドが呼び出されたとき、ユーザーエージェントは以下の手順を実行しなければなりません:

コンストラクタで指定された readyState が track に対して live でない場合、新しい DOMException（名前が InvalidStateError）で拒否された promise を返し、これらの手順を中止する。
p を新しい promise とする。
以下の手順を並列で実行する:
1. track からデータを収集し、デバイスの利用可能な機能（必要に応じて範囲を含む）を含む PhotoCapabilities 辞書に格納する。この方法は基盤となるデバイスによって異なる。
2. 何らかの理由でデータが収集できない場合（例: MediaStreamTrack が非同期に終了した場合）、p を新しい DOMException （名前が OperationError）で拒否し、これらの手順を中止する。
3. p を PhotoCapabilities 辞書で解決する。
p を返す。

getPhotoSettings()

getPhotoSettings() は、現在の設定値を取得するために使用されます（存在する場合）。このメソッドが呼び出されたとき、ユーザーエージェントは以下の手順を実行しなければなりません:

コンストラクタで指定された readyState が track に対して live でない場合、新しい DOMException（名前が InvalidStateError）で拒否された promise を返し、これらの手順を中止する。
p を新しい promise とする。
以下の手順を並列で実行する:
1. track からデータを収集し、デバイスが現在置かれている条件を含む PhotoSettings 辞書に格納する。この方法は基盤となるデバイスによって異なる。
2. 何らかの理由でデータが収集できない場合（例: MediaStreamTrack が非同期に終了した場合）、p を新しい DOMException （名前が OperationError）で拒否し、これらの手順を中止する。
3. p を PhotoSettings 辞書で解決する。
p を返す。

grabFrame()

grabFrame() は、track で保持されているライブビデオのスナップショットを撮影し、成功すると ImageBitmap を返します。grabFrame() は、呼び出された時点で一度だけデータを返します。このメソッドが呼び出されたとき、ユーザーエージェントは以下の手順を実行しなければなりません:

コンストラクタで指定された readyState が track に対して live でない場合、新しい DOMException（名前が InvalidStateError）で拒否された promise を返し、これらの手順を中止する。
p を新しい promise とする。
以下の手順を並列で実行する:
1. track からデータを収集し、ImageBitmap オブジェクトに格納する。width および height の値は track の制約から導かれる。
2. 何らかの理由で操作が完了できない場合（例: 複数の grabFrame()/takePhoto() メソッドが短時間で連続して呼び出された場合）、p を新しい DOMException （名前が UnknownError）で拒否し、これらの手順を中止する。
3. p を ImageBitmap オブジェクトで解決する。
p を返す。

4. PhotoCapabilities（写真機能）

dictionary PhotoCapabilities {
    RedEyeReduction         redEyeReduction;
    MediaSettingsRange      imageHeight;
    MediaSettingsRange      imageWidth;
    sequence<FillLightMode> fillLightMode;
};

4.1. Members（メンバー）

redEyeReduction, of type RedEyeReduction: ソースの赤目軽減機能。
imageHeight, of type MediaSettingsRange: UAがサポートする画像の高さの範囲を示します。
imageWidth, of type MediaSettingsRange: UAがサポートする画像の幅の範囲を示します。
fillLightMode, of type sequence<FillLightMode>: サポートされているフィルライトモード（フラッシュ）設定を示します（存在する場合）。

サポートされている解像度は、imageWidth および imageHeight の範囲として分離して提示されます。これはフィンガープリンティングのリスクを増加させないためと、UAが実際のハードウェア構成に関して最善の判断を行えるようにするためです。

5. PhotoSettings（写真設定）

dictionary PhotoSettings {
    FillLightMode   fillLightMode;
    double          imageHeight;
    double          imageWidth;
    boolean         redEyeReduction;
};

5.1. Members（メンバー）

redEyeReduction, of type boolean: カメラの赤目軽減を希望するかどうかを示します。
imageHeight, of type double: 希望する画像の高さを示します。UAが離散的な高さオプションのみサポートする場合、最も近い値が選択されます。
imageWidth, of type double: 希望する画像の幅を示します。UAが離散的な幅オプションのみサポートする場合、最も近い値が選択されます。
fillLightMode, of type FillLightMode: 希望するフィルライトモード（フラッシュ）設定を示します。

6. `MediaSettingsRange`（メディア設定範囲）

dictionary MediaSettingsRange {
    double max;
    double min;
    double step;
};

6.1. Members（メンバー）

max, of type double: この設定の最大値
min, of type double: この設定の最小値
step, of type double: この設定の連続する値の最小差分。

7. `RedEyeReduction`（赤目軽減）

enum RedEyeReduction {
    "never",
    "always",
    "controllable"
};

7.1. Values（値）

never: デバイスで赤目軽減は利用できません。
always: デバイスで赤目軽減が利用可能で、常に有効化されています。
controllable: デバイスで赤目軽減が利用可能で、redEyeReductionを通じてユーザーが制御できます。

8. `FillLightMode`（フィルライトモード）

enum FillLightMode {
    "auto",
    "off",
    "flash"
};

8.1. Values（値）

auto: ビデオデバイスのフィルライトは必要な場合（通常は低照度時）に有効化されます。それ以外はオフになります。autoはtakePhoto() 実行時に必ずフラッシュが発光することを保証しません。flash を使用すると、takePhoto() メソッドで必ずフラッシュが発光します。
off: ソースのフィルライトやフラッシュは使用されません。
flash: この値はtakePhoto() メソッドで必ずフラッシュが発光します。

9. Extensions（拡張）

このセクションでは、制約可能なプロパティの新しいセットを定義します。 MediaStreamTrack に適用することで、写真撮影により適した動作にできます。これらの制約はMediaStreamTrack の getCapabilities()、 getSettings()、 getConstraints() および applyConstraints() を通じて、ImageCapture オブジェクトの track の動作を変更します。

9.1. `MediaTrackSupportedConstraints` dictionary（辞書）

MediaTrackSupportedConstraints は、写真機能を制御するためにUAが認識する制約のリストで拡張されます。この辞書はMediaDevices の getSupportedConstraints() メソッドで取得できます。

partial dictionary MediaTrackSupportedConstraints {
    boolean whiteBalanceMode = true;
    boolean exposureMode = true;
    boolean focusMode = true;
    boolean pointsOfInterest = true;

    boolean exposureCompensation = true;
    boolean exposureTime = true;
    boolean colorTemperature = true;
    boolean iso = true;

    boolean brightness = true;
    boolean contrast = true;
    boolean pan = true;
    boolean saturation = true;
    boolean sharpness = true;
    boolean focusDistance = true;
    boolean tilt = true;
    boolean zoom = true;
    boolean torch = true;
};

9.1.1. Members（メンバー）

whiteBalanceMode, of type boolean, defaulting to true: ホワイトバランスモードの制約が認識されるかどうか。
colorTemperature, of type boolean, defaulting to true: 色温度の制約が認識されるかどうか。
exposureMode, of type boolean, defaulting to true: 露出の制約が認識されるかどうか。
exposureCompensation, of type boolean, defaulting to true: 露出補正の制約が認識されるかどうか。
exposureTime, of type boolean, defaulting to true: 露出時間の制約が認識されるかどうか。
iso, of type boolean, defaulting to true: ISOの制約が認識されるかどうか。
focusMode, of type boolean, defaulting to true: フォーカスモードの制約が認識されるかどうか。
pointsOfInterest, of type boolean, defaulting to true: 注目点がサポートされるかどうか。
brightness, of type boolean, defaulting to true: 明るさの制約が認識されるかどうか。
contrast, of type boolean, defaulting to true: コントラストの制約が認識されるかどうか。
pan, of type boolean, defaulting to true: パンの制約が認識されるかどうか。
saturation, of type boolean, defaulting to true: 彩度の制約が認識されるかどうか。
sharpness, of type boolean, defaulting to true: シャープネスの制約が認識されるかどうか。
focusDistance, of type boolean, defaulting to true: フォーカス距離の制約が認識されるかどうか。
tilt, of type boolean, defaulting to true: チルトの制約が認識されるかどうか。
zoom, of type boolean, defaulting to true: ズームレベルの設定が認識されるかどうか。
torch, of type boolean, defaulting to true: トーチの設定が認識されるかどうか。

9.2. `MediaTrackCapabilities` dictionary（辞書）

MediaTrackCapabilities は、画像キャプチャに特化した機能で拡張されます。この辞書はUAが getCapabilities() を通じて生成し、サポートされる制約の範囲や列挙値を表します。

partial dictionary MediaTrackCapabilities {
    sequence<DOMString>  whiteBalanceMode;
    sequence<DOMString>  exposureMode;
    sequence<DOMString>  focusMode;

    MediaSettingsRange   exposureCompensation;
    MediaSettingsRange   exposureTime;
    MediaSettingsRange   colorTemperature;
    MediaSettingsRange   iso;

    MediaSettingsRange   brightness;
    MediaSettingsRange   contrast;
    MediaSettingsRange   saturation;
    MediaSettingsRange   sharpness;

    MediaSettingsRange   focusDistance;
    MediaSettingsRange   pan;
    MediaSettingsRange   tilt;
    MediaSettingsRange   zoom;

    sequence<boolean> torch;
};

9.2.1. Members（メンバー）

whiteBalanceMode, of type sequence<DOMString>: サポートされているホワイトバランスモードのシーケンス。各文字列はMeteringModeのメンバーのいずれかでなければなりません。
colorTemperature, of type MediaSettingsRange: シーンのホワイトバランス計算に使用される、サポートされている相関色温度の範囲を示します。
exposureMode, of type sequence<DOMString>: サポートされている露出モードのシーケンス。各文字列はMeteringModeのメンバーでなければなりません。
exposureCompensation, of type MediaSettingsRange: サポートされている露出補正の範囲。通常は0EVを中心とした範囲です。
exposureTime, of type MediaSettingsRange: サポートされている露出時間の範囲。値は数値で、増加するほど露出時間が長くなります。
iso, of type MediaSettingsRange: 許可されているISO値の範囲。
focusMode, of type sequence<DOMString>: サポートされているフォーカスモードのシーケンス。各文字列はMeteringModeのメンバーでなければなりません。
brightness, of type MediaSettingsRange: カメラの明るさ設定のサポート範囲。値は数値で、増加するほど明るさが増します。
contrast, of type MediaSettingsRange: サポートされているコントラストの範囲。値は数値で、増加するほどコントラストが強くなります。
pan, of type MediaSettingsRange: UAおよびトラックがサポートするパン値の範囲。
トラックが利用許可のリクエストなしで作成された場合、または許可が拒否された場合、トラックはパンをサポートしません。その場合、UAはパン値の範囲を公開してはならず、基礎となるビデオソースがパンをサポートしていることを示すために空のMediaSettingsRange辞書を提供してもよいです。

UAが空のMediaSettingsRange辞書を提供しても、パン・チルト・ズームのサポートは、新たなgetUserMedia()呼び出しで、対応するビデオトラックが含まれる場合のみ利用可能です。
saturation, of type MediaSettingsRange: 許可されている彩度設定の範囲。値は数値で、増加するほど彩度が高くなります。
sharpness, of type MediaSettingsRange: カメラのシャープネスの許可範囲。値は数値で、増加するほどシャープネスが強くなり、最小値はシャープネス強調や処理なしを意味します。
focusDistance, of type MediaSettingsRange: UAがサポートするフォーカス距離値の範囲。
tilt, of type MediaSettingsRange: UAおよびトラックがサポートするチルト値の範囲。
トラックが利用許可のリクエストなしで作成された場合、または許可が拒否された場合、トラックはチルトをサポートしません。その場合、UAはチルト値の範囲を公開してはならず、基礎となるビデオソースがチルトをサポートしていることを示すために空のMediaSettingsRange辞書を提供してもよいです。
zoom, of type MediaSettingsRange: UAおよびトラックがサポートするズーム値の範囲。
トラックが利用許可のリクエストなしで作成された場合、または許可が拒否された場合、トラックはズームをサポートしません。その場合、UAはズーム値の範囲を公開してはならず、基礎となるビデオソースがズームをサポートしていることを示すために空のMediaSettingsRange辞書を提供してもよいです。
torch, of type sequence<boolean>: ソースがトーチをオンにできない場合、falseのみが報告されます。ソースがトーチをオフにできない場合、trueのみが報告されます。スクリプトが制御可能な場合、trueとfalseの両方が可能値として報告されます。

9.3. `MediaTrackConstraintSet` dictionary（辞書）

MediaTrackConstraintSet [GETUSERMEDIA] 辞書は、getConstraints() で現在の状態を取得したり、applyConstraints() で制約セットを適用するために使われます。

MediaTrackSettings は、UAが要求されたMediaTrackConstraintsを適用した効果を検証するために取得できます。ズームなど一部の制約は即時に適用されない場合があります。

partial dictionary MediaTrackConstraintSet {
    ConstrainDOMString           whiteBalanceMode;
    ConstrainDOMString           exposureMode;
    ConstrainDOMString           focusMode;
    ConstrainPoint2D             pointsOfInterest;

    ConstrainDouble              exposureCompensation;
    ConstrainDouble              exposureTime;
    ConstrainDouble              colorTemperature;
    ConstrainDouble              iso;

    ConstrainDouble              brightness;
    ConstrainDouble              contrast;
    ConstrainDouble              saturation;
    ConstrainDouble              sharpness;

    ConstrainDouble              focusDistance;
    (boolean or ConstrainDouble) pan;
    (boolean or ConstrainDouble) tilt;
    (boolean or ConstrainDouble) zoom;

    ConstrainBoolean             torch;
};

9.3.1. Members（メンバー）

whiteBalanceMode, of type ConstrainDOMString: この文字列はMeteringModeのメンバーのいずれかでなければなりません。ホワイトバランスモード制約可能プロパティ参照。
exposureMode, of type ConstrainDOMString: この文字列はMeteringModeのメンバーのいずれかでなければなりません。露出制約可能プロパティ参照。
focusMode, of type ConstrainDOMString: この文字列はMeteringModeのメンバーのいずれかでなければなりません。フォーカスモード制約可能プロパティ参照。
colorTemperature, of type ConstrainDouble: 色温度制約可能プロパティ参照。
exposureCompensation, of type ConstrainDouble: 露出補正制約可能プロパティ参照。
exposureTime, of type ConstrainDouble: 露出時間制約可能プロパティ参照。
iso, of type ConstrainDouble: iso制約可能プロパティ参照。
pointsOfInterest, of type ConstrainPoint2D: 注目点制約可能プロパティ参照。
brightness, of type ConstrainDouble: 明るさ制約可能プロパティ参照。
contrast, of type ConstrainDouble: コントラスト制約可能プロパティ参照。
pan, of type (boolean or ConstrainDouble): パン制約可能プロパティ参照。
saturation, of type ConstrainDouble: 彩度制約可能プロパティ参照。
sharpness, of type ConstrainDouble: シャープネス制約可能プロパティ参照。
focusDistance, of type ConstrainDouble: フォーカス距離制約可能プロパティ参照。
tilt, of type (boolean or ConstrainDouble): チルト制約可能プロパティ参照。
zoom, of type (boolean or ConstrainDouble): ズーム制約可能プロパティ参照。
torch, of type ConstrainBoolean: トーチ制約可能プロパティ参照。

9.4. `MediaTrackSettings` dictionary

ビデオストリームのトラック上でgetSettings() メソッドが呼び出された場合、ユーザーエージェントは基盤となるユーザーエージェントの現在の状態を表す拡張されたMediaTrackSettings 辞書を返さなければなりません。

partial dictionary MediaTrackSettings {
  DOMString         whiteBalanceMode;
  DOMString         exposureMode;
  DOMString         focusMode;
  sequence<Point2D> pointsOfInterest;

  double            exposureCompensation;
  double            exposureTime;
  double            colorTemperature;
  double            iso;

  double            brightness;
  double            contrast;
  double            saturation;
  double            sharpness;

  double            focusDistance;
  double            pan;
  double            tilt;
  double            zoom;

  boolean           torch;
};

9.4.1. Members

whiteBalanceMode, of type DOMString

現在のホワイトバランスモードの設定。文字列は MeteringMode のいずれかのメンバーでなければなりません。

exposureMode, of type DOMString

現在の露出モードの設定。文字列は MeteringMode のいずれかのメンバーでなければなりません。

colorTemperature, of type double

ホワイトバランス計算に使用される色温度。このフィールドは whiteBalanceMode が manual の場合にのみ意味を持ちます。

exposureCompensation, of type double

現在の露出補正の設定。0 EV の値は露出補正なしと解釈されます。このフィールドは exposureMode が continuous または single-shot の場合にのみ意味を持ちます。

exposureTime, of type double

現在の露光時間の設定。このフィールドは exposureMode が manual の場合にのみ意味を持ちます。

iso, of type double

現在のカメラの ISO 設定。

focusMode, of type DOMString

現在のフォーカスモードの設定。文字列は MeteringMode のいずれかのメンバーでなければなりません。

pointsOfInterest, of type sequence<Point2D>

他の設定（例：フォーカス、露出、自動ホワイトバランス）で使用される注目点（points of interest）として使用される Point2D のシーケンス。

brightness, of type double

これはカメラの現在の明るさ（brightness）設定を反映します。

contrast, of type double

これはカメラの現在のコントラスト（contrast）設定を反映します。

pan, of type double

これはカメラの現在のパン（pan）設定を反映します。

もしトラックが使用の許可を要求する（[permissions] に定義された通り）ことなく作成されており、PermissionDescriptor の name メンバーが camera に設定され、かつその panTiltZoom メンバーが true に設定されていない、あるいはその許可要求が拒否された場合、そのトラックは pan をサポートしません。

その場合、UA は pan 設定を公開してはなりません。

saturation, of type double

これはカメラの現在の彩度（saturation）設定を反映します。

sharpness, of type double

これはカメラの現在のシャープネス（sharpness）設定を反映します。

focusDistance, of type double

これはカメラの現在のフォーカス距離（focus distance）設定を反映します。

tilt, of type double

これはカメラの現在のチルト（tilt）設定を反映します。

zoom, of type double

これはカメラの現在のズーム（zoom）設定を反映します。

その場合、UA は zoom 設定を公開してはなりません。

torch, of type boolean

現在のカメラのトーチ（torch）設定。

9.5. 追加の制約可能なプロパティ

dictionary ConstrainPoint2DParameters {
  sequence<Point2D> exact;
  sequence<Point2D> ideal;
};

typedef (sequence<Point2D> or ConstrainPoint2DParameters) ConstrainPoint2D;

9.5.1. Members

exact, of type sequence<Point2D>: 注目点（points of interest）の正確に要求される値。
ideal, of type sequence<Point2D>: 注目点（points of interest）の理想的（ターゲット）値。

10. 写真機能と制約可能なプロパティ

前述の多くの写真およびビデオ機能は、複数の方法で実装できるハードウェア機能を反映しており、定義が難しいものが多いです。さらに、メーカーは知的財産を保護するためにあいまいな定義を公開する傾向があります。

これらの写真機能および制約可能なプロパティの名前は、デバイス選択のための許可された必須制約の一覧には含まれていません。そのため、getUserMedia() では、これらの写真機能および制約可能なプロパティはrequired constraintsではなく、optional basic constraintsおよびadvanced constraintsでのみ制約できます。

White balance mode は、カメラが異なる色温度に合わせて調整するために使用する設定です。Color temperature は背景光の色温度（通常ケルビンで測定）です。この設定は通常実装によって自動かつ連続的に決定されますが、推定されたシーン照明の温度を実装にヒントとして渡すmanualモードを提供することも一般的です。一般的なモードの典型的な温度範囲は以下の通りです：

Mode	Kelvin range
incandescent	2500-3500
fluorescent	4000-5000
warm-fluorescent	5000-5500
daylight	5500-6500
cloudy-daylight	6500-8000
twilight	8000-9000
shade	9000-10000

Exposure は、感光素子に入る光量を指します。オート露出モード（single-shot または continuous の exposureMode）では、露光時間や絞りが写真の被写体に基づいて実装によって自動的に調整されます。manual の exposureMode では、これらのパラメータは固定の絶対値に設定されます。
Focus mode は撮影装置のフォーカス設定（例：auto または manual）を説明します。
Points of interest は、exposure、white balance mode、focus mode 等の他の設定で使用されるメータリング領域の中心点を表します。各点は Point2D です（通常これら3つの制御はいわゆる 3A アルゴリズム（オートフォーカス、オート露出、オートホワイトバランス）によって同時に変更されます）。
A Point2D Point of Interest は正規化された正方形空間内のピクセル位置を表すものとして解釈されます（{x,y} ∈ [0.0, 1.0]）。座標の原点 {x,y} = {0.0, 0.0} は左上隅を表し、{x,y} = {1.0, 1.0} は右下隅を表します：x 座標（列）は右方向に増加し、y 座標（行）は下方向に増加します。記載された限界を超える値は許容される最も近い値にクランプされます。
Exposure Compensation は、実装が現在使用している値から露出レベルを調整する数値的なカメラ設定です。この値はオート露出で有効な露出レベルにバイアスをかけるために使用され、通常は 0 EV（補正なし）を中心とする対称的な範囲になります。この値は single-shot および continuous の exposureMode でのみ使用されます。
Exposure Time は、感光素子に光が当たる時間の長さを制御する数値的なカメラ設定です。この値は manual の exposureMode で露出を制御するために使用されます。値は100マイクロ秒単位です。つまり、値が1.0は1/10000秒の露光時間、10000.0は1秒の露光時間を意味します。
The ISO 設定はカメラの光に対する感度を表します。これは数値で、値が小さいほど感度が大きくなります。この値は [iso12232] 標準に従うべきです。
Red Eye Reduction は、フラッシュの長時間露光によって発生する被写体の赤い瞳（「Red Eye」）の出現を抑制または防止するためのカメラ機能です。
[LIGHTING-VOCABULARY] は brightness を「ある領域がより多くまたはより少ない光を放出しているように見える視覚感覚の属性」と定義しており、本APIの文脈では写真対象から放出される光の見かけ上の量を調整する数値的なカメラ設定を指します。明るさを高くするとシーンの暗い領域の強度が増し、明るい部分の強度は圧縮されます。この設定の範囲と効果は実装依存ですが、一般に各ピクセルに飽和処理を伴って加算される数値になります。
Contrast は、シーンの明暗差を制御する数値的なカメラ設定です。コントラストを高くすると明暗差が拡大します。この設定の範囲と効果は実装依存ですが、ヒストグラム上での輝度レンジを大きくするような画素値の変換として理解できます。変換は単純なゲイン係数であることもあります。
[LIGHTING-VOCABULARY] は saturation を「明るさに対して評価される領域の色の鮮やかさ」と定義しており、本文脈ではシーン内の色の強度（すなわちグレー成分の量）を制御する数値的なカメラ設定を指します。非常に低い彩度は白黒に近い写真になります。彩度は contrast に似ていますが色に関するものであり、プラットフォーム依存ではありますが与えられた画像の色差成分に対して適用されるゲイン係数として理解できます。
Sharpness はシーンのエッジの強度を制御する数値的なカメラ設定です。シャープネスを高くするとエッジ部分のコントラストが高くなり、低くするとコントラストが減りエッジがぼやけます（ソフトフォーカス）。実装はプラットフォーム依存ですが、元画像にエッジ検出を適用した画像と元画像自体の線形結合として理解でき、その相対的な重みがこの sharpness によって制御されます。
Brightness, contrast, saturation and sharpness は [UVC] で規定されています。
Image width と image height は、潜在的なセンサー補正およびその他のアルゴリズムが実行された後の生成される写真画像のサポートされる/希望される解像度を表します。
サポートされる解像度は分離管理されます。例えば imageWidth および imageHeight の値/範囲を分離管理し、フィンガープリント攻撃面の増加を防ぎ、要求された制約に対する実際のハードウェア構成に関してUAがベストエフォートで決定できるようにします。
Focus distance はレンズの焦点距離を制御する数値的なカメラ設定です。設定は通常メートル単位で最適焦点距離までの距離を表します。
Pan はカメラのパンを制御する数値的なカメラ設定です。設定は弧秒（1度の1/3600）で表されます。値の範囲は -180*3600 弧秒から +180*3600 弧秒です。正の値は上から見たときに時計回りにパンし、負の値は上から見たときに反時計回りにパンします。
pan に関する制約はパン可能なカメラに対する選択において fitness distance を通じて影響します。現在のパン設定を上書きせずにこの影響を与えるために、pan は true に制約することができます。逆に false に制約するとパン機能を持つカメラは不利になります。

値が false 以外の値を持つ MediaTrackConstraintSet オブジェクトを使用する任意のアルゴリズムは、その pan 辞書メンバーが存在する場合、使用の許可を要求する（[permissions] の定義に従う）か、または pan 設定を公開しないことを選択しなければなりません。許可を要求する場合は PermissionDescriptor の name メンバーを camera に設定し、かつその panTiltZoom メンバーを true に設定しなければなりません。

もしトップレベル閲覧コンテキストの visibilityState の値が "hidden" である場合、applyConstraints() アルゴリズムは pan 辞書メンバーが false 以外の値を持つ場合に SecurityError を投げなければなりません。
Tilt はカメラのチルトを制御する数値的なカメラ設定です。設定は弧秒（1度の1/3600）で表されます。値の範囲は -180*3600 弧秒から +180*3600 弧秒です。正の値は正面から見たときにカメラを上向きにチルトし、負の値は正面から見たときに下向きにチルトします。
tilt に関する制約はチルト可能なカメラに対する選択において fitness distance を通じて影響します。現在のチルト設定を上書きせずにこの影響を与えるために、tilt は true に制約することができます。逆に false に制約するとチルト機能を持つカメラは不利になります。

値が false 以外の値を持つ MediaTrackConstraintSet オブジェクトを使用する任意のアルゴリズムは、その tilt 辞書メンバーが存在する場合、使用の許可を要求する（[permissions] の定義に従う）か、または tilt 設定を公開しないことを選択しなければなりません。許可を要求する場合は PermissionDescriptor の name メンバーを camera に設定し、かつその panTiltZoom メンバーを true に設定しなければなりません。

もしトップレベル閲覧コンテキストの visibilityState の値が "hidden" である場合、applyConstraints() アルゴリズムは tilt 辞書メンバーが false 以外の値を持つ場合に SecurityError を投げなければなりません。

pan および tilt を適用する順序は定義されておらず、UA は任意の順序で適用できます。実際にはこれらの値は絶対値なので順序が最終位置に影響するべきではありません。ただし、pan や tilt の適用が十分に遅い場合は、適用される順序が視覚的に目立つことがあります。
Zoom はレンズの焦点距離を制御する数値的なカメラ設定です。設定は通常比率を表し、例えば 4 は 4:1 のズーム比を意味します。最小値は通常 1（1:1、つまりズームなし）です。
zoom に関する制約はズーム可能なカメラに対する選択において fitness distance を通じて影響します。現在のズーム設定を上書きせずにこの影響を与えるために、zoom は true に制約することができます。逆に false に制約するとズーム機能を持つカメラは不利になります。

値が false 以外の値を持つ MediaTrackConstraintSet オブジェクトを使用する任意のアルゴリズムは、その zoom 辞書メンバーが存在する場合、使用の許可を要求する（[permissions] の定義に従う）か、または zoom 設定を公開しないことを選択しなければなりません。許可を要求する場合は PermissionDescriptor の name メンバーを camera に設定し、かつその panTiltZoom メンバーを true に設定しなければなりません。

もしトップレベル閲覧コンテキストの visibilityState の値が "hidden" である場合、applyConstraints() アルゴリズムは zoom 辞書メンバーが false 以外の値を持つ場合に SecurityError を投げなければなりません。
Fill light mode は撮影装置のフラッシュ設定（例：auto、off、on）を説明します。Torch は、ソースの補助光が継続的に接続されており、track がアクティブである限り点灯し続ける設定を説明します。

11. `MeteringMode`（測光モード）

enum MeteringMode {
  "none",
  "manual",
  "single-shot",
  "continuous"
};

11.1. Values（値）

none: このソースはフォーカス・露出・ホワイトバランスモードを提供しません。設定時は機能をオフにするコマンドとして解釈されます。
manual: キャプチャデバイスがレンズ位置・露出時間・ホワイトバランスを手動で制御するように設定されるか、そのようなモードが要求されます。
single-shot: キャプチャデバイスがワンショットオートフォーカス・一回限りの露出・ホワイトバランス計算に設定されるか、そのようなモードが要求されます。
continuous: キャプチャデバイスがシャッターラグほぼゼロの連続フォーカス・連続自動露出・ホワイトバランス計算に設定されるか、そのような連続フォーカス・露出・ホワイトバランス計算モードが要求されます。

12. `Point2D`（2次元座標）

Point2D は2次元空間内の位置を表します。座標の原点は空間の左上隅にあります。

dictionary Point2D {
  double x = 0.0;
  double y = 0.0;
};

12.1. Members（メンバー）

x, of type double, defaulting to 0.0: 水平（x座標）の値。
y, of type double, defaulting to 0.0: 垂直（y座標）の値。

13. 使用例

これらの例の一部修正版は、例えばこのCodePenコレクションでも参照できます。

13.1. カメラのパン・チルト・ズームを更新し `takePhoto()` を呼び出す

この例は、例えばこのCodePen でもほぼ同じ形で参照できます。

<html>
<body>
<video autoplay></video>
<img>
<div>
  <input id="pan" title="Pan" type="range" disabled />
  <label for="pan">パン</label>
</div>
<div>
  <input id="tilt" title="Tilt" type="range" disabled />
  <label for="tilt">チルト</label>
</div>
<div>
  <input id="zoom" title="Zoom" type="range" disabled />
  <label for="zoom">ズーム</label>
</div>
<script>
  let imageCapture;

  async function getMedia() {
    try {
      const stream = await navigator.mediaDevices.getUserMedia({
        video: {pan: true, tilt: true, zoom: true},
      });
      const video = document.querySelector('video');
      video.srcObject = stream;

      const [track] = stream.getVideoTracks();
      imageCapture = new ImageCapture(track);

      const capabilities = track.getCapabilities();
      const settings = track.getSettings();

      for (const ptz of ['pan', 'tilt', 'zoom']) {
        // パン・チルト・ズームが利用可能か確認
        if (!(ptz in settings)) continue;

        // スライダー要素にマッピング
        const input = document.getElementById(ptz);
        input.min = capabilities[ptz].min;
        input.max = capabilities[ptz].max;
        input.step = capabilities[ptz].step;
        input.value = settings[ptz];
        input.disabled = false;
        input.oninput = async event => {
          try {
            // Chromeではadvanced constraintsが必要
            await track.applyConstraints({[ptz]: input.value});
          } catch (err) {
            console.error("applyConstraints() failed: ", err);
          }
        };
      }
    } catch (err) {
      console.error(err);
    }
  }

  async function takePhoto() {
    try {
      const blob = await imageCapture.takePhoto();
      console.log("Photo taken: " + blob.type + ", " + blob.size + "B");

      const image = document.querySelector('img');
      image.src = URL.createObjectURL(blob);
    } catch (err) {
      console.error("takePhoto() failed: ", err);
    }
  }
</script>
</body>
</html>

13.2. `grabFrame()`でフレームを繰り返し取得

この例は、例えばこのCodePen でもほぼ同じ形で参照できます。

<html>
<body>
<canvas></canvas>
<button id="stopButton">フレーム取得停止</button>
<script>
  async function grabFrames() {
    try {
      const canvas = document.querySelector('canvas');
      const video = document.querySelector('video');

      const stream = await navigator.mediaDevices.getUserMedia({video: true});
      video.srcObject = stream;
      const [track] = stream.getVideoTracks();
      try {
        const imageCapture = new ImageCapture(track);

        stopButton.onclick = () => track.stop();

        while (track.readyState == 'live') {
          const imgData = await imageCapture.grabFrame();
          canvas.width = imgData.width;
          canvas.height = imgData.height;
          canvas.getContext('2d').drawImage(imgData, 0, 0);
          await new Promise(r => setTimeout(r, 1000));
        }
      } finally {
        track.stop();
      }
    } catch (err) {
      console.error(err);
    }
  }
</script>
</body>
</html>

13.3. フレーム取得と後処理

この例は、例えばこのCodePen でもほぼ同じ形で参照できます。

<html>
<body>
<canvas></canvas>
<script>
  async function grabFrames() {
    try {
      const canvas = document.querySelector('canvas');
      const video = document.querySelector('video');

      const stream = await navigator.mediaDevices.getUserMedia({video: true});
      video.srcObject = stream;
      const [track] = stream.getVideoTracks();
      try {
        const imageCapture = new ImageCapture(track);
        const imageBitmap = await imageCapture.grabFrame();

        // |imageBitmap| のピクセルは直接アクセスできないため、取得したフレームを <canvas> に描画し getImageData() で取得します。
        const ctx = canvas.getContext('2d');
        canvas.width = imageBitmap.width;
        canvas.height = imageBitmap.height;
        ctx.drawImage(imageBitmap, 0, 0);

        // <canvas> からピクセルを取得し、色を反転
        const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);

        const data = imageData.data;
        for (let i = 0; i < data.length; i += 4) {
          data[i] ^= 255;     // 赤
          data[i + 1] ^= 255; // 緑
          data[i + 2] ^= 255; // 青
        }
        // 最後に反転画像を <canvas> に描画
        ctx.putImageData(imageData, 0, 0);
      } finally {
        track.stop();
      }
    } catch (err) {
      console.error(err);
    }
  }
</script>
</body>
</html>

13.4. カメラのフォーカス距離を更新し `takePhoto()` を呼び出す

<html>
<body>
<video autoplay></video>
<img>
<input type="range" hidden>
<script>
  let imageCapture;

  async function getMedia() {
    try {
      const stream = await navigator.mediaDevices.getUserMedia({video: true});
      const video = document.querySelector('video');
      video.srcObject = stream;

      const [track] = stream.getVideoTracks();
      imageCapture = new ImageCapture(track);

      const capabilities = track.getCapabilities();
      const settings = track.getSettings();

      // フォーカス距離が利用可能か確認
      if (!capabilities.focusDistance) {
        return;
      }

      // フォーカス距離をスライダー要素にマッピング
      const input = document.querySelector('input[type="range"]');
      input.min = capabilities.focusDistance.min;
      input.max = capabilities.focusDistance.max;
      input.step = capabilities.focusDistance.step;
      input.value = settings.focusDistance;
      input.oninput = async event => {
        try {
          await track.applyConstraints({
            focusMode: "manual",
            focusDistance: input.value
          });
        } catch (err) {
          console.error("applyConstraints() failed: ", err);
        }
      };
      input.parentElement.hidden = false;
    } catch (err) {
      console.error(err);
    }
  }

  async function takePhoto() {
    try {
      const blob = await imageCapture.takePhoto();
      console.log("Photo taken: " + blob.type + ", " + blob.size + "B");

      const image = document.querySelector('img');
      image.src = URL.createObjectURL(blob);
    } catch (err) {
      console.error("takePhoto() failed: ", err);
    }
  }
</script>
</body>
</html>

MediaStream画像キャプチャ

概要

この文書のステータス

1. はじめに

2. セキュリティとプライバシーに関する考慮事項

3. 画像キャプチャAPI

3.1. 属性

3.2. メソッド

4. PhotoCapabilities（写真機能）

4.1. Members（メンバー）

5. PhotoSettings（写真設定）

5.1. Members（メンバー）

6. MediaSettingsRange（メディア設定範囲）

6.1. Members（メンバー）

7. RedEyeReduction（赤目軽減）

7.1. Values（値）

8. FillLightMode（フィルライトモード）

8.1. Values（値）

9. Extensions（拡張）

9.1. MediaTrackSupportedConstraints dictionary（辞書）

9.1.1. Members（メンバー）

9.2. MediaTrackCapabilities dictionary（辞書）

9.2.1. Members（メンバー）

9.3. MediaTrackConstraintSet dictionary（辞書）

9.3.1. Members（メンバー）

9.4. MediaTrackSettings dictionary

9.4.1. Members

9.5. 追加の制約可能なプロパティ

9.5.1. Members

10. 写真機能と制約可能なプロパティ

11. MeteringMode（測光モード）

11.1. Values（値）

12. Point2D（2次元座標）

12.1. Members（メンバー）

13. 使用例

13.1. カメラのパン・チルト・ズームを更新し takePhoto() を呼び出す

13.2. grabFrame()でフレームを繰り返し取得

13.3. フレーム取得と後処理

13.4. カメラのフォーカス距離を更新し takePhoto() を呼び出す

適合性

文書の規約

適合するアルゴリズム

索引

本仕様で定義される用語

参照によって定義された用語

参考文献

規定参考文献

参考情報

IDL索引

6. `MediaSettingsRange`（メディア設定範囲）

7. `RedEyeReduction`（赤目軽減）

8. `FillLightMode`（フィルライトモード）

9.1. `MediaTrackSupportedConstraints` dictionary（辞書）

9.2. `MediaTrackCapabilities` dictionary（辞書）

9.3. `MediaTrackConstraintSet` dictionary（辞書）

9.4. `MediaTrackSettings` dictionary

11. `MeteringMode`（測光モード）

12. `Point2D`（2次元座標）

13.1. カメラのパン・チルト・ズームを更新し `takePhoto()` を呼び出す

13.2. `grabFrame()`でフレームを繰り返し取得

13.4. カメラのフォーカス距離を更新し `takePhoto()` を呼び出す