CameraView/docs/_posts/2018-12-20-controls.md

---
layout: page
title: "Controls"
subtitle: "Output parameters and capture options"
description: "Output parameters and capture options"
category: docs
order: 2
date: 2018-12-20 21:08:53
disqus: 1
---

CameraView supports a wide range of controls that will control the behavior of the sensor or the
quality of the output.

Everything can be controlled through XML parameters or programmatically. For convenience, most options
are represented by `enum` classes extending the `Control` class. This makes it possible to use 
`CameraView.set(Control)` to set the given control, `CameraView.get(Class<Control>)` to get it,
or `CameraOptions.supports(Control)` to see if it is supported.

### XML Attributes

```xml
<com.otaliastudios.cameraview.CameraView
    app:cameraFacing="front|back"
    app:cameraFlash="off|on|auto|torch"
    app:cameraWhiteBalance="auto|incandescent|fluorescent|daylight|cloudy"
    app:cameraHdr="off|on"
    app:cameraAudio="on|off|mono|stereo"
    app:cameraAudioBitRate="0"
    app:cameraVideoCodec="deviceDefault|h263|h264"
    app:cameraVideoMaxSize="0"
    app:cameraVideoMaxDuration="0"
    app:cameraVideoBitRate="0"/>
```

### APIs

##### cameraFacing

Which camera to use, either back facing or front facing.
Defaults to the first available value (tries `BACK` first).

```java
cameraView.setFacing(Facing.BACK);
cameraView.setFacing(Facing.FRONT);
```

##### cameraFlash

Flash mode, either off, on, auto or torch. Defaults to `OFF`.

```java
cameraView.setFlash(Flash.OFF);
cameraView.setFlash(Flash.ON);
cameraView.setFlash(Flash.AUTO);
cameraView.setFlash(Flash.TORCH);
```

##### cameraVideoCodec

Sets the encoder for video recordings. Defaults to `DEVICE_DEFAULT`,
which should typically be H_264.

```java
cameraView.setVideoCodec(VideoCodec.DEVICE_DEFAULT);
cameraView.setVideoCodec(VideoCodec.H_263);
cameraView.setVideoCodec(VideoCodec.H_264);
```

##### cameraWhiteBalance

Sets the desired white balance for the current session.
Defaults to `AUTO`.

```java
cameraView.setWhiteBalance(WhiteBalance.AUTO);
cameraView.setWhiteBalance(WhiteBalance.INCANDESCENT);
cameraView.setWhiteBalance(WhiteBalance.FLUORESCENT);
cameraView.setWhiteBalance(WhiteBalance.DAYLIGHT);
cameraView.setWhiteBalance(WhiteBalance.CLOUDY);
```

##### cameraHdr

Turns on or off HDR captures. Defaults to `OFF`.

```java
cameraView.setHdr(Hdr.OFF);
cameraView.setHdr(Hdr.ON);
```

##### cameraAudio

Turns on or off audio stream while recording videos.
Defaults to `ON`.

```java
cameraView.setAudio(Audio.OFF);
cameraView.setAudio(Audio.ON); // on but depends on video config
cameraView.setAudio(Audio.MONO); // force mono
cameraView.setAudio(Audio.STEREO); // force stereo
```

##### cameraAudioBitRate

Controls the audio bit rate in bits per second.
Use 0 or a negative value to fallback to the encoder default. Defaults to 0.

```java
cameraView.setAudioBitRate(0);
cameraView.setAudioBitRate(64000);
```

##### cameraVideoMaxSize

Defines the maximum size in bytes for recorded video files.
Once this size is reached, the recording will automatically stop.
Defaults to unlimited size. Use 0 or negatives to disable.

```java
cameraView.setVideoMaxSize(100000);
cameraView.setVideoMaxSize(0); // Disable
```

##### cameraVideoMaxDuration

Defines the maximum duration in milliseconds for video recordings.
Once this duration is reached, the recording will automatically stop.
Defaults to unlimited duration. Use 0 or negatives to disable.

```java
cameraView.setVideoMaxDuration(100000);
cameraView.setVideoMaxDuration(0); // Disable
```

##### cameraVideoBitRate

