CameraControl

  • Revision slug: DOM/CameraControl
  • Revision title: CameraControl
  • Revision id: 350789
  • Created:
  • Creator: Jeremie
  • Is current revision? No
  • Comment

Revision Content

{{ domref() }}

{{ non-standard_header() }}

When you obtain a reference to a camera by calling {{domxref("CameraManager.getCamera()")}}, the object passed as a parameter of the callback function called on success is a CameraControl object. You can use its methods and properties to manage and make use of the camera.

Properties

Name Type Description
{{domxref("CameraControl.capabilities","capabilities")}} {{domxref("CameraCapabilities")}} An object indicating all the capabilities for the given camera.
effect string A string defining the effect to be used by the camera (none by default). It's value must be one of the values available in {{domxref("CameraCapabilities")}}.effects.
exposureCompensation {{readonlyinline}} double

A value used to compensate the camera exposure. This attribute is read-only; to change the exposure, you need to call the {{domxref("CameraControl.setExposureCompensation()")}} method.

Acceptable values for this property must range from the value of the {{domxref("CameraCapabilities")}}.minExposureCompensation property  to the value of the {{domxref("CameraCapabilities")}}.maxExposureCompensation property in steps of the {{domxref("CameraCapabilities")}}.stepExposureCompensation property.

Invalid values are rounded to the nearest valid value.

flashMode string A string that defines how the flash, if any, is to be used; this is auto by default if the device has a flash, none otherwise. Its value must be chosen from the list of options specified by  {{domxref("CameraCapabilities")}}.flashModes.
focalLength double A number that express the camera's focal length in millimeters.
focusAreas Array

An Array of one or more {{anch("Area")}} objects that define where the camera will perform auto-focusing.

When set, if the array contains more objects than the number defined in {{domxref("CameraCapabilities")}}.maxFocusAreas, extra objects will be ignored.

If set to null, the camera will determine the auto-focus areas by itself.

focusDistanceFar double

These three properties define the distances in meters to where the image subject appears to be in focus.  focusDistanceOptimum is where the subject will appear sharpest; the difference between focusDistanceFar and focusDistanceNear is the image's depth of field.

focusDistanceFar may be Infinity.

focusDistanceNear double
focusDistanceOptimum double
focusMode string A string that defines which kind of focus mode the camera should use (auto or fixed by default). Its value must be chosen from {{domxref("CameraCapabilities")}}.focusModes.
meteringAreas Array

An Array of one or more {{anch("Area")}} objects that define where the camera will perform light metering.

If the array contains more objects than the number defined inside {{domxref("CameraCapabilities")}}.maxMeteringAreas, extra objects will be ignored.

If set to null, the camera will determine the light metering areas by itself.

onShutter callback A function to call on the camera's shutter event, to trigger a shutter sound and/or a visual shutter indicator.
onClosed callback A function to call when a new CameraControl object in the same app takes over the camera.
onRecorderStateChange callback

A function to call when the recorder changes state, either because the recording process encountered an error, or because one of the recording limits (see {{domxref("CameraControl.startRecording()")}}) was reached.

This callback takes one parameter, which is one of the following strings:

  • FileSizeLimitReached
  • VideoLengthLimitReached
  • MediaRecorderFailed
  • MediaServerFailed
  • TrackCompleted
  • TrackFailed
sceneMode string A string that defines which scene mode the camera is to use (auto by default). Its value must be chosen from {{domxref("CameraCapabilities")}}.sceneModes.
whiteBalanceMode string A string that defines which white balance mode the camera is to use (auto by default). Its value must be chosen from {{domxref("CameraCapabilities")}}.whiteBalanceModes.
zoom double A number that defines which kind of zoom factor mode the camera is to use (1 by default). Its value must be chosen from {{domxref("CameraCapabilities")}}.zoomRatios.

Area

Areas objects are used within meteringAreas and focusAreas properties. This kind of object is any object with the following properties:

