CWAC-Cam2: Taking Pictures. Made (Somewhat) Sensible. Again.

Taking pictures using a third-party app is fairly straightforward, using ACTION_IMAGE_CAPTURE and ACTION_VIDEO_CAPTURE. However, different camera apps have slightly different behavior, meaning that you are prone to getting inconsistent results.

Taking pictures using the Android SDK camera classes directly is eminently possible, but is full of edge and corner cases, not to mention its own set of per-device idiosyncracies. Plus, there are now two separate APIs for this, three if you count MediaRecorder for video recording.

CWAC-Cam2 is an effort to create an in-app ACTION_IMAGE_CAPTURE/ACTION_VIDEO_CAPTURE workalike, with a bit more configurability. You still integrate by opening up a separate activity (CameraActivity and VideoRecorderActivity, in this case), but it is all within your own app, rather than relying upon device- or user-specific third-party camera apps.

Library Objectives

The #1 objective of this library is maximum compatibility with hardware. As such, this library will not be suitable for all use cases.

The targeted use case is an app that might otherwise have relied upon ACTION_IMAGE_CAPTURE/ACTION_VIDEO_CAPTURE, but needs greater reliability and somewhat greater control.

If you are trying to write "a camera app" — an app whose primary job is to take pictures — this library may be unsuitable for you.

Installation

To integrate the core AAR, the Gradle recipe is:

repositories {
    maven {
        url "https://s3.amazonaws.com/repo.commonsware.com"
    }
}

dependencies {
    compile 'com.commonsware.cwac:cam2:0.6.0'
}

The cam2 artifact depends on some other libraries, available in JCenter or Maven Central. They should be pulled down automatically when you integrate in the cam2 AAR.

You are also welcome to clone this repo and use the cam2/ Android library project2 in source form.

Basic Usage

The only supported API at the moment is through CameraActivity and its IntentBuilder for still pictures and VideoRecorderActivity and its IntentBuilder for videos. You will also want to review the documentation regarding permissions, as while the library will work "out of the box", most likely you will want to do some permission setup in your app for Android 6.0+ devices.

While there are other public classes and methods in the library, ones that may be exposed as part of a public API in the future, they are not supported at the present time.

NOTE: Ensure that you do not block hardware acceleration for the library-provided activities. In other words, do not have android:hardwareAccelerated="false" for your whole <application> in the manifest.

Upgrade Notes

If you are moving from 0.5.x to 0.6.0 or higher, please note that the default camera engine is now the one using android.hardware.Camera. The forceClassic() method is deprecated, replaced with forceEngine(), which takes a CameraEngine.ID enum value (either CLASSIC or CAMERA2).

Also, if you are moving from 0.5.x to 0.6.0 or higher, please note that your photos will be rotated, if the EXIF headers say that they should be rotated, and if there is sufficient memory to rotate the photos. Call skipOrientationNormalization() to avoid this.

If you are moving from 0.3.x or 0.4.x to 0.5.0 or higher, please note that FocusMode is no longer an inner enum of AbstractCameraActivity, but rather is a standalone Java file. You will need to switch your import statement to com.commonsware.cwac.cam2.FocusMode.

Tested Devices

The compatibility status page outlines what devices have been tested with this library by the library author.

Dependencies

The cam2 artifact depends upon com.github.clans:fab (for a floating action button and floating action menu implementation) and de.greenrobot:eventbus (for internal communications within the library). Both are listed as dependencies in the AAR artifact metadata and should be added to your project automatically.

ProGuard

It is recommended that you not obfuscate the classes in CWAC libraries:

-keep class com.commonsware.cwac.** { *; }

If you feel that obfuscating open source code makes sense, at minimum you will need to employ appropriate rules to prevent greenrobot's EventBus code, and this library's use of it, from being obfuscated.

Version

This is version v0.6.0 of this library, which means it is coming along slowly.

Demo

There are two demo projects.

One is demo/. This illustrates taking pictures or recording videos using the front and rear-facing cameras. More importantly, it serves as a way of collecting information about a device, particularly if you are going to file a bug report.

The demo-playground/ sample project displays a PreferenceFragment where you can tweak various IntentBuilder configurations, then tap on an action bar item to take a picture using those settings. This is good for experimenting with the CameraActivity and VideoRecorderActivity capabilities.

Additional Documentation

The Busy Coder's Guide to Android Development contains three chapters related to this library. One is a tutorial for implementing Android 6.0 runtime permissions that happens to use this library. Another is a chapter on various ways to take pictures that includes coverage of this library. A third chapter explores the camera APIs in Android and references implementation details from this library.

License

The code in this project is licensed under the Apache Software License 2.0, per the terms of the included LICENSE file.

Questions

If you have questions regarding the use of this code, please post a question on StackOverflow tagged with commonsware-cwac and android after searching to see if there already is an answer. Be sure to indicate what CWAC module you are having issues with, and be sure to include source code and stack traces if you are encountering crashes.

If you have encountered what is clearly a bug, or if you have a feature request, please read the contribution guidelines, then post an issue. Be certain to include complete steps for reproducing the issue.

Do not ask for help via social media.

Release Notes

• v0.6.0: EXIF orientation normalization, whitelist for camera2 usage, more focus modes, and torch flash mode
• v0.5.11: LG V10 H901 bug fix
• v0.5.10: LG G4, activity re-creation bugs fixed, plus more graceful failure for a camera2 issue
• v0.5.9: handle config changes/process termination better
• v0.5.8: better OOM handling, added ResultReceiver support for getting details of errors, bug fix in confirmationQuality
• v0.5.7: improved OnePlus X compatibility, allow configurable confirmation quality, block camera-change FAB in exact-match scenario
• v0.5.6: added quality control to still photos, added video recording to demo/
• v0.5.5: fixed LG G3 video bug and disable camera changes during video recording
• v0.5.4: fixed two video recording bugs
• v0.5.3: reverts inadequate shutdown change from v0.5.2 due to bugs
• v0.5.2: fixed zoom, inadequate shutdown, and dual engines issues
• v0.5.1: fixed critical bug in video recording
• v0.5.0: added zoom support, better display orientation support
• v0.4.4: added Nexus 5X, Galaxy S4 Zoom to alt orientation whitelist
• v0.4.3: too-large camera preview issue fix
• v0.4.2: Camera2 API timing issue fix
• v0.4.1: Nexus 6P bug fix, support for choosing built-in activities or third-party camera apps
• v0.4.0: flash mode support, better preview sizing, bug fixes
• v0.3.4: more bug fixes, added debug preview frame support
• v0.3.3: yet more bug fixes
• v0.3.2: bug fixes
• v0.3.1: fixed bugs related to Nexus 7 (2012), SONY Xperia Z, and two Samsung models
• v0.3.0: added focus modes, exact camera match option, preview mirror option, and demo app improvements
• v0.2.3: reverted part of action bar divider line fix
• v0.2.2: FAB and divider line fixes, minor demo project improvements
• v0.2.1: added Android 6.0 runtime permission support, added missing element
• v0.2.0: added initial support for video recording, fixed aspect ratio and other bugs
• v0.1.1: added forceClassic() and updateMediaStore(), fixed numerous issues
• v0.1.0: initial release

Who Made This?