v1 Migration Guide Breaking Changes & new concepts
CameraView v2 introduces various breaking changes that will allow for more flexibility in the future, removes useless features and makes method names consistent. Upgrading will require addressing these in your app, plus understanding new concepts.
Until the final v2 release, these things might change, but likely they will not.
The lib was moved to AndroidX classes. Hopefully this should not have any impact on you.
Open, not start
start() method has been renamed to
open(), and the
stop() method to
close(). This was
done for consistency with the
setJpegQuality() have been removed. They were working only with specific
setups and made no real sense. We will use the default quality provided by the camera engine.
setCropOutput() have been removed. This was an expensive operation that
worked with pictures only. In v2, if you want your output to be cropped to match the view bounds, you
will use the
*snapshot() APIs (see below).
This was an opaque option packaging various parameters. It has been removed. You are expected to control the video quality by choosing the video size and setting video parameters with new APIs (see below).
BitmapCallbackhas been moved into a separate class.
BitmapCallbackresult is now
@Nullable! This will happen if we encounter an
OutOfMemoryErrorduring decoding. You should consider passing a maxWidth and maxHeight instead of loading the full image.
- Methods returning a
Setnow return a
isVideoSnapshotSupported()was removed, as we do not rely on internal video snapshot feature anymore. See below.
- In addition to
getSupportedPictureAspectRatio, we now have equivalent methods for video. See below.
SessionType has been renamed to
Mode which has a clearer meaning.
getPictureSize(): now returns the real output picture size. This means that it accounts for rotation. It will also return
VIDEOmode: use getVideoSize in that case.
getVideoSize(): added. Returns the real output video size. This means that it accounts for rotation. It will return
getSnapshotSize(): This is the size of pictures taken with
takePictureSnapshot()and videos taken with
takeVideoSnapshot(). It accounts for rotation and cropping. Read about snapshots below.
As you might have guessed, video size is now configurable, with the addition of
It works exactly like the picture one, so please refer to the size selector documentation. Defaults to
The engine will use the video size selector when mode is
VIDEO, and the picture size selector when mode is
Picture and videos
Take, not capture
takeVideo(). Signature changed from long to int
isTakingPicture() method was added for symmetry with videos.
This is the major improvement over v1. There are now 4 capture APIs, two for pictures and two for videos.
- Standard APIs:
takeVideo(). These take a high quality picture or video, depending on the
SizeSelectorand parameters that were used. The standard APIs must be called in the appropriate
Mode(pictures must be taken in
PICTUREmode, videos must be taken in
- Snapshot APIs:
takeVideoSnapshot(). These take a super fast, reliable snapshot of the camera preview. The snapshot APIs can be called in any
Mode(you can snap videos in picture mode).
The good news is that snapshot APIs will automatically crop the result, for both video and pictures, which means that square videos or any other ratio are possible.
||Auto crop||Output size|
||That of the view|
||That of the view|
The video snapshot supports audio and respects the
Audio, max duration, max size & codec settings,
which makes it a powerful tool. The drawback is that it needs:
- API 18. If called before, it throws
- An OpenGL preview (see below). If not, it throws
Some new APIs were introduced, which are respected by both standard videos and snapshot videos:
cameraAudioBitRate: sets the audio bit rate in bit/s
cameraVideoBitRate: sets the video bit rate in bit/s
Important: takeVideo(), like takeVideoSnapshot(), will not accept a null file as input. Use new File(context.getFilesDir(), “video.mp4”) to use the old default.
The type of preview is now configurable with
cameraPreview XML attribute and
Preview control class.
This defaults to the new
GL_SURFACE and it is highly recommended that you do not change this.
||This might be better for battery, but will not work well (AFAIR) with dynamic layout changes and similar things. No support for video snapshots.|
||Better. Requires hardware acceleration. No support for video snapshots.|
||Supports video snapshots. Might support GL real time filters in the future.|
The GL surface, as an extra benefit, has a much more efficient way of capturing picture snapshots, that avoids OOM errors, rotating the image on the fly, reading EXIF, and other horrible things belonging to v1. These picture snapshots will also work while taking videos.
Advanced feature: Preview Sizing
We finally introduced a
setPreviewSize() method which accepts a
SizeSelector. The use of this method
is discouraged if you don’t know exactly what you are doing. The default preview size selector is already
smart enough to
- respect the picture/video aspect ratio
- be a bit bigger than the view so that there is no upscaling
There are not so many reason why you would use this method, other than, for example, control the frame
processor size or, indirectly, the snapshots size. If what you are doing is just assigning an aspect ratio,
for instance, please do so using
getPreviewSize() was removed as it has no useful meaning.
The listener interface brings two breaking signature changes:
onPictureTaken()now returns a
result.getJpeg()to access the jpeg stream. The result class includes rich information about the picture (or picture snapshot) that was taken, plus handy utilities (
onVideoTaken()now returns a
result.getFile()to access the video file. The result class includes rich information about the video (or video snapshot) that was taken.
The v2 version introduces a
cameraExperimental XML flag that you can use to enable experimental features.
Might be used in the future to speed up development.
Other improvements & changes
@NonNullannotations pretty much everywhere. This might break your Kotlin build.
cameraGridColorto control the grid color
Facingvalue is not
BACKanymore but rather a value that guarantees that you have cameras (if possible). If device has no
BACKcameras, defaults to
ExtraPropertiesas it was useless.
TODO: improve the focus marker drawing, move out of XML (accept a drawable?)