Video Selfie Module

Note

This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation here. Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade.

Full rollout to all clients still TBD.

The Video Selfie module runs selfie, ID, and optional voice-consent capture as one continuous camera session, recorded on-device and uploaded alongside the captures. The camera switches between front and rear while a single composited recording follows it, so the user sees one uninterrupted experience instead of a sequence of separate capture screens.

Combines camera-capture and composite / orchestrator traits: it owns several capture steps and drives its own step progression. See the patterns page for the shared lifecycle.

Tag

<incode-video-selfie> is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.

import '@incodetech/web/video-selfie';
import '@incodetech/web/video-selfie/styles.css';

Properties

Property	Type	Required	Description
`config`	`VideoSelfieConfig`	❌	Configuration options
`onFinish`	`() => void`	❌	Called when the session completes
`onError`	`(error: string \| undefined) => void`	❌	Called when an error occurs

Configuration

VideoSelfieConfig mirrors the backend VIDEO_ONBOARDING workflow module, so inside <incode-flow> or <incode-workflow> the orchestrator supplies it from your dashboard. Standalone integrators set it on config directly.

Which steps run is derived from the config rather than listed explicitly — checkIdScan adds the ID steps, checkVoiceConsent adds the speech step.

Option	Type	Description
`useAsSelfie`	`boolean`	Treat the captured selfie as the session's selfie, so a separate Selfie step is unnecessary.
`showTutorials`	`boolean`	Show the tutorial screen before capture. When `false`, the module starts at the permission step.
`companyName`	`string`	Company name shown in the consent copy.
`checkLiveness`	`boolean`	Run liveness checks on the selfie step.
`checkIdScan`	`boolean`	Add the front and back ID capture steps.
`checkDocumentScan`	`boolean`	Add the proof-of-address document step.
`compareIdEnabled`	`boolean`	Compare the captured face against the ID portrait.
`compareOcrEnabled`	`boolean`	Compare OCR data from the front of the ID.
`compareBackIdEnabled`	`boolean`	Compare against the back of the ID.
`compareBackOcrEnabled`	`boolean`	Compare OCR data from the back of the ID.
`checkVoiceConsent`	`boolean`	Add the spoken-consent step.
`voiceConsentQuestions`	`number`	How many consent questions to ask.
`numberOfTries`	`number`	Validation attempts per capture and voice step. Default `3`; `-1` means unlimited.
`speechToTextCheck`	`boolean`	Validate the consent audio server-side. Default `true`.
`selfieQualityAffectsScore`	`boolean`	Let selfie quality contribute to the session score.
`validateClosedEyes`	`boolean`	Reject frames where the eyes are closed.
`validateFaceMask`	`boolean`	Reject frames where a face mask is present.
`validateHeadCover`	`boolean`	Reject frames where a head covering obscures the face.
`validateLenses`	`boolean`	Reject frames where glasses or lenses interfere.

The remaining fields (maxWaitingVideoSelfieFile, lastSecondsVideoQualityCheck, lastSecondsVideoQualityCheckDuration) tune upload and quality-check timing and come from your dashboard configuration. Pass them through unmodified.

Steps

VideoSelfieStep is the set of capture steps a session can run, in flow order:

Step	Camera	Description
`selfie`	Front	Face capture with liveness and quality checks.
`frontId`	Rear	Front of the ID document.
`backId`	Rear	Back of the ID document.
`poa`	Rear	Proof-of-address document.
`questions`	Front	On-screen consent questions.
`speech`	Front	Spoken consent, recorded for verification.

State machine

VideoSelfieRecordingState carries a status plus live step and detection detail:

Status	Description
`idle`	Initial state, waiting for `start()`.
`starting`	Acquiring the first camera and opening the upload.
`recording`	Capturing the active step.
`validationFeedback`	A validation check failed; the module dwells to show the reason before retrying.
`flippingId`	Prompting the user to turn the ID over between the front and back steps.
`switchingCamera`	Moving between front and rear cameras for the next step.
`finalizing`	Finishing the upload after the last step.
`success`	Upload accepted. Carries `recordingId`.
`finished`	Terminal.
`error`	Failed. Carries `error` and `errorKind`.
`aborted`	The session was abandoned without finalizing.

State properties:

Property	Type	Description
`step`	`VideoSelfieStep?`	The active capture step.
`stepIndex`	`number`	Zero-based index of the active step.
`isLastStep`	`boolean`	Whether advancing finalizes the session.
`stream`	`MediaStream?`	The raw camera for the active step. Render this as the preview.
`composite`	`MediaStream?`	The composited recording output that follows camera switches. Not for preview.
`detectionStatus`	`string?`	Live capture feedback for the active step — show it as guidance.
`orientation`	`DetectionOrientation?`	Document orientation when the detector reports one, so an ID mask can follow a rotated document. `undefined` keeps the fixed frame.
`validationFailure`	`object?`	Why the current attempt failed, during a `validationFeedback` dwell.
`attemptsRemaining`	`number`	Attempts left on the active step. `-1` means unlimited.
`recordingId`	`string \| null`	The completed upload id, available during `success` and `finished`.
`error`	`string?`	Failure detail when `status === 'error'`.
`errorKind`	`'connection' \| 'technical'`	Whether the failure was a transport problem or something else. Use it to choose retry copy.

API methods

Method	Purpose	Callable when
`start()`	Acquire the camera, open the upload, and begin recording.	`idle`
`nextStep()`	Advance to the next step, switching cameras when needed. Finalizes on the last.	`recording`
`retry()`	Retry the active step after a validation failure or error.	`validationFeedback`, `error`
`abort()`	Abandon the session without finalizing the upload.	Any active status

Plus the universal lifecycle: subscribe, getState, stop.

Headless usage

import { setup } from '@incodetech/core';
import {
  createVideoSelfieRecordingManager,
  warmupVideoSelfieWasm,
} from '@incodetech/core/video-selfie';

await setup({ apiURL, token });
await warmupVideoSelfieWasm(config);

const manager = createVideoSelfieRecordingManager({ config });

manager.subscribe((state) => {
  if (state.status === 'recording') {
    renderPreview(state.stream, {
      step: state.step,
      guidance: state.detectionStatus,
      attemptsLeft: state.attemptsRemaining,
    });
  }
  if (state.status === 'finished') {
    onDone(state.recordingId);
  }
});

manager.start();

Render state.stream as the preview, not state.composite — the composite exists to keep one continuous recording across camera switches.

@incodetech/core/video-selfie also exports helpers for building your own capture screen: resolveVideoSelfieSteps (which steps a config runs), facingModeForStep, createVideoSelfieCameraWarmer (warm the camera before the user reaches the step), getVideoSelfieQuestions and getVoiceConsentPhrase (consent copy), and createConsentRecorder.

WASM requirement

Video Selfie needs the videoSelfie pipeline, plus videoSelfieId when checkIdScan is enabled. Call warmupVideoSelfieWasm(config) to preload exactly what the config needs, or derive the list yourself with videoSelfieWasmPipelines(config) and pass it to setup({ wasm: { pipelines } }).