# Video Selfie

The Video Selfie module records a short video of the user performing a guided series of actions, including capturing their ID and selfie, to confirm physical presence and run liveness and face match checks. It can also capture voice consent.

For an overview of this module and how it works, see [Video Selfie](https://developer.incode.com/docs/video-selfie).

How you use this module depends on your [integration pattern](https://developer.incode.com/docs/android-common-implementation-patterns#integration-patterns). In Patterns 1 and 2, you add the module to a `FlowConfig` in code as shown on this page. In Pattern 3, you define your modules and configuration in Dashboard as a Flow or Workflow and reference it by ID with `startFlow()` or `startWorkflow()` as shown on [Run Flows Configured in Dashboard](https://developer.incode.com/docs/android-run-flows-configured-online).

Video Selfie is not available in [Capture-Only mode](https://developer.incode.com/docs/android-capture-only-sdk); adding it there throws `ModuleNotAvailableException`.

Screen recording requires API level 21 or later.

## Add Video Selfie

1. Add a selfie step before Video Selfie: either an [ID Scan](https://developer.incode.com/docs/android-id-scan) that captures a selfie, or the [Selfie Scan](https://developer.incode.com/docs/android-selfie-scan) module. The face captured here is matched against that selfie, so omitting it causes the module to fail with `SelfieNotMatchedException`.
2. Add the module with one of the `addVideoSelfie` overloads:

   ```kotlin
   // Default configuration
   flowConfigBuilder.addVideoSelfie()

   // Custom configuration built with VideoSelfie.Builder
   flowConfigBuilder.addVideoSelfie(videoSelfie)
   ```
   ```java
   // Default configuration
   flowConfigBuilder.addVideoSelfie();

   // Custom configuration built with VideoSelfie.Builder
   flowConfigBuilder.addVideoSelfie(videoSelfie);
   ```

### Example

The example below builds a `VideoSelfie` module with selfie matching and liveness enabled, adds it to the flow, and listens for the result through `onVideoRecorded()`.

```kotlin
val videoSelfie = VideoSelfie.Builder()
    .setSelfieMode(VideoSelfie.SelfieMode.SELFIE_MATCH)
    .setLivenessEnabled(true)
    .build()

val flowConfig = FlowConfig.Builder()
    .addVideoSelfie(videoSelfie)
    .build()

IncodeWelcome.getInstance().startOnboarding(
    activityContext,
    sessionConfig,
    flowConfig,
    object : OnboardingListener() {
        override fun onVideoRecorded(videoSelfieResult: VideoSelfieResult) {
            // Video recorded and uploaded
        }

        override fun onError(error: Throwable) {}

        override fun onUserCancelled() {}
    }
)
```
```java
VideoSelfie videoSelfie = new VideoSelfie.Builder()
    .setSelfieMode(VideoSelfie.SelfieMode.SELFIE_MATCH)
    .setLivenessEnabled(true)
    .build();

FlowConfig flowConfig = new FlowConfig.Builder()
    .addVideoSelfie(videoSelfie)
    .build();

IncodeWelcome.getInstance().startOnboarding(
    activityContext,
    sessionConfig,
    flowConfig,
    new IncodeWelcome.OnboardingListener() {
        @Override
        public void onVideoRecorded(@NonNull VideoSelfieResult videoSelfieResult) {
            // Video recorded and uploaded
        }

        @Override
        public void onError(@NonNull Throwable error) {}

        @Override
        public void onUserCancelled() {}
    }
);
```

## Configuration Options

Configure the module with `VideoSelfie.Builder`. The table below lists the most commonly used options.

| Setting                                 | Description                                                                                                                                                                                         |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setSelfieMode(VideoSelfie.SelfieMode)` | Sets the comparison mode for the captured selfie. `SELFIE_MATCH` (default) matches the new selfie against a previously captured selfie; `FACE_MATCH` matches it against the previously captured ID. |
| `setLivenessEnabled(Boolean)`           | Enables or disables the liveness check.                                                                                                                                                             |
| `setShowTutorials(Boolean)`             | Shows or hides the tutorial screen before recording.                                                                                                                                                |
| `setMaxVideoLength(Int)`                | Sets the maximum recording length.                                                                                                                                                                  |
| `setDisableAudio(Boolean)`              | Records video without audio.                                                                                                                                                                        |
| `setLogo(Int)`                          | Sets a drawable resource shown during recording.                                                                                                                                                    |

For the complete option set, see `VideoSelfie.Builder` in [API Reference](https://developer.incode.com/docs/android-api-reference).

## Result

Video Selfie delivers a `VideoSelfieResult` through the `OnboardingListener` callback `onVideoRecorded(VideoSelfieResult)`. Key fields include:

- `videoFilePath`: The URI pointing to the recorded video file; `null` when unavailable.
- `audioFilePath`: The URI pointing to the recorded audio file; `null` when unavailable.
- `selfieImagePath`: The URI pointing to the captured selfie image; `null` when unavailable.
- `idFrontImagePath`: The URI pointing to the captured ID front image; `null` when unavailable.
- `idBackImagePath`: The URI pointing to the captured ID back image; `null` when unavailable.
- `documentImagePath`: The URI pointing to the captured document image; `null` when unavailable.
- `voiceConsentSelfiePath`: The URI pointing to the voice-consent selfie image; `null` when unavailable.

- Fields inherited from `BaseResult`:
  - `resultCode`: The `ResultCode` for this result.
  - `error`: When `resultCode` is `ERROR`, the `Throwable` that caused it; otherwise, `null`.
  - `deviceStats`: The `DeviceStats` snapshot of the device state when the result was produced.
  - `motionStatus`: Device motion assessment during capture. One of the following:
    - `UNCLEAR`: Motion could not be determined; the default.
    - `PASS`: Device motion was within acceptable limits.
    - `FAIL`: Excessive device motion was detected.

Errors surface through `OnboardingListener.onError(Throwable)`. For this module, the throwable is a `VideoSelfieException` subtype: `SelfieNotMatchedException`, `AudioNotMatchedException`, or `VideoUploadException`.

For all fields, see `VideoSelfieResult` in [API Reference](https://developer.incode.com/docs/android-api-reference).