top
A number range from -1000 at the topmost of the sensor to 1000 at the bottommost of the sensor.
left
A number range from -1000 at the leftmost of the sensor to 1000 at the rightmost of the sensor.
bottom
A number range from -1000 at the topmost of the sensor to 1000 at the bottommost of the sensor.
right
A number range from -1000 at the leftmost of the sensor to 1000 at the rightmost of the sensor.
weight
A number defining the relative importance of the area against other areas.

Note: Objects missing one or more of these properties will be ignored.

Methods

{{ domxref("CameraControl.autoFocus()") }}
Tells the camera to attempt to focus the image.
{{ domxref("CameraControl.getPreviewStream()") }}
Gets a video stream from the camera; you can use this in an arbitrary context.
{{ domxref("CameraControl.getPreviewStreamVideoMode()") }}
Gets a video stream from the camera based on a specific video mode.
{{ domxref("CameraControl.release()") }}
Releases the camera so that other applications can use it.
{{ domxref("CameraControl.resumePreview()") }}
Resumes the preview video stream after it's been paused by a call to {{domxref("CameraControl.takePicture()")}}.
{{ domxref("CameraControl.setExposureCompensation()") }}
Lets you specify the exposure compensation factor.
{{ domxref("CameraControl.startRecording()") }}
Lets you start recording a video stream.
{{ domxref("CameraControl.stopRecording()") }}
Lets you stop recording a video stream.
{{ domxref("CameraControl.takePicture()") }}
Lets you capture a single image, receiving it as a {{domxref("Blob")}}.

Specification

Not part of any specification; however, this API should be removed when the WebRTC Capture and Stream API has been implemented.

See also

  • {{ domxref("CameraManager") }}
  • {{ domxref("CameraCapabilities") }}
  • {{ domxref("window.navigator.mozCameras","navigator.mozCameras") }}

Revision Source