Controls the video bit rate in bits per second.
Use 0 or a negative value to fallback to the encoder default. Defaults to 0.

```java
cameraView.setVideoBitRate(0);
cameraView.setVideoBitRate(4000000);
```

### Auto Focus

There are many ways to focus a CameraView engine:

- Continuous autofocus is activated by default, where present
- User can start focus with a [Gesture](gestures.html)
- The developer can start focus with the `startAutoFocus(float, float)` API. This action needs
  the coordinates of a point to focus, with respect to the view width and height.

The last two actions will trigger the focus callbacks:

```java
cameraView.addCameraListener(new CameraListener() {
    
    @Override
    public void onAutoFocusStart(@NonNull PointF point) {
        // Auto focus was started by a gesture or by startAutoFocus(float, float).
        // The camera is currently trying to focus around that area.
        // This can be used to draw things on screen.
    }

    @Override
    public void onAutoFocusEnd(boolean successful, @NonNull PointF point) {
        // Auto focus operation just ended. If successful, the camera will have converged
        // to a new focus point, and possibly changed exposure and white balance as well.
        // The point is the same that was passed to onAutoFocusStart.
    }
});
```

Auto focus is not guaranteed to be supported: check the `CameraOptions` to be sure.

```xml
<com.otaliastudios.cameraview.CameraView
    app:cameraAutoFocusMarker="@string/cameraview_default_autofocus_marker"
    app:cameraAutoFocusResetDelay="3000"/>
```

##### cameraAutoFocusMarker

Lets you set a marker for drawing on screen in response to auto focus events.
In XML, you should pass the qualified class name of your marker.

```java
cameraView.setAutoFocusMarker(null);
cameraView.setAutoFocusMarker(marker);
```

We offer a default marker (similar to the old `focusWithMarker` attribute in v1),
which you can set in XML using the `@string/cameraview_default_autofocus_marker` resource,
or programmatically:

```java
cameraView.setAutoFocusMarker(new DefaultAutoFocusMarker());
```

##### cameraAutoFocusResetDelay

Lets you control how an auto-focus operation is reset after completed.
Setting a value <= 0 or == Long.MAX_VALUE will not reset the auto-focus.
This is useful for low end devices that have slow auto-focus capabilities.
Defaults to 3 seconds.

```java
cameraView.setCameraAutoFocusResetDelay(1000);  // 1 second
cameraView.setCameraAutoFocusResetDelay(0);  // NO reset
cameraView.setCameraAutoFocusResetDelay(-1);  // NO reset
cameraView.setCameraAutoFocusResetDelay(Long.MAX_VALUE);  // NO reset
```

### Zoom

There are two ways to control the zoom value:

- User can zoom in or out with a [Gesture](gestures.html)
- The developer can start manual zoom with the `setZoom(float)` API, passing in a value between 0 and 1.

Both actions will trigger the zoom callback, which can be used, for example, to draw a seek bar:

```java
cameraView.addCameraListener(new CameraListener() {
    
    @Override
    public void onZoomChanged(float newValue, @NonNull float[] bounds, @Nullable PointF[] fingers) {
        // newValue: the new zoom value
        // bounds: this is always [0, 1]
        // fingers: if caused by touch gestures, these is the fingers position
    }
});
```

Zoom is not guaranteed to be supported: check the `CameraOptions` to be sure.

### Exposure correction

There are two ways to control the exposure correction value:

- User can change the exposure correction with a [Gesture](gestures.html)
- The developer can change this value with the `setExposureCorrection(float)` API, passing in the EV
  value, in camera stops. This value should be contained in the minimum and maximum supported values,
  as returned by `CameraOptions`.

Both actions will trigger the exposure correction callback, which can be used, for example, to draw a seek bar:

```java
cameraView.addCameraListener(new CameraListener() {
    
    @UiThread
    public void onExposureCorrectionChanged(float newValue, @NonNull float[] bounds, @Nullable PointF[] fingers) {
        // newValue: the new correction value
        // bounds: min and max bounds for newValue, as returned by {@link CameraOptions}
        // fingers: finger positions that caused the event, null if not caused by touch
    }
});
```

EV correction is not guaranteed to be supported: check the `CameraOptions` to be sure.