AVCaptureDevice: torchMode property
The torchMode property controls the torch next to the camera: off, on, or switched automatically by ambient light.
Value
A string, one of these three:
| Value | Effect |
|---|---|
'off' | Off |
'on' | Stays on |
'auto' | Turns on automatically when it's dark and off when it's bright |
- Readable and writable.
- Defaults to
'off'(verified by testing). - Call
lockForConfiguration()before writing it, andunlockForConfiguration()afterwards. - That the torch actually lights up after writing
'on'or'auto'is not verified on a device. - The app writes it itself, and there is no event when it changes.
Invalid values
- Writing without the lock: throws a
DOMExceptionwhosenameis'InvalidStateError', and the value doesn't change (verified by testing). The message istorchMode: the system refused (…); the parentheses hold the reason the system gave, which says to lock first (-lockForConfiguration:). - The camera has no torch (
hasTorchisfalse) or doesn't support this value: the system refuses, and it throws aDOMExceptionwhosenameis'InvalidStateError', with the reason the system gave in the message. Not verified on a device. - Writing a value not in the table doesn't throw: a warning listing all valid values is printed to the console, and
torchModekeeps its previous value (verified by testing).
Examples
js
const device = AVCaptureDevice.defaultDeviceWithMediaType('video');
if (device !== null && device.hasTorch) {
device.lockForConfiguration();
try {
device.torchMode = device.torchMode === 'on' ? 'off' : 'on';
} finally {
device.unlockForConfiguration();
}
console.log(device.torchMode);
}Effect: turns the torch on if it's off and off if it's on, and prints the new value. The torch actually lighting up and going out is not verified on a device.
Corresponding iOS API
AVCaptureDevice.torchMode. AVCaptureTorchModeOn is written as 'on', and so on. In ObjC, writing without the lock throws NSGenericException; here it throws a DOMException whose name is 'InvalidStateError'.
See also
hasTorch,isTorchAvailable: whether there is one, and whether it can be used now- Lock before changing settings
- Turn on the flashlight