<p>{{ domref() }}</p>
<p>{{ non-standard_header() }}</p>
<p>When you obtain a reference to a camera by calling {{domxref("CameraManager.getCamera()")}}, the object passed as a parameter of the callback function called on success is a <code>CameraControl</code> object. You can use its methods and properties to manage and make use of the camera.</p>
<h2 id="Properties">Properties</h2>
<table class="standard-table">
  <thead>
    <tr>
      <th scope="col">Name</th>
      <th scope="col">Type</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{domxref("CameraControl.capabilities","capabilities")}}</td>
      <td>{{domxref("CameraCapabilities")}}</td>
      <td>An object indicating all the capabilities for the given camera.</td>
    </tr>
    <tr>
      <td><code>effect</code></td>
      <td><code>string</code></td>
      <td>A string defining the effect to be used by the camera (<code>none</code> by default). It's value must be one of the values available in {{domxref("CameraCapabilities")}}<code>.effects</code>.</td>
    </tr>
    <tr>
      <td><code>exposureCompensation</code> {{readonlyinline}}</td>
      <td><code>double</code></td>
      <td>
        <p>A value used to compensate the camera exposure. This attribute is read-only; to change the exposure, you need to call the {{domxref("CameraControl.setExposureCompensation()")}} method.</p>
        <p>Acceptable values for this property must range from the value of the {{domxref("CameraCapabilities")}}<code>.minExposureCompensation</code> property&nbsp; to the value of the {{domxref("CameraCapabilities")}}<code>.maxExposureCompensation</code> property in steps of the {{domxref("CameraCapabilities")}}<code>.stepExposureCompensation</code> property.</p>
        <p>Invalid values are rounded to the nearest valid value.</p>
      </td>
    </tr>
    <tr>
      <td><code>flashMode</code></td>
      <td><code>string</code></td>
      <td>A string that defines how the flash, if any, is to be used; this is <code>auto</code> by default if the device has a flash, <code>none</code> otherwise. Its value must be chosen from the list of options specified by&nbsp; {{domxref("CameraCapabilities")}}<code>.flashModes</code>.</td>
    </tr>
    <tr>
      <td><code>focalLength</code></td>
      <td><code>double</code></td>
      <td>A number that express the camera's focal length in millimeters.</td>
    </tr>
    <tr>
      <td><code>focusAreas</code></td>
      <td><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Array" title="/en-US/docs/JavaScript/Reference/Global_Objects/Array"><code>Array</code></a></td>
      <td>
        <p>An <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Array" title="/en-US/docs/JavaScript/Reference/Global_Objects/Array"><code>Array</code></a> of one or more {{anch("Area")}} objects that define where the camera will perform auto-focusing.</p>
        <p>When set, if the array contains more objects than the number defined in {{domxref("CameraCapabilities")}}<code>.maxFocusAreas</code>, extra objects will be ignored.</p>
        <p>If set to <code>null</code>, the camera will determine the auto-focus areas by itself.</p>
      </td>
    </tr>
    <tr>
      <td><code>focusDistanceFar</code></td>
      <td><code>double</code></td>
      <td colspan="1" rowspan="3">
        <p>These three properties define the distances in meters to where the image subject appears to be in focus.&nbsp; <code>focusDistanceOptimum</code> is where the subject will appear sharpest; the difference between <code>focusDistanceFar</code> and <code>focusDistanceNear</code> is the image's depth of field.</p>
        <p><code>focusDistanceFar</code> may be <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Infinity" title="/en-US/docs/JavaScript/Reference/Global_Objects/Infinity">Infinity</a></code>.</p>
      </td>
    </tr>
    <tr>
      <td><code>focusDistanceNear</code></td>
      <td><code>double</code></td>
    </tr>
    <tr>
      <td><code>focusDistanceOptimum</code></td>
      <td><code>double</code></td>
    </tr>
    <tr>
      <td><code>focusMode</code></td>
      <td><code>string</code></td>
      <td>A string that defines which kind of focus mode the camera should use (<code>auto</code> or <code>fixed</code> by default). Its value must be chosen from {{domxref("CameraCapabilities")}}<code>.focusModes</code>.</td>
    </tr>
    <tr>
      <td><code>meteringAreas</code></td>
      <td><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Array" title="/en-US/docs/JavaScript/Reference/Global_Objects/Array"><code>Array</code></a></td>
      <td>
        <p>An <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Array" title="/en-US/docs/JavaScript/Reference/Global_Objects/Array"><code>Array</code></a> of one or more {{anch("Area")}} objects that define where the camera will perform light metering.<br />
          <br />
          If the array contains more objects than the number defined inside {{domxref("CameraCapabilities")}}<code>.maxMeteringAreas</code>, extra objects will be ignored.</p>
        <p>If set to <code>null</code>, the camera will determine the light metering areas by itself.</p>
      </td>
    </tr>
    <tr>
      <td><code>onShutter</code></td>
      <td><code>callback</code></td>
      <td>A function to call on the camera's shutter event, to trigger a shutter sound and/or a visual shutter indicator.</td>
    </tr>
    <tr>
      <td><code>onClosed</code></td>
      <td><code>callback</code></td>
      <td>A function to call when a new <code>CameraControl</code> object in the same app takes over the camera.</td>
    </tr>
    <tr>
      <td><code>onRecorderStateChange</code></td>
      <td><code>callback</code></td>
      <td>
        <p>A function to call when the recorder changes state, either because the recording process encountered an error, or because one of the recording limits (see {{domxref("CameraControl.startRecording()")}}) was reached.</p>
        <p>This callback takes one parameter, which is one of the following strings:</p>
        <ul>
          <li><code><span class="p">FileSizeLimitReached</span></code></li>
          <li><code><span class="p">VideoLengthLimitReached</span></code></li>
          <li><code><span class="p">MediaRecorderFailed</span></code></li>
          <li><code><span class="p">MediaServerFailed</span></code></li>
          <li><code><span class="p">TrackCompleted</span></code></li>
          <li><code><span class="p">TrackFailed</span></code></li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>sceneMode</code></td>
      <td><code>string</code></td>
      <td>A string that defines which scene mode the camera is to use (<code>auto</code> by default). Its value must be chosen from {{domxref("CameraCapabilities")}}<code>.sceneModes</code>.</td>
    </tr>
    <tr>
      <td><code>whiteBalanceMode</code></td>
      <td><code>string</code></td>
      <td>A string that defines which white balance mode the camera is to use (<code>auto</code> by default). Its value must be chosen from {{domxref("CameraCapabilities")}}<code>.whiteBalanceModes</code>.</td>
    </tr>
    <tr>
      <td><code>zoom</code></td>
      <td><code>double</code></td>
      <td>A number that defines which kind of zoom factor mode the camera is to use (1 by default). Its value must be chosen from {{domxref("CameraCapabilities")}}<code>.zoomRatios</code>.</td>
    </tr>
  </tbody>
