Camera
Defined under the namespace Scandit.Datacapture.Core
- TorchState
Added in version 6.13.0
Possible values for the torch state.
- On
Added in version 6.13.0
Value to indicate that the torch is turned on.
- Off
Added in version 6.13.0
Value to indicate that the torch is turned off.
- PermissionState
Added in version 8.6.0
The camera access permission state.
- Granted
Added in version 8.6.0
Camera access has been granted by the user.
- Denied
Added in version 8.6.0
Camera access has been denied by the user.
- Prompt
Added in version 8.6.0
Camera access has not been decided yet; requesting it will prompt the user.
- VideoFrameResolution
interface VideoFrameResolutionAdded in version 6.13.0
Resolution of a video frame.
- CamerasWithPermissionState
interface CamerasWithPermissionStateAdded in version 8.6.0
The result of Camera.getAllWithPermissionState(): the available cameras together with the current camera permission state.
- cameras
readonly cameras: Camera[]
Added in version 8.6.0
The available cameras on the device. Could be empty if the user has denied camera access.
- permissionState
readonly permissionState: PermissionState
Added in version 8.6.0
The current camera access permission state.
- ZoomListener
interface ZoomListenerAdded in version 8.4.0
Interface definition for a callback to be invoked when the zoom level of a Camera changes.
- Camera
class Camera : FrameSource
Added in version 6.13.0
Gives access to the built-in camera on Web. It implements the FrameSource interface, and, as such can be set as the frame source for the DataCaptureContext.
Instances of this class are created through one of the static methods pickBestGuess(), pickBestGuessForPosition() or forDeviceId().
The camera is started by changing the desired state to FrameSourceState.On.
By default, the resolution of captured frames as well as auto-focus and exposure settings are chosen such that they work best for a variety of use cases. To fine-tune recognition, the camera settings can be changed through applying new camera settings.
Cameras on web are not accessible by default, their details can only be retrieved once the user has granted permission.
Important
The permission prompt will be triggered when starting the camera, or if you gather Cameras from the device in advance by using getAllWithPermissionState() or getAll(). So you should not initiate the camera too early or the user will be prompted for permission when they are not expecting it.
Properties like deviceId and label will be updated on the instance only once the camera has been accessed. Similarly, the currentResolution will be updated only once the camera has been started.
Please bear in mind that web cameras do not always have meaningful metadata. The SDK will try to infer the position and other properties of the camera based on the metadata, but it is not always possible. That’s why the static methods pickBestGuess() and pickBestGuessForPosition() may not always return the camera you expect.
- desiredState
get desiredState(): FrameSourceState
Added in version 6.13.0
Implemented from FrameSource. See FrameSource.desiredState.
- getCurrentState()
getCurrentState(): FrameSourceState
Added in version 6.13.0
Implemented from FrameSource. See FrameSource.getCurrentState.
- position
position: CameraPosition
Added in version 6.13.0
The direction that the camera faces.
Note that this property represents a desirable position before the camera has started, but may get updated to a different value once the camera has started to reflect what the camera reports as position.
- currentResolution
get currentResolution(): VideoFrameResolution | null
Added in version 6.13.0
The current video frame resolution of the camera. Only available once the camera has started.
- addListener(listener)
addListener(listener: FrameSourceListener | null):
voidAdded in version 6.13.0
Implemented from FrameSource. See FrameSource.addListener().
- removeListener(listener)
removeListener(listener: FrameSourceListener | null):
voidAdded in version 6.13.0
Implemented from FrameSource. See FrameSource.removeListener().
- pickBestGuess()
static pickBestGuess(): Camera
Added in version 8.0.0
Returns a Camera instance representing the optimal camera detected on the device to capture data. Given the wide variation in web camera implementations and often incomplete metadata, this method employs heuristics to automatically select the camera best suited for reliable data capture operations.
Note that this function always return the same Camera instance.
- pickBestGuessForPosition(position)
static pickBestGuessForPosition(position: CameraPosition): Camera
Added in version 8.0.0
Returns a Camera instance representing the best camera detected on the device to capture data for the given position. Given the wide variation in web camera implementations and often incomplete metadata, this method employs heuristics to automatically select the camera that best matches the given position. In rare case the automatic detection may fail to select the right camera, either because no camera was found for the given position or because the algorithm could not determine the correct position from the metadata it received.
Note that until cameras have not been discovered on the device (happens when a camera starts or if you call getAllWithPermissionState() or getAll()), you cannot have more than one camera for a given position. Calling multiple times pickBestGuessForPosition() with the same position will return the same Camera instance.
- forDeviceId(deviceId)
static forDeviceId(deviceId: string): Camera
Added in version 8.0.0
Returns a Camera instance with the given deviceId. This method allows you to access a camera that you have already gathered from the device in advance using getAllWithPermissionState() or getAll(). Once started, the camera properties label and position will be updated, as well as the resolution.
Calling multiple times forDeviceId() with the same deviceId` will return the same Camera instance.
- getAll(refreshDevices, cameraAlreadyAccessed)
static getAll(refreshDevices?: boolean, cameraAlreadyAccessed?: boolean): Promise<Camera[]>
Added in version 6.13.0
Note
Prefer getAllWithPermissionState(), which additionally reports the camera PermissionState and thus lets you tell apart an empty result caused by the absence of cameras from one caused by the user denying access. This method remains for backward-compatibility reasons.
- Param [refreshDevices]
Force a call to refresh available video devices even when information is already available, defaults to false
- Param [cameraAlreadyAccessed]
Hint that a camera has already been accessed before, avoiding a possible initial camera access permission request on the first call, in cases this cannot be already reliably detected, defaults to false
Gets a list of cameras (if any) available on the device, a camera access permission is requested to the user the first time this method is called if needed.
If the user denies the necessary camera access permission, the list of cameras will be empty.
If the browser is incompatible the returned promise is rejected with a UnsupportedBrowserError error.
When refreshing available devices, if updated deviceId information is detected, cameras’ deviceId are updated accordingly. This could happen after a camera is accessed and then stopped in some situations.
- getAllWithPermissionState(refreshDevices, cameraAlreadyAccessed)
static getAllWithPermissionState(refreshDevices?: boolean, cameraAlreadyAccessed?: boolean): Promise<CamerasWithPermissionState>
Added in version 8.6.0
- Param [refreshDevices]
Force a call to refresh available video devices even when information is already available, defaults to false
- Param [cameraAlreadyAccessed]
Hint that a camera has already been accessed before, avoiding a possible initial camera access permission request on the first call, in cases this cannot be already reliably detected, defaults to false
Behaves like getAll() but additionally reports the camera PermissionState. This lets you tell apart an empty camera list caused by the absence of cameras on the device (PermissionState.Granted with no cameras) from one caused by the user denying camera access (PermissionState.Denied).
The permission state is retrieved through the browser Permissions API when available, without triggering a permission prompt. On browsers that do not support querying the camera permission (such as Safari 14 and before Firefox 132), the state is derived from the enumerated cameras and from the camera-access attempt this method already performs (the same attempt as getAll()), so a denial is still reported. It may be reported as PermissionState.Prompt only when the state cannot be determined, for example when no cameras are present and access has not been attempted.
If the browser is incompatible the returned promise is rejected with a UnsupportedBrowserError error.
The value returned by getAllWithPermissionState() tells your application how to react. The reliable signal is the PermissionState; the returned cameras are a secondary hint that, when access has not been granted, may contain entries that cannot be used. The table below summarizes the recommended handling for each case.
Permission state
Cameras
What it means
What to do
One or more
Access is granted and camera hardware is present.
Proceed: start a camera, or let the user choose one from the returned list.
Empty
Access is granted, but the device has no camera.
Inform the user that no camera is available. Retrying or prompting again will not change the result.
Empty
The user has blocked camera access. This is persistent: the browser will not show the prompt again.
Guide the user to re-enable the camera permission from the browser or site settings. Do not repeatedly call the method expecting a prompt.
Empty
No decision has been recorded yet. This happens when access was never requested (for example when
cameraAlreadyAccessedis true), when the prompt was dismissed, or when there was nothing to access.Request access again, for example by calling the method with
cameraAlreadyAccessedset to false, or by starting a camera. It is safe to retry.One or more
Cameras were enumerated but the state is still undetermined. This is uncommon.
Treat the cameras as usable and proceed; starting a camera will prompt if access is still required.
Note
Distinguishing a dismissed prompt (PermissionState.Prompt) from a persistent denial (PermissionState.Denied) relies on the browser Permissions API. On browsers that do not support it (such as Safari 14 and Firefox before version 132), a dismissed prompt is reported as PermissionState.Denied. If you want a retry path to work there as well, allow the user to re-trigger a request from your denial handling.
- switchToDesiredState(state)
switchToDesiredState(state: FrameSourceState): Promise<
void>Added in version 6.13.0
Implemented from FrameSource. See FrameSource.switchToDesiredState().
- applySettings(settings)
applySettings(settings: CameraSettings): Promise<
void>Added in version 6.13.0
Applies the camera settings to the camera. The task will complete when the settings have been applied and the camera has switched to use the new settings. If the camera is currently in FrameSourceState.Off state, the task will complete immediately. If, on the other hand, the camera is currently in FrameSourceState.On state, the settings will be modified on the fly.
- settings
get settings(): CameraSettings
Added in version 6.20.0
Gets the currently set CameraSettings on this camera. Use applySettings() to apply new settings.
- isTorchAvailable()
isTorchAvailable(): Promise<boolean>
Added in version 6.13.0
Whether the torch is available for the given camera.
Available only on Chrome Android. When the camera is off, this method always returns false. When the camera is on, it returns true for cameras that support the torch, false otherwise.
- getDesiredTorchState()
getDesiredTorchState(): TorchState
Added in version 6.13.0
Gets the desired torch state for this camera. By default, the torch state is TorchState.Off. When setting the desired torch state to TorchState.On, the torch will be on as long as the camera is running (the camera’s state is FrameSourceState.On) and off otherwise.
- setDesiredTorchState(desiredTorchState)
setDesiredTorchState(desiredTorchState: TorchState): Promise<
void>Added in version 6.13.0
Sets the desired torch state for this camera. By default, the torch state is TorchState.Off. When setting the desired torch state to TorchState.On, the torch will be on as long as the camera is running (the camera’s state is FrameSourceState.On) and off otherwise. When setting the desired torch state for a camera that does not have a torch (see isTorchAvailable()), this call has no effect.
- addZoomListener(listener)
addZoomListener(listener: ZoomListener):
voidAdded in version 8.4.0
Adds a listener that will be called when the zoom level of the camera changes.
- removeZoomListener(listener)
removeZoomListener(listener: ZoomListener):
voidAdded in version 8.4.0
Removes a previously added listener for zoom level changes.
- isZoomAvailable()
isZoomAvailable(): boolean
Added in version 8.4.0
Returns whether the current camera supports zoom.
- getMirrorImageEnabled()
getMirrorImageEnabled(): boolean
Added in version 6.13.0
Gets whether the currently selected camera’s video is mirrored along the vertical axis. By default front cameras are automatically mirrored.
- setMirrorImageEnabled(enabled)
setMirrorImageEnabled(enabled: boolean): Promise<
void>Added in version 6.13.0
Sets whether the currently selected camera’s video is mirrored along the vertical axis. By default front cameras are automatically mirrored. This setting is applied per camera and the method has no effect if no camera is currently selected. In Single Image Mode this method has no effect.
- setClipArea(area)
setClipArea(area?: Rect): Promise<
void>Added in version 7.2.0
Clip the video stream to the given area. Must be called after switching the camera to FrameSourceState.On.