> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/video-recording-video-grabacion.md).

# Video Recording

The `facephi-video-provider` is a key web component of the SDK Web, enabling real-time video recording of the onboarding or authentication process. It supports real-time transmission modes (`ws`, `sse`) as well as a browser-only local recording mode (`serviceType: 'local'`).

As a provider, you must wrap the components you want to record.

Type: `HTMLFacephiVideoProviderElement`

***

## How It Works

The `facephi-video-provider` provides smooth video recording by capturing interactions and processes during authentication or onboarding. Wrapping it around components ensures that all activities are included in the recording.

***

## Recording types

Recording can be performed in different ways:

### Remote recording (default)

The tool will use WebSocket services (`ws`) or Server-Sent Events (`sse`) for recording.

{% hint style="info" %}
By default, the WebSocket service ( will be used`ws`).
{% endhint %}

#### Integration Example

Widgets must be integrated within the Video Provider tag once it has fully loaded.

```jsx
<facephi-video-provider
    settings={{ serviceType: 'ws' }}
    onChangeLoading={(event) => {
        if (!event.detail) {
            // Start Facephi widget flow
        }
    }}
/>
```

The Video Provider must be stopped once the extraction process has been completed.

```jsx
<facephi-video-provider
    settings={{ serviceType: 'local' }}
>
    <facephi-selphi-widget
        onExtractionFinish={async () => {
            await video.stopVideo();
        }}
    />
</facephi-video-provider>
```