</table>
<h3>Area</h3>
<p>Areas objects are used within <code>meteringAreas</code> and <code>focusAreas</code> properties. This kind of object is any object with the following properties:</p>
<dl>
  <dt>
    <code>top</code></dt>
  <dd>
    A number range from -1000 at the topmost of the sensor to 1000 at the bottommost of the sensor.</dd>
  <dt>
    <code>left</code></dt>
  <dd>
    A number range from -1000 at the leftmost of the sensor to 1000 at the rightmost of the sensor.</dd>
  <dt>
    <code>bottom</code></dt>
  <dd>
    A number range from -1000 at the topmost of the sensor to 1000 at the bottommost of the sensor.</dd>
  <dt>
    <code>right</code></dt>
  <dd>
    A number range from -1000 at the leftmost of the sensor to 1000 at the rightmost of the sensor.</dd>
  <dt>
    <code>weight</code></dt>
  <dd>
    A number defining the relative importance of the area against other areas.</dd>
</dl>
<div class="note">
  <p><strong>Note:</strong> Objects missing one or more of these properties will be ignored.</p>
</div>
<h2 id="Methods">Methods</h2>
<dl>
  <dt>
    {{ domxref("CameraControl.autoFocus()") }}</dt>
  <dd>
    Tells the camera to attempt to focus the image.</dd>
  <dt>
    {{ domxref("CameraControl.getPreviewStream()") }}</dt>
  <dd>
    Gets a video stream from the camera; you can use this in an arbitrary context.</dd>
  <dt>
    {{ domxref("CameraControl.getPreviewStreamVideoMode()") }}</dt>
  <dd>
    Gets a video stream from the camera based on a specific video mode.</dd>
  <dt>
    {{ domxref("CameraControl.release()") }}</dt>
  <dd>
    Releases the camera so that other applications can use it.</dd>
  <dt>
    {{ domxref("CameraControl.resumePreview()") }}</dt>
  <dd>
    Resumes the preview video stream after it's been paused by a call to {{domxref("CameraControl.takePicture()")}}.</dd>
  <dt>
    {{ domxref("CameraControl.setExposureCompensation()") }}</dt>
  <dd>
    Lets you specify the exposure compensation factor.</dd>
  <dt>
    {{ domxref("CameraControl.startRecording()") }}</dt>
  <dd>
    Lets you start recording a video stream.</dd>
  <dt>
    {{ domxref("CameraControl.stopRecording()") }}</dt>
  <dd>
    Lets you stop recording a video stream.</dd>
  <dt>
    {{ domxref("CameraControl.takePicture()") }}</dt>
  <dd>
    Lets you capture a single image, receiving it as a {{domxref("Blob")}}.</dd>
</dl>
<h3 id="Specification" name="Specification">Specification</h3>
<p>Not part of any specification; however, this API should be removed when the <a class="external" href="http://dev.w3.org/2011/webrtc/editor/getusermedia.html" rel="external" title="http://dev.w3.org/2011/webrtc/editor/getusermedia.html">WebRTC Capture and Stream API</a> has been implemented.</p>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{ domxref("CameraManager") }}</li>
  <li>{{ domxref("CameraCapabilities") }}</li>
  <li>{{ domxref("window.navigator.mozCameras","navigator.mozCameras") }}</li>
</ul>
Revert to this revision