Required Lighting

The Required Lighting setting controls the live lighting requirements LIQA uses during camera capture. It affects whether the user is asked to improve lighting intensity or turn toward the light source before LIQA collects the image.

Use required-lighting when you need to balance image standardization with completion rate in real user environments.

For physical lighting setup recommendations, see the On-Site Setup guide.

Client need	Recommended option
Collect the most standardized face image with optimal lighting requirements	default
Help users complete capture when lighting conditions are poor but still keep live lighting guidance	adaptive
Allow capture when users cannot achieve good lighting, accepting that analysis quality may be affected	none

Use the required-lighting API to customize the capture flow. If the property is left empty, the default option will be used.

Options

Option	Behavior
default	Keeps optimal lighting requirements for better image detail. This is the recommended default for most face and skin-analysis flows.
adaptive	Starts with normal lighting requirements and relaxes them when lighting conditions are poor. On desktop, adaptive lighting relaxes faster to reduce blocking users with limited webcam lighting control.
none	Disables lighting validation during capture. Use carefully when users cannot achieve good lighting: poor lighting can affect analysis quality and image consistency.

Default default

Use default when the capture flow should wait for optimal lighting before collecting the image.

tsx
<hautai-liqa
  license="LICENSE_KEY_PROVIDED_BY_HAUT.AI"
  required-lighting="default"
>
</hautai-liqa>

tsx
<hautai-liqa
  license="LICENSE_KEY_PROVIDED_BY_HAUT.AI"
  required-lighting="default"
>
</hautai-liqa>

How it works

• LIQA validates live lighting intensity and lighting direction.
• The user receives lighting guidance when the face is too dark, too bright, or not lit evenly enough from the front.
• Auto-capture waits until the configured lighting requirements are met together with the other live quality criteria.

Adaptive

Use adaptive when users may not have ideal lighting control, especially on desktop devices, but you still want LIQA to guide them toward better lighting before capture.

tsx
<hautai-liqa
  license="LICENSE_KEY_PROVIDED_BY_HAUT.AI"
  required-lighting="adaptive"
>
</hautai-liqa>

tsx
<hautai-liqa
  license="LICENSE_KEY_PROVIDED_BY_HAUT.AI"
  required-lighting="adaptive"
>
</hautai-liqa>

How it works

• LIQA starts with the normal live lighting requirements.
• If lighting remains poor, LIQA gradually softens the lighting requirements so the user is less likely to get stuck.
• Desktop adaptive lighting relaxes faster than the standard adaptive profile because desktop users often have less control over camera position and surrounding light.

None

Use none only when users cannot reliably achieve good lighting, or when completion is more important than lighting standardization. This can affect the quality of the analysis because LIQA will allow images captured in poor or uneven lighting.

tsx
<hautai-liqa
  license="LICENSE_KEY_PROVIDED_BY_HAUT.AI"
  required-lighting="none"
>
</hautai-liqa>

tsx
<hautai-liqa
  license="LICENSE_KEY_PROVIDED_BY_HAUT.AI"
  required-lighting="none"
>
</hautai-liqa>

Analysis quality

required-lighting="none" disables LIQA lighting validation during capture. Images collected in poor or uneven lighting can reduce analysis quality and make results less consistent.

How it works

• LIQA does not block capture on live lighting intensity or lighting direction.
• Other live capture requirements for the selected preset still apply.
• Post-capture quality checks can still report lighting-related issues if Photo Quality Check is enabled.

Preset support

required-lighting is configurable for the face preset.

For other presets, LIQA uses default lighting behavior according to the public API contract.

Relationship to quality checks

required-lighting controls live capture guidance and capture readiness while the user is in front of the camera.

quality-check controls post-capture validation after an image is captured or uploaded. It can report lighting-related quality issues such as exposure, uneven illumination, and shadows, but it does not replace the live capture behavior controlled by required-lighting.

Use both features when the user should be guided during capture and the submitted image should still be validated before upload.

Compatibility

The old settings.lighting configuration is deprecated.

If required-lighting is not provided, settings.lighting=0 maps to requiredLighting: "none" for backward compatibility. New integrations should use required-lighting="none" directly instead.