1 2# Jetpack Camera App �� 3 4Jetpack Camera App (JCA) is a camera app, focused on features used by app developers, and built 5entirely with CameraX, Kotlin and Jetpack Compose. It follows Android 6design and development best practices and it's intended to be a useful reference for developers and 7OEMs looking to validate their camera feature implementations. 8 9# Development Environment ⚒️ 10 11This project uses the gradle build system, and can be imported directly into Android Studio. 12 13Currently, Jetpack Camera App is built using the Android Gradle Plugin 8.4, which is only compatible 14with Android Studio Jellyfish or newer. 15 16# Architecture �� 17 18JCA is built with [modern android development (MAD)](https://developer.android.com/modern-android-development) principles in mind, 19including [architecture and testing best practices](https://developer.android.com/topic/architecture). 20 21The app is split into multiple modules, with a clear separation between the UI and data layers. 22 23# Testing �� 24 25Thorough testing is a key directive of JCA. We use [Compose Test](https://developer.android.com/develop/ui/compose/testing) and 26[UI Automator](https://developer.android.com/training/testing/other-components/ui-automator) to write instrumentation 27tests that run on-device. 28 29These tests can be run on a connected device via Android Studio, or can be tested on an Android 30Emulator using built-in Gradle Managed Device tasks. Currently, we include Pixel 2 (API 28) and 31Pixel 8 (API 34) emulators which can be used to run instrumentation tests with: 32 33`$ ./gradlew pixel2Api28StableDebugAndroidTest` and 34`$ ./gradlew pixel8Api34StableDebugAndroidTest` 35 36# Features ✨��✨ 37 38This section provides a detailed overview of the camera app's features, highlighting its 39capabilities and functionalities. Each feature is described with its purpose, usage, and any 40relevant considerations to help you understand and utilize the app effectively. 41 42- [Standard Camera Features](#standard-camera-features) 43 * [Viewfinder](#viewfinder) 44 * [Aspect Ratio](#aspect-ratio) 45 * [Image Capture](#image-capture) 46 * [Tap to Focus](#tap-to-focus) 47 * [Flip Camera](#flip-camera) 48 * [Zoom](#zoom) 49 * [Scene Illumination / Flash](#scene-illumination---flash) 50- [Video Features](#video-features) 51 * [Video Capture](#video-capture) 52 * [Pause / Resume](#pause---resume) 53 * [Video Duration Limit](#video-duration-limit) 54 * [Video Quality](#video-quality) 55 * [Audio / Amplitude Visualization](#audio---amplitude-visualization) 56 * [Frame Rate](#frame-rate) 57 * [Video Stabilization](#video-stabilization) 58 * [Flip Camera While Recording](#flip-camera-while-recording) 59- [Advanced Camera Features](#advanced-camera-features) 60 * [Screen Flash](#screen-flash) 61 * [Dual Concurrent Camera](#dual-concurrent-camera) 62 * [HDR (High Dynamic Range)](#hdr--high-dynamic-range-) 63 * [LLB (Low Light Boost)](#llb--low-light-boost-) 64 * [Single / Multi-stream Mode](#single---multi-stream-mode) 65- [Special Application Features](#special-application-features) 66 * [Debug Mode](#debug-mode) 67 * [Intent Capture Modes](#intent-capture-modes) 68 * [Dark Mode](#dark-mode) 69 70## Standard Camera Features 71 72This section outlines the essential features of the camera app that enable you to capture photos and 73videos with ease. It covers fundamental aspects of camera operation, providing a solid starting 74point for utilizing the app's capabilities. 75 76### Viewfinder 77 78The viewfinder provides a real-time preview of the camera's sensor output, accurately displaying the 79scene with correct scaling and orientation. It functions as a "What You See Is What You Get" ( 80WYSIWYG) display, showing only the pixels that will be captured in the final image or video, when 81hardware and processing capabilities allow (see limitations). This ensures that the displayed 82preview precisely reflects the captured content, allowing for accurate composition and framing. 83 84#### How to Enable / Use 85 86* This is a core function of the camera app. When the camera app is opened, the viewfinder is 87 active. 88 89#### Constraints / Limitations 90 91* The viewfinder's quality is limited by the screen's resolution and brightness. JCA is built on 92 CameraX, which will limit the viewfinder resolution to 1080p as a tradeoff of performance and 93 quality. 94* Due to the computational demands of high-quality video stabilization, the viewfinder may not be 95 strictly WYSIWYG when the video stabilization mode is set to “High Quality”, as the stabilization 96 algorithm applied to the recorded video stream might not be able to be replicated in real-time for 97 the viewfinder preview. 98 99--- 100 101### Aspect Ratio 102 103Sets the proportions of the preview and the captured image or video. 104 105#### How to Enable / Use 106 1071. Open the camera app settings and select Set Aspect Ratio 1082. Or open the quick dropdown in the preview screen and look for the aspect ratio icon 1093. Select/toggle among the desired aspect ratios (e.g., 16:9, 4:3, 1:1). 110 111--- 112 113### Image Capture 114 115Captures a still image from the camera. When the capture button is pressed, the camera captures a 116still image that accurately represents the scene currently displayed in the viewfinder. The captured 117image will incorporate any applicable image processing settings, such as Ultra HDR, based on the 118user's selected mode. 119 120#### How to Enable / Use 121 1221. Open the camera app. 1232. Tap the shutter button (white circle). 1243. The resulting image is saved to the device's media store, or, when the app is launched via the 125 `ACTION_IMAGE_CAPTURE` or `INTENT_ACTION_STILL_IMAGE_CAMERA` intents, to the URI(s) provided. 126 127#### Constraints / Limitations 128 129* The ability to capture an image may be limited by available device storage. 130* Image capture is disabled when the app is launched with the `ACTION_VIDEO_CAPTURE` intent. 131* Image capture is also disabled in concurrent camera mode and when HDR is enabled and the device 132 does not support Ultra HDR image capture. 133 134--- 135 136### Tap to Focus 137 138Allows the user to manually select the focus point of the camera. 139 140#### How to Enable / Use 141 1421. Open the camera app. 1432. Tap on the desired area of the viewfinder. 1443. The camera will adjust the focus to the tapped area. 145 146#### Constraints / Limitations 147 148* May struggle in low-light conditions. 149* Can be affected by movement of the subject or camera. 150* Some devices may have limitations on how close or far the focus can be adjusted. 151 152--- 153 154### Flip Camera 155 156This feature allows users to instantly switch between the device's primary front-facing and 157rear-facing cameras. 158 159#### How to Enable / Use 160 161There are several ways to flip camera lenses: 162 1631. Open the camera app. 1642. Tap the flip camera button. 165 166Alternatively, 167 1681. Open the camera app. 1692. Double tap on the viewfinder. 170 171Alternatively, 172 1731. Open the camera app. 1742. Open quick settings by tapping the downward facing arrow at the top of the screen. 1753. Tap the flip camera button which is displaying the currently visible camera. 176 177#### Constraints / Limitations 178 179* If the device does not have a front or a rear camera, the flip camera button will be disabled. 180 181--- 182 183### Zoom 184 185This feature enables users to digitally or optically zoom in and out on the scene. On devices 186equipped with Camera2's `LOGICAL_MULTI_CAMERA` capability, the zoom functionality may automatically 187transition between available lenses, such as the main, telephoto, and wide-angle lenses, to provide 188seamless zoom transitions across the device's optical range. 189 190#### How to Enable / Use 191 1921. Open the camera app. 1932. Use pinch-to-zoom gestures. Text indicating the current magnification factor will appear above 194 the capture button. If the device supports the `LOGICAL_MULTI_CAMERA` capability, switching 195 between lenses will occur automatically as zoom increases or decreases. 196 197#### Constraints / Limitations 198 199* Digital zoom may reduce image quality. 200* In Dual Concurrent Camera mode, only the primary lens’ zoom can be changed. The secondary lens 201 will not react to pinch-to-zoom gestures. 202 203--- 204 205### Scene Illumination / Flash 206 207This feature provides various options for illuminating the scene during capture of images and video, 208including: 209 210* **On:** Activates the device's built-in flash for a burst of light during image capture, and 211 constant illumination during video capture. 212* **Auto:** Automatically determines the need for illumination based on ambient light conditions for 213 image capture. 214* **Low-Light Boost:** Utilizes Camera2's `ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY` auto-exposure ( 215 AE) mode to enhance brightness in low-light conditions, if the device supports it. 216* **Off:** Disables all scene illumination. 217 218#### How to Enable / Use 219 2201. Open the camera app. 2212. Tap the flash icon to toggle between scene illumination modes (on, off, auto, LLB). 2223. Take a photo or video. 223 224Alternatively, 225 2261. Open the camera app. 2272. Open quick settings by tapping the downward facing arrow at the top of the screen. 2283. Tap the flash icon to toggle between scene illumination modes. 2294. Take a photo or video. 230 231#### Constraints / Limitations 232 233* Auto mode relies solely on ambient scene lighting for image capture and behaves as "On" for video 234 capture. 235* Dedicated front-facing flash units, if present, are not utilized; front-facing cameras exclusively 236 use screen flash for illumination. 237* Low-light boost may not be applied to image capture when the app is in multi-stream mode. To 238 guarantee low-light boost application in both image and video capture, utilize single-stream mode. 239 240## Video Features 241 242This section explores the camera app's comprehensive video recording capabilities, providing tools 243and settings to enhance your video capture experience. It covers various aspects of video 244functionality, from basic recording to advanced controls and customization. 245 246### Video Capture 247 248Records video that, in most cases (see limitations), represents the scene visible in the viewfinder. 249When HDR mode is enabled, the captured video can record 10-bit HDR content. 250 251#### How to Enable / Use 252 2531. Open the camera app. 2542. Press and hold the shutter button (white circle) until video recording starts, indicated by a 255 filled red circle in the shutter button and an incrementing duration timer above the shutter 256 button. 2573. Release the shutter button to finish recording. The resulting video is saved to the device's 258 media store, or, when the app is launched via the `ACTION_VIDEO_CAPTURE` intent, to the URI 259 provided. 260 261#### Constraints / Limitations 262 263* May be limited by device storage. 264* Due to the computational demands of high-quality video stabilization, the viewfinder may not be 265 strictly WYSIWYG when the video stabilization mode is set to “High Quality”. The stabilization 266 algorithm applied to the recorded video stream might not be able to be replicated in real-time for 267 the viewfinder preview. 268* Video capture is disabled when the app is launched with the `ACTION_IMAGE_CAPTURE` or 269 `INTENT_ACTION_STILL_IMAGE_CAMERA` intents. 270* Video capture is also disabled when HDR is enabled and the device does not support 10-bit HDR 271 video capture. 272 273--- 274 275### Pause / Resume 276 277Temporarily stops and restarts video recording. 278 279#### How to Enable / Use 280 2811. While recording video, tap the pause button. 2822. Tap the resume button to continue recording. 283 284#### Constraints / Limitations 285 286* May not be available on all devices or in all recording modes. 287 288--- 289 290### Video Duration Limit 291 292Sets a maximum length for video recordings. 293 294#### How to Enable / Use 295 2961. Open the camera app settings. 2972. Select Set Maximum Video Duration 2983. Choose the desired duration limit. 299 300--- 301 302### Video Quality 303 304Sets the resolution and compression level of video recordings. 305 306#### How to Enable / Use 307 3081. Open the camera app settings. 3092. Select Set Video Quality. 3103. Choose the desired video quality (e.g., 720p, 1080p, 4K). 311 312#### Constraints / Limitations 313 314* Available quality settings depend on camera hardware. 315* Ultra High Definition may only be available under video/image-only mode 316 317--- 318 319### Audio / Amplitude Visualization 320 321Controls the audio recording level and processing. 322 323#### How to Enable / Use 324 3251. Start video recording by holding down the capture button 3262. Audio visualization appears to the right of the button while recording 327 328--- 329 330### Frame Rate 331 332Sets the number of frames recorded per second in a video. 333 334#### How to Enable / Use 335 3361. Open the camera app settings. 3372. Select Set Frame Rate 3383. Select the desired frame rate (e.g., 30fps, 60fps). 339 340#### Constraints / Limitations 341 342* Available frame rates depend on camera hardware. 343 344--- 345 346### Video Stabilization 347 348This feature offers multiple stabilization modes to enhance video smoothness and clarity. The 349following stabilization modes are offered as options by JCA 350 351* **Auto:** Automatically enables stabilization based on the device's capabilities and current 352 recording settings. 353* **On:** Activates stabilization for both the preview and recorded video streams, providing a 354 smooth viewing experience during capture and playback. 355* **High Quality:** Applies a high-quality stabilization algorithm to the recorded video stream, 356 potentially resulting in superior stabilization. However, the preview stream may not be stabilized 357 in real-time due to computational limitations. 358* **Optical:** Utilizes the device's optical image stabilization (OIS) hardware to stabilize all 359 streams. 360* **Off:** Disables all stabilization features. 361 362#### How to Enable / Use 363 3641. Open the camera app settings from the settings icon in the upper left corner. 3652. Click the “Set Video Stabilization” setting if it is selectable. If it is not selectable, the 366 current lens does not support any video stabilization. 3673. Choose the desired stabilization mode and press “close”. The stabilization mode will be applied 368 when returning to the camera viewfinder. This selected stabilization mode will be persisted if 369 the app is closed, and will be applied the next time the app is opened. 370 371#### Constraints / Limitations 372 373* Some stabilization modes, such as “On” and “High Quality”, may crop the video and/or viewfinder 374 slightly. 375* Each lens may support different stabilization modes. Supported stabilization modes will be 376 selectable in settings, and unsupported stabilization modes will not be selectable. Swapping the 377 default lens in settings may change the available stabilization modes. 378* Some stabilization modes may not support every frame rate. To ensure best support for most 379 stabilization modes, select “Auto” frame rate. 380* If a stabilization mode is selected, and the camera switches settings via quick settings or by 381 flipping cameras, the stabilization may be disabled temporarily. This is indicated by a greyed out 382 stabilization icon at the top of the viewfinder screen. When settings and/or lens allow the 383 stabilization mode, it will be re-enabled. 384 385--- 386 387### Flip Camera While Recording 388 389Switches between front and rear cameras during video recording. 390 391#### How to Enable / Use 392 3931. While recording video, tap the flip camera button. 394 395#### Constraints / Limitations 396 397* Uses Persistent Recording API which is experimental, and may not always function as expected 398* May be buggy with pause/resume. This is being addressed. 399* Does not work with concurrent cameras, stabilization, or single stream. 400 401## Advanced Camera Features 402 403This section delves into the advanced capabilities of the camera app, unlocking a new level of 404control and creativity for experienced users. It explores features that extend beyond basic camera 405operation, offering specialized functionalities and enhanced capture modes. 406 407### Screen Flash 408 409During image capture with a front-facing camera, this feature illuminates the subject by displaying 410a solid, bright overlay on the device's screen and maximizing screen brightness. 411 412#### How to Enable / Use 413 4141. Open the camera app. 4152. Ensure a front-facing camera is selected by tapping on the “flip camera” button. 4163. Tap the flash icon to toggle between scene illumination mode. Screen flash will be selected if 417 the “On” or “Auto” flash mode is selected. 4184. Take a photo. 419 420See the “Scene Illumination / Flash” feature for other methods of enabling screen flash. 421 422#### Constraints / Limitations 423 424* Screen flash will only be used for front-facing cameras. 425* Screen flash is currently limited to image capture only. There will be no additional illumination 426 for video capture. 427* In "Auto" mode, screen flash behaves equivalently to the "On" mode, regardless of ambient scene 428 lighting. 429 430--- 431 432### Dual Concurrent Camera 433 434This feature enables simultaneous video capture from both the front and rear-facing cameras. It is 435built upon the CameraX concurrent camera APIs and is only available on devices that support the 436`PackageManager.FEATURE_CAMERA_CONCURRENT` feature. The interface displays two video streams: a " 437primary" stream and a "secondary" stream. The primary stream occupies the majority of the 438viewfinder, providing the main view, while the secondary stream is presented in a picture-in-picture 439format. The "Flip Camera" feature will swap the roles of the primary and secondary camera streams, 440effectively switching which camera provides the main view. 441 442#### How to Enable / Use 443 4441. Open the camera app. 4452. Open quick settings by tapping the downward facing arrow at the top of the screen. 4463. Tap the concurrent camera mode button to select the concurrent camera mode. It will display 447 “DUAL” underneath the button when Dual Concurrent Camera mode is enabled, and “SINGLE” for normal 448 single-camera operation. 4494. Both streams will be visible in the viewfinder. You may optionally record a video of what is 450 visible in the viewfinder. Both streams will be composited in the recorded video. 451 452#### Constraints / Limitations 453 454* Image capture is not supported in dual concurrent camera mode; only video capture is available. 455* Single-stream and multi-stream modes are unavailable; both camera streams are composited into a 456 single output stream. 457* HDR mode is not supported in dual concurrent camera mode. 458* Zoom and tap-to-focus functionality are limited to the primary camera stream. Tapping on the 459 secondary stream will interact with the corresponding area of the primary stream that is occluded 460 by the secondary stream's view. 461* Because two cameras are being used concurrently in Dual Concurrent Camera mode, additional power 462 and thermal load should be expected. 463 464--- 465 466### HDR (High Dynamic Range) 467 468This multifaceted feature enhances the camera's ability to capture and display a wider range of 469colors and brightness levels. It comprises three key components: 470 471* **10-bit HDR Video Capture:** Record videos with enhanced color and dynamic range. This 472 functionality is built upon CameraX's `DynamicRange` APIs, including the associated APIs within 473 the `VideoCapture` class. 10-bit HDR allows for over a billion color possibilities, resulting in 474 smoother gradients and more realistic color reproduction. High Dynamic Range (HDR) captures a 475 wider range of light and dark tones, preserving detail in both highlights and shadows. 476* **Ultra HDR Image Capture:** Capture images with expanded dynamic range by embedding a gain map 477 within the standard JPEG file. This functionality is dependent on 478 `ImageCapture.OUTPUT_FORMAT_JPEG_ULTRA_HDR` being an available output format on the device. This 479 gain map stores supplemental luminance data, enabling compatible displays to render a wider range 480 of brightness levels. On non-HDR displays, the image is rendered as a standard SDR JPEG, ensuring 481 backward compatibility. 482* **HDR Viewfinder Preview:** When 10-bit HDR video mode is activated, the device's display 483 dynamically switches to HDR rendering for real-time preview, provided the current display supports 484 the `ActivityInfo.COLOR_MODE_HDR` color mode. This enables accurate monitoring of captured HDR 485 video content during recording, leveraging the display's extended dynamic range capabilities. 486 487#### How to Enable / Use 488 4891. Open the camera app. 4902. Open quick settings by tapping the downward facing arrow at the top of the screen. 4913. Tap the “HDR” button to select HDR mode, if it is enabled. Tapping again will toggle back to SDR 492 mode. 4934. Exit quick settings by tapping the upward facing arrow at the top of the screen. 4945. Toggle between 10-bit HDR video mode and Ultra HDR image capture mode using the toggle switch in 495 the lower right corner. If only one of these modes is available on the device, this switch will 496 be disabled, and tapping it will display a reason for why it is disabled. 4976. Take a photo or video as normal, depending on which mode is selected. 498 499#### Constraints / Limitations 500 501* Not every device supports HDR mode. Some devices may support only 10-bit HDR video or Ultra HDR, 502 but not both. 503* HDR mode supports either image capture or video capture, but not both simultaneously. Users must 504 select their desired capture mode using the mode selector switch. 505* HDR mode is not supported when using the dual concurrent camera feature. 506* Different lenses on the device may have varying HDR capabilities. Some lenses may support HDR 507 capture, while others may only support SDR capture. 508* In HDR mode, single-stream mode is exclusively used for video capture. Image capture is disabled 509 when single-stream mode is enabled. 510* The viewfinder utilizes HDR rendering during 10-bit HDR video capture. However, HDR rendering may 511 not be used in Ultra HDR image capture mode. 512* During HDR preview, standard dynamic range (SDR) assets, such as the app's user interface, may 513 appear dimmed. 514 515--- 516 517### LLB (Low Light Boost) 518 519Enhances the brightness of the camera's preview and recorded videos. If the device supports it, this 520feature utilizes Camera2's `ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY` auto-exposure (AE) mode to 521improve brightness in low-light conditions. 522 523#### How to Enable / Use 524 5251. Tap the flash icon to cycle through flash modes. 5262. The crescent moon icon indicates that LLB is enabled. 5273. LLB has two states: 528 1. Outlined Crescent Moon: LLB is inactive (the scene isn't dark enough). 529 2. Filled Crescent Moon: LLB is active (the scene is dark enough, and brightness is enhanced). 5304. To disable LLB, switch to a different flash mode. 531 532#### Constraints / Limitations 533 534* A reduced frame rate can introduce some motion blur. 535* It only works on Preview and Video Capture in multi-stream mode. 536* Images captured in single-stream mode will still be brightened. 537* Not all devices support Low Light Boost. Only lenses with `ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY` 538 as an available `CONTROL_AE_AVAILABLE_MODES` support LLB. 539* LLB will override the frame rate setting. 540 541--- 542 543### Single / Multi-stream Mode 544 545This setting controls whether the camera uses a single stream or multiple streams for preview, 546video, and image capture. 547 548* **Multi-stream mode:** Uses separate streams for preview, video recording, and still image 549 capture. The output of each stream may appear slightly different. In general, this mode can be 550 more efficient and have higher performance than single-stream mode. 551* **Single-stream mode:** Uses a single stream for all functions. In this mode, the preview 552 accurately reflects what will be captured in videos or images. This is a common mode that is used 553 in apps that want to apply effects to the camera stream and have them appear in captured images 554 and videos. 555 556#### How to Enable / Use 557 5581. Open quick settings by tapping the downward facing arrow at the top of the screen. 5592. Tap the single or multi stream button. This will toggle between single stream or multi stream 560 modes. 561 562#### Constraints / Limitations 563 564* Ultra HDR cannot be enabled in single stream mode. 565* Multi or single stream selectors are not available when using Dual Concurrent Cameras. 566 567## Special Application Features 568 569This section explores features that provide extended functionality and customization within the 570camera app, going beyond core image and video capture capabilities. These features cater to specific 571user preferences and developer needs. 572 573### Debug Mode 574 575Provides advanced camera information and controls for developers. 576 577#### How to Enable / Use 578 5791. Launch the app with extra KEY_DEBUG_MODE set to true 5802. Access the debug mode UI through the purple “Debug” button in the preview screen 581 582#### Constraints / Limitations 583 584* Intended for developers and may cause instability. 585 586--- 587 588### Intent Capture Modes 589 590Launch the app into modes with specialized user flow. Also allows configuring content values for 591media to be captured 592 593#### How to Enable / Use 594 5951. In the launching intent for JCA, set intent action to ACTION_IMAGE_CAPTURE, ACTION_VIDEO_CAPTURE, 596 or INTENT_ACTION_STILL_IMAGE_CAMERA for single image capture, single video capture, or multiple 597 image capture mode. 5982. Configure content values and insert the url into the intent at MediaStore.EXTRA_OUTPUT 5993. Launch JCA 600 601--- 602 603### Dark Mode 604 605This feature allows users to customize the app's appearance by selecting between three modes: 606 607* **On:** Enables dark mode, displaying UI elements with a darker color scheme. 608* **Off:** Enables light mode, displaying UI elements with a lighter color scheme. 609* **System:** Adopts the system-wide dark mode setting, dynamically adjusting the app's appearance 610 based on the user's device preferences. 611 612The appearance of UI elements will differ depending on the selected mode. This setting only affects 613the user interface and does not impact the captured images or videos. 614 615#### How to Enable / Use 616 6171. Open the camera app settings from the settings icon in the upper left corner. 6182. Tap the “Set Dark Mode” setting under “App Settings”. 6193. Select the desired mode. 620 621# Source Code Headers 622 623Every file containing source code must include copyright and license 624information. This includes any JS/CSS files that you might be serving out to 625browsers. (This is to help well-intentioned people avoid accidental copying that 626doesn't comply with the license.) 627 628Apache header: 629 630 Copyright (C) 2024 The Android Open Source Project 631 632 Licensed under the Apache License, Version 2.0 (the "License"); 633 you may not use this file except in compliance with the License. 634 You may obtain a copy of the License at 635 636 https://www.apache.org/licenses/LICENSE-2.0 637 638 Unless required by applicable law or agreed to in writing, software 639 distributed under the License is distributed on an "AS IS" BASIS, 640 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 641 See the License for the specific language governing permissions and 642 limitations under the License. 643
