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.
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.
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.2'
}
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.
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.
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
.
The compatibility status page outlines what devices have been tested with this library by the library author.
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.
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.
This is version v0.6.2 of this library, which means it is coming along slowly.
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.
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.
The code in this project is licensed under the Apache Software License 2.0, per the terms of the included LICENSE file.
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.
- v0.6.2: fixed Nexus 6P and Honor 5X bugs
- v0.6.1: Chronometer support and config change bug fix
- 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 inconfirmationQuality
- 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()
andupdateMediaStore()
, fixed numerous issues - v0.1.0: initial release