Voice Capture - VoiceID

Introduction

Face Capture is performed with the Voice Component.

This component is responsible for capturing the user's voice and subsequently extracting the corresponding templates. Its main processes are:

• Internal management of the microphone and permissions.

• Input of a certain number of phrases to then read each one in a step.

• Analysis of silences.

• Progress analysis.

• Assistant in the capture processes.

• Generation of the templates with the voice characteristics and scores.

In the section of Simplified Launch the steps necessary for the basic integration of the SDK are detailed. In this section, information is added for launching this component.

Dependency

The specific dependency for the component is:

implementation "com.facephi.androidsdk:voice_component:$version"

Available controllers

Controller	Description
VoiceController	Main voice capture controller

Simplified Launch

Once the SDK has been initialized and a new operation has been created, the component can be launched. Any of its controllers can be used to execute its functionality.

Starting the capture:

val response = SDKController.launch(
    VoiceController(VoiceConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

Basic configuration

To launch the current component, an object must be created VoiceConfigurationData which will be the configuration of the component controller.

The basic configuration required for it is as follows:

VoiceConfigurationData(
  phrases = arrayOf(
            "Your full name and address",
            "Your ID number with letter",
        )
)

The list of phrases that will be shown to the user can be edited.

Receiving the result

The launch will return the information in SdkResult format. It can distinguish between a successful and unsuccessful launch:

when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error}")
    is SdkResult.Success -> response.data
}

Receiving errors

Errors will be returned as a 'VoiceError' object.

List of errors:

• VOC_ACTIVITY_RESULT_MSG_ERROR: The activity result is incorrect

• VOC_APPLICATION_CONTEXT_ERROR: The required application context is null

• VOC_CANCEL_BY_USER: The user has canceled the process

• VOC_CANCEL_LAUNCH: A general SDK cancellation has been performed

• VOC_COMPONENT_LICENSE_ERROR: The component license is not correct

• VOC_EMPTY_LICENSE: The license String is empty

• VOC_FETCH_DATA_ERROR: Error in collecting the result

• VOC_FLOW_ERROR: Error in the flow process

• VOC_INITIALIZATION_ERROR: Initialization error

• VOC_INTERNAL_LICENSE_ERROR: Internal error related to the license

• VOC_MANAGER_NOT_INITIALIZED: The managers are null

• VOC_NO_DATA_ERROR: The input data are null

• VOC_OPERATION_NOT_CREATED: There is no operation in progress

• VOC_PERMISSION_DENIED: The user has rejected the permissions

• VOC_TIMEOUT: Timeout in the process

Receipt of the correct result - data

In the SdkResult.Success part - data, we will have the class VoiceResult.

The fields returned in the result are as follows:

audio recordings

Contains a list of captured audio recordings in ByteArray format.

tokenizedAudios

Contains the list of captured audio recordings in Facephi's tokenized format.

---

Advanced information

This section expands the component information.

Advanced component configuration

To launch the current component, an object must be created VoiceConfigurationData which will be the configuration of the component controller.

Below are all the fields that are part of this class.

• phrases: Indicates the phrase(s) needed to capture..

• vibrationEnabled: Indicates vibration activation when the Widget finishes successfully.

• showTutorial: Indicates whether the component activates the tutorial screen. This view intuitively explains how the capture is performed.

• extractionTimeout: Sets the maximum time the capture can take.

• showDiagnostic: Show diagnostic screens at the end of the process.

• enableQualityCheck: Enables or disables the audio quality check. It is recommended to keep it always enabled.

• showPreviousTip: Shows a screen before launching the capture with information about the process to be performed and a launch button.

---

Component customization

Apart from the changes that can be made at the SDK level (which are explained in the document of SDK Customization), this particular component allows modification of its interface.

Texts