To obtain the video, see the section on [video provider results](/docs.facephi-en/sdks/sdk-web/componentes/video-recording-video-grabacion/resultados.md#grabacion-local).

### Local recording

The component `<facephi-video-provider>` supports a **local recording** mode that captures video entirely in the browser using the MediaRecorder API. Unlike the default WebSocket service types (`ws`) or Server-Sent Events (`sse`), local recording does not transmit video to an external server during capture. Instead, the recorded video remains client-side and is returned as a `Blob` when recording stops.

The recorded video is still automatically sent through the SDK tracking pipeline (`trackingAsset` with MIME type `video/mp4`), so it integrates seamlessly with subsequent processing.

Once `<facephi-video-provider>` is rendered in the DOM with `settings.serviceType` set to `'local'`, the component **immediately starts the recording pipeline**: initializes the camera stack, calls `getUserMedia` and the browser requests the required permissions from the user (camera and microphone when `audioEnabled` es `true`). No additional start call is needed: rendering the provider is enough to start recording.

The generated video can be obtained by calling the method `stopVideo()` of the component, which will return a `Blob`.

#### Browser compatibility <a href="#browser-support" id="browser-support"></a>

Local recording is based on the **MediaRecorder API**, which is compatible with all modern browsers (Chrome, Firefox, Safari 14.5+, Edge). The component automatically selects the best video codec available for the current browser.

In **Chrome/Edge 94+**, the component uses [Insertable Streams](https://developer.chrome.com/docs/capabilities/web-apis/mediastreamtrack-insertable-media-processing) for higher-fidelity frame processing (for example, timer overlays) without an intermediate canvas layer. This is automatically detected and used without requiring configuration.

#### Permissions <a href="#permissions" id="permissions"></a>

The user must grant **camera**permission. If `audioEnabled` es `true` (the default value), microphone permission is also required **microphone**. The component internally handles the call `getUserMedia`.

#### Proxy configuration <a href="#proxy-configuration" id="proxy-configuration"></a>

If you are routing SDK requests through a forwarding proxy, you must configure the `proxy` en `<facephi-sdk-provider>` property so that the camera module can load its required assets. See the [property `proxy` of the SDK provider](/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider/propiedades/proxy.md) and the [proxy configuration guide](/docs.facephi-en/sdks/sdk-web/introduccion/configuracion-adicional.md#guia-de-configuracion-de-proxy) for configuration details.

#### Licensing <a href="#licensing" id="licensing"></a>

Local recording mode **does not require a video recording license**. When `serviceType` is configured as `"local"`, the component skips the license validation required by the modes `ws` and `sse`.

#### Integration Example

Widgets must be integrated within the Video Provider tag once it has fully loaded.

```jsx
<facephi-video-provider
    settings={{ serviceType: 'local' }}
>
    <facephi-selphi-widget />
</facephi-video-provider>
```

To obtain the video, see the section on [video provider results](/docs.facephi-en/sdks/sdk-web/componentes/video-recording-video-grabacion/resultados.md#grabacion-local).

### Differences between WS and SSE modes

| Aspect                  | Local                                             | WS / SSE                               |
| ----------------------- | ------------------------------------------------- | -------------------------------------- |
| Server infrastructure   | Not required for recording                        | Requires `baseUrl` and `apiKey`        |
| Video recording license | Not required                                      | Required                               |
| Video output            | `Blob` returned client-side through `stopVideo()` | Transmitted to the server in real time |
| Codec selection         | Automatic (best available: VP8, VP9, H.264, AV1)  | Determined by the server               |
| Timer overlay           | Optional (`videoTimer: true`)                     | Not available                          |
| Camera switching        | Supported (continuous recording maintained)       | Supported                              |
| Tracking integration    | Automatic (sent after `stopVideo()`)              | Automatic (in real time)               |

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

#### Camera permission denied <a href="#camera-permission-denied" id="camera-permission-denied"></a>

If the user denies access to the camera or microphone, the component emits an error through the SDK error pipeline (`SDKErrorType.VideoProviderError`). Listen for the event `emitError` en `<facephi-sdk-provider>` to handle it in your application.

#### Unsupported MIME type <a href="#no-supported-mime-type" id="no-supported-mime-type"></a>

In very old browsers that do not support any of the tested codecs (VP8, VP9, H.264, AV1, H.265), `MediaRecorder` will fall back to the browser's default codec. If no codec is supported, a recording error will be emitted.

#### Camera switching failure <a href="#camera-switch-fails" id="camera-switch-fails"></a>

When `cameraSwitch` is set to `true` and the initial camera request fails (common on devices with restricted permissions), the component will automatically retry with `cameraSwitch` disabled. If both attempts fail, an error is emitted. Check the messages `[LocalRecording]` in the browser console.

#### Debug logging

Configure `showLog={true}` en `<facephi-video-provider>` to enable detailed console output. Look for messages with the prefix `[LocalRecorder]` to track the recording lifecycle:

* Engine initialization (resolution, FPS, quality, pipeline selection)
* Recording start (codec, bitrate, frame scheduling method)
* Camera switching events
* Video generation (file size, duration, number of chunks)
* Engine deinitialization

***

## Configuration

The Video Provider component is configured through JSX or JavaScript properties.

{% content-ref url="/pages/3c5ca02bcb8f624cc296dbd130b73e03004409f7" %}
[Properties](/docs.facephi-en/sdks/sdk-web/componentes/video-recording-video-grabacion/propiedades.md)
{% endcontent-ref %}

The Video Provider component will emit events during its lifecycle.

{% content-ref url="/pages/d752bd5a2872f0fc1be33e3091b3a9769d7a1e05" %}
[Events](/docs.facephi-en/sdks/sdk-web/componentes/video-recording-video-grabacion/eventos.md)
{% endcontent-ref %}

Some functions are provided with the component to offer additional utilities.

{% content-ref url="/pages/32a6093c0aaea29173165a5c9ae1e82d8560798b" %}
[Methods](/docs.facephi-en/sdks/sdk-web/componentes/video-recording-video-grabacion/metodos.md)
{% endcontent-ref %}

How to obtain the recorded extraction video after the extraction process.

{% content-ref url="/pages/1ff3be7d970a03d9ddf0fe842deb34eee8a553b2" %}
[Results](/docs.facephi-en/sdks/sdk-web/componentes/video-recording-video-grabacion/resultados.md)
{% endcontent-ref %}

***

#### Benefits of using Video Provider

* Improved performance in video processes.
* Advanced configuration of technical parameters.
* Optimal compatibility with devices and browsers.

***

### When to use Video Provider?

* Whenever you implement VideoID in your application.
* When you need to control or customize the video experience.
* To ensure technical compatibility in diverse environments.

***

### Next steps

See:

* Video Provider usage examples.
* Advanced configuration options.
* Best practices for video processes.