Version: SNAPSHOT 🚧

Voice Capture

1. Introduction

Voice capture is performed with the Voice Component.

This component handles capturing the user’s voice and extracting the corresponding templates. Its main processes include:

Internal microphone and permission management.
Prompting a series of phrases for the user to read.
Silence detection analysis.
Progress tracking during capture.
Guided assistance throughout the capture process.
Generation of voice templates and quality scores.

Refer to the Quickstart section for basic SDK integration. This section provides details for launching this component.

2. Dependency

Add the component-specific dependency:

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

3. Available Controllers

Controller	Description
VoiceController	Main controller for voice capture

4. Quick Launch

Once the SDK is initialized and a new operation has been created, launch the component:

val response = SDKController.launch(
    VoiceController(
        VoiceConfigurationData(
            phrases = arrayOf(
                "Your full name and address",
                "Your document number with letter"
            )
        )
    )
)

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

5. Basic Configuration

Create a VoiceConfigurationData object with the following field:

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

You can customize the list of phrases to be presented to the user.

6. Receiving the Result

The launch returns an SdkResult. Handle success and error:

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

6.1 Handling Errors

Errors are returned as a VoiceError object. Possible values include:

VOC_ACTIVITY_RESULT_MSG_ERROR: The result of the activity is incorrect.
VOC_APPLICATION_CONTEXT_ERROR: Required application context is null.
VOC_CANCEL_BY_USER: User has cancelled the process.
VOC_CANCEL_LAUNCH: A general cancellation of the SDK has been done.
VOC_COMPONENT_LICENSE_ERROR: The license of the component is not correct.
VOC_EMPTY_LICENSE: License String is empty.
VOC_FETCH_DATA_ERROR: Error in the result collection.
VOC_FLOW_ERROR: Error in the flow process.
VOC_INITIALIZATION_ERROR: Initialisation error.
VOC_INTERNAL_LICENSE_ERROR: Internal error related to the component license
VOC_MANAGER_NOT_INITIALIZED: Managers are nil.
VOC_NO_DATA_ERROR: Input data is null.
VOC_OPERATION_NOT_CREATED: No operation in progress.
VOC_PERMISSION_DENIED: User has denied permissions.
VOC_TIMEOUT: Timeout in the process.

6.2 Handling Success – `data`

On success (SdkResult.Success), you receive a VoiceResult object. It contains:

6.2.1 `audios`

An array of captured audio samples as ByteArray.

6.2.2 `tokenizedAudios`

An array of tokenized audio samples.

7. Advanced Information

This section provides advanced configuration options for the Voice Component.

7.1 Advanced Component Configuration

All fields of VoiceConfigurationData:

phrases: Array of phrases to be captured.
vibrationEnabled: Enable vibration feedback when the capture completes.
showTutorial: Display a tutorial screen explaining the capture process.
extractionTimeout: Maximum duration (ms) for voice capture.
showDiagnostic: Show diagnostic screens at the end of the process.
enableQualityCheck: Enable or disable audio quality checks (recommended enabled).
showPreviousTip: Show a pre-capture tip screen with instructions and a start button.

8. Component Customization

Beyond SDK-level settings (see Advanced Settings), this component allows interface customization.

8.1 Texts

Override default texts by including an XML file in your app:

<!-- Previous Tip -->
    <string name="voice_component_tip_message">Speak clearly and loudly. &lt;br&gt;&lt;br&gt; Make sure you are in a quiet environment.</string>
    <string name="voice_component_tip_title">Speech recognition</string>
    <string name="voice_component_tip_button">Continue</string>
    <!-- Process -->
    <string name="voice_component_success_message">Recorded recording</string>
    <string name="voice_component_speech_message">Without pressing anything, he speaks clearly and close to the microphone</string>
    <string name="voice_component_speech_more_message">Keep talking</string>
    <string name="voice_component_speech_empty_message" translatable="false"></string>
    <string name="voice_component_read_message">Say out loud:</string>
    <string name="voice_component_speech_noisy_message">There is too much background noise, try to go to a quiet environment</string>
    <string name="voice_component_success_records_message">successful recordings</string>
    <!-- Diagnostic -->
    <string name="voice_component_timeout_title">Time exceeded</string>
    <string name="voice_component_timeout_desc">We were unable to identify you. Please try again.</string>
    <string name="voice_component_internal_error_title">There was a technical problem</string>
    <string name="voice_component_internal_error_desc">We apologize. The capture could not be made</string>

8.2 Animations

Override Lottie animations by including files in res/raw/ with the same names:

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

8.3 External Views

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

Previous tip screen:

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

Error diagnosis screen:

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

Enroll 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 that implement the interfaces have been created, the "customViews" parameter can be added at component launch to be used in the SDK.

9. Logs

Filter console logs for this component with: "VOICE:"

1. Introduction​

2. Dependency​

3. Available Controllers​

4. Quick Launch​

5. Basic Configuration​

6. Receiving the Result​

6.1 Handling Errors​

6.2 Handling Success – data​

6.2.1 audios​

6.2.2 tokenizedAudios​

7. Advanced Information​

7.1 Advanced Component Configuration​

8. Component Customization​

8.1 Texts​

8.2 Animations​

8.3 External Views​

9. Logs​