You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
262 lines
7.8 KiB
262 lines
7.8 KiB
---
|
|
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. |