Texts can be customized by adding an XML resource file to the client application and overriding the default values.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- Previous Tip -->
    <string name="voice_widget_tip_message">Speak clearly and loudly.<br/><br/>Make sure you are in a quiet environment.</string>
    <string name="voice_widget_tip_message_alt">Speak clearly and loudly. Make sure you are in a quiet environment.</string>
    <string name="voice_widget_tip_title">Speech recognition</string>
    <string name="voice_widget_tip_button">Continue</string>
    <string name="voice_widget_tip_anim_alt">Animation in which a person appears holding the phone in front of their face and speaking directly to it. Before you begin, if you are using a screen reader, use headphones.</string>
    <!-- Process -->
    <string name="voice_widget_success_message">Recorded recording</string>
    <string name="voice_widget_speech_message">Speak clearly and close to the microphone</string>
    <string name="voice_widget_speech_more_message">Keep talking</string>
    <string name="voice_widget_speech_empty_message" translatable="false"></string>
    <string name="voice_widget_read_message">Say out loud:</string>
    <string name="voice_widget_speech_noisy_message">There is too much background noise, try to go to a quiet environment</string>
    <string name="voice_widget_success_records_message">successful recordings</string>
    <string name="voice_widget_phrase_generic_error_message">Please repeat the phrase.</string>
    <string name="voice_widget_phrase_long_silence_message">Speak for 2 seconds or more.</string>
    <string name="voice_widget_phrase_long_reverberation_message">Too much echo. Try a different environment.</string>
    <string name="voice_widget_quality_check_error_message">Audio quality is insufficient.</string>
    <string name="voice_widget_multiple_speakers_error_message">Background voices detected. Make sure you are in a quiet environment.</string>
    <!-- Diagnostic -->
    <string name="voice_widget_timeout_title">Time exceeded</string>
    <string name="voice_widget_timeout_desc">We were unable to identify you. Please try again.</string>
    <string name="voice_widget_internal_error_title">There was a technical problem</string>
    <string name="voice_widget_internal_error_desc">We apologize. The capture could not be made</string>
    <string name="voice_widget_exit_alert_accept">Accept</string>
    <string name="voice_widget_exit_alert_cancel">Cancel</string>
    <string name="voice_widget_exit_alert_question">Are you sure you want to finish the process?</string>
    <string name="voice_widget_back_button_alt">Back</string>
    <string name="voice_widget_close_button_alt">Close</string>
    <string name="voice_widget_logo_alt">Logo</string>

</resources>

                                                                                    |

Animations

If you want to modify the SDK animations (lottie), you should include the animations with the same name in the application's res/raw/ folder.

voice_anim_enroll_ko.json
voice_anim_enroll_ok.json
voice_anim_enroll_progress.json
voice_anim_intro.json

External views

It is possible to completely modify the component screens while maintaining their functionality and navigation. To do this, the following interfaces must be implemented:

Previous tip screen:

interface IVoicePreviousTipView {
    @Composable
    fun Content(
        onContinue: () -> Unit,
        onClose: () -> Unit
    )
}

Error diagnostic screen:

interface IVoiceErrorDiagnosticView {
    @Composable
    fun Content(
        error: VoiceError,
        onRetry: () -> Unit,
        onClose: () -> Unit,
    )
}

Capture screens:

interface IVoiceEnrollRecordingView {
    @Composable
    fun Content(
        phrase: String,
        numberRecordedPhrases: Int,
        numberTotalPhrases: Int,
        voiceAmplitude: Float,
        recordingProgress: Int,
        onClose: () -> Unit,
    )
}

interface IVoiceEnrollSuccessView {
    @Composable
    fun Content(
        phrase: String,
        numberRecordedPhrases: Int,
        numberTotalPhrases: Int,
        onClose: () -> Unit,
    )
}

interface IVoiceEnrollErrorView {
    @Composable
    fun Content(
        phrase: String,
        numberRecordedPhrases: Int,
        numberTotalPhrases: Int,
        onClose: () -> Unit,
    )
}

Once the classes implementing the interfaces have been created, at component launch the "customViews" parameter can be added so they are used in the SDK.