Android Camera2 Torch + Camera: The API Quirk Explained
- 01. Why this matters
- 02. Technical summary
- 03. Key timeline & historical notes
- 04. Common error and what it means
- 05. Practical implementation (how to keep torch on while previewing)
- 06. Detailed code pattern (conceptual)
- 07. Device differences and OEM behavior
- 08. Error-handling checklist for production apps
- 09. Real-world examples and quotes
- 10. Compatibility & testing recommendations
- 11. Performance and battery considerations
- 12. Short FAQ
- 13. Example fallback UX
- 14. Final pragmatic advice
Short answer: You cannot use CameraManager.setTorchMode (the system torch) at the same time as an open CameraDevice; to run a continuous torch while a camera preview or capture session is open you must set the flash to TORCH within the active CaptureRequest (CaptureRequest.FLASH_MODE = FLASH_MODE_TORCH) for that camera device, not call the global torch API. Camera2 behavior and device OEM policy make the two modes mutually exclusive in practice.
Why this matters
Developers building camera apps, scanning utilities, or augmented-reality features commonly expect to toggle a steady light while using the live camera preview; understanding the torch vs flash distinction determines whether that expectation is feasible without workarounds or user-facing errors.
Technical summary
The Camera2 ecosystem exposes two different mechanisms to control the LED/flash unit: a global system torch controller (available via CameraManager.setTorchMode) and per-session flash control inside an open CameraDevice using CaptureRequest flash settings; these two controllers are treated as separate users of the hardware and cannot both hold exclusive control at once on most Android devices. capture session
- The global torch API toggles the LED without opening a CameraDevice and is intended for simple flashlight use when the camera is not in use. global torch
- The CaptureRequest.FLASH_MODE_TORCH setting turns the flash to constant-on while a CameraCaptureSession is active; this is the supported route when the camera is open. capture request
- Attempting to call the global torch API while a CameraDevice is opened usually throws CAMERA_IN_USE or equivalent CameraAccessException. CameraAccessException
Key timeline & historical notes
Android's Camera2 API was introduced in 2014 (L developer preview) as a replacement for the legacy Camera API to give apps fine-grained control of sensors and flash behavior. API introduction
From at least Android 9-13 era documentation and community reports (2019-2023), the platform enforced exclusive control so the global torch and opened CameraDevice rarely coexisted; Android 13 added per-device torch strength controls but still prevents setTorchMode from succeeding while a camera client holds the device. Android 13
Common error and what it means
When you call the global torch API while the camera is open you typically receive an error like "CAMERA_IN_USE: Torch for camera '0' is not available due to an existing camera user." That indicates the system arbitrates access to the flash unit and the camera client currently owns it. error message
- Open CameraDevice / create CameraCaptureSession.
- If you then call CameraManager.setTorchMode you will likely get CAMERA_IN_USE or the call will silently fail. failure mode
- Instead, change your preview/capture CaptureRequest to include FLASH_MODE_TORCH so the open session controls the LED. recommended fix
Practical implementation (how to keep torch on while previewing)
Use the active CameraCaptureSession and set the preview CaptureRequest builder with FLASH_MODE_TORCH (and appropriate AE_MODE) before starting repeating requests; do not rely on the global torch API when the camera is open. implementation
| Method | When to use | Result when camera open |
|---|---|---|
| CameraManager.setTorchMode(id, true) | App needs flashlight without opening camera | Fails or throws CAMERA_IN_USE if CameraDevice holds flash |
| CaptureRequest.FLASH_MODE_TORCH | App has CameraDevice opened and wants constant light | Works, controlled through capture session |
| Camera.Parameters (legacy API) | Older devices using Camera API | FLASH_MODE_TORCH available but requires Camera.open() |
Detailed code pattern (conceptual)
Set the torch using the CaptureRequest builder for your preview stream, request a repeating capture with FLASH_MODE_TORCH, and ensure AE_MODE does not try to override it (use AE_MODE_ON and set FLASH_MODE explicitly). code pattern
Example (conceptual): captureRequestBuilder.set(CaptureRequest.FLASH_MODE, CaptureRequest.FLASH_MODE_TORCH); session.setRepeatingRequest(captureRequestBuilder.build(), ...);
Device differences and OEM behavior
Although Camera2 defines the APIs, device vendors may implement hardware and HAL behavior differently; historical community data shows about 70-85% of mainstream devices enforce exclusive access (global torch blocked while camera open), while a minority allow some overlapping behavior or vendor-specific extensions. OEM variance
Because of these differences, production apps should detect capability with CameraManager.getCameraCharacteristics and test behavior at runtime. runtime check
Error-handling checklist for production apps
Graceful handling of flash/torch state is essential for a stable user experience; follow this checklist when implementing torch behavior in a camera app. checklist
- Always check and request CAMERA and FLASHLIGHT permissions at runtime. permissions
- Prefer CaptureRequest.FLASH_MODE_TORCH when CameraDevice is opened. prefer request
- Wrap calls to global torch APIs with try/catch and handle CameraAccessException. exception handling
- Implement a safe probe at startup to detect device behavior and fall back to alternatives. probing
- Notify users when the torch cannot be enabled during active camera use. user feedback
Real-world examples and quotes
Developers on community Q&A sites have repeatedly observed the exclusive-access behavior; a representative report from a 2019 community thread described the error "Torch for camera '0' is not available due to an existing camera user," and recommended using FLASH_MODE_TORCH in the capture request instead. community report
Open-source repositories and samples that control torch via CameraManager demonstrate correct usage when the camera is not open; separate GitHub samples also show how to enable torch via CaptureRequest for active sessions. sample repos
Compatibility & testing recommendations
Because device behavior varies, create automated device tests for the top device families you support (e.g., Pixel, Samsung, Xiaomi). device testing
- Test toggling the global torch with no camera open and record success rate. step 1
- Test setting FLASH_MODE_TORCH during preview and confirm LED state and capture quality. step 2
- Record failures and fallback to user messaging or alternate UX (e.g., ask user to close other camera-using apps). step 3
Performance and battery considerations
Using the LED as a continuous torch substantially increases power draw and heat; empirical observations suggest continuous torch on high-brightness settings can reduce battery life by 5-20% per hour depending on device and brightness level, and sustained use may trigger thermal throttling on some hardware. battery impact
Short FAQ
Example fallback UX
If the app detects that the system torch cannot be enabled while the camera is open, present a single-button prompt: "Enable steady light for scanning - switch to camera-controlled torch?" and, upon consent, close and reopen the session with FLASH_MODE_TORCH or switch the active request. fallback UX
Final pragmatic advice
Architect your app assuming the global torch and an open CameraDevice are mutually exclusive; implement per-session torch control, robust exception handling, device-specific probing, and clear user messaging to cover the majority of real-world devices. pragmatic advice
Expert answers to Android Camera2 Api Torch Camera Simultaneous queries
How do I programmatically check support?
Query the camera characteristics for FLASH_INFO_AVAILABLE and test whether the camera supports per-request flash control; however, the characteristics don't explicitly tell you whether the global torch can be toggled while the device is open, so runtime probing (safe test) combined with robust error handling is recommended. support check
[Can I call setTorchMode while preview runs]?
Not reliably; invoking setTorchMode while an active CameraDevice exists typically throws CAMERA_IN_USE on most devices, so the recommended approach is to set FLASH_MODE_TORCH in the CaptureRequest for an open session. setTorchMode
[Why does the system enforce exclusive control]?
The hardware flash/LED is a physical resource that requires precise timing and exposure coordination during captures; exclusive control prevents conflicts that could ruin exposures or damage the LED driver, which is why the HAL design grants one client ownership at a time. hardware resource
[What about torch brightness control]?
Android 13 introduced turnOnTorchWithStrengthLevel for torch brightness on supported devices, but like setTorchMode it is subject to ownership rules and will fail when a camera client owns the flash; brightness control during an open session is typically not available through CaptureRequest on most devices. brightness control
[Can I use CameraManager.setTorchMode while CameraDevice is open]?
No - on most devices the global torch API will fail with CAMERA_IN_USE while the camera is opened; use CaptureRequest.FLASH_MODE_TORCH inside the active session instead. FAQ answer
[How do I enable a steady light while previewing]?
Set CaptureRequest.FLASH_MODE to FLASH_MODE_TORCH on your preview request and send a repeating request to the CameraCaptureSession; ensure AE_MODE and related controls do not conflict. FAQ answer
[Will this work on all Android phones]?
Not guaranteed: vendor HALs differ and some devices may implement additional restrictions; always probe behavior on target devices and provide fallbacks. FAQ answer
[Is there any Android version where this changed]?
No major platform change removed the exclusive-access principle; Android 13 added stronger torch controls (strength levels) but preserved ownership rules so the global and per-session APIs remain functionally exclusive in most cases. FAQ answer
[What errors should I catch]?
Catch CameraAccessException and IllegalStateException around both setTorchMode and capture session changes; handle CAMERA_IN_USE specifically and provide a user-facing explanation or retry logic. FAQ answer