Voice Assistant

Speech Verifier can play a voice instruction before the verification session begins. Voice guidance is optional and is provided to the verifier through a SpeechVerifierVoiceProvider passed to the builder with voiceProvider(_:).

If no voice provider is set, the verification runs without voice guidance.

Voice Provider

A SpeechVerifierVoiceProvider has two closures:

Closure	Description
play(key)	Plays the voice entry for the given key (e.g. VOICE_ST4).
stop()	Stops the current playback.

let voiceProvider = SpeechVerifierVoiceProvider(
  play: { key in
    // Play the audio for `key` with your own player or AmaniVoiceAssistant.
    return try await assistant.play(key: key)
  },
  stop: {
    try await assistant.stop()
  }
)

let verifier = try SpeechVerifier.Builder()
  .session(serverURL: serverURL, token: token)
  .voiceProvider(voiceProvider)
  .build()

Voice Keys

Provide audio for the keys your flow can start with.

Voice key	Runtime step
VOICE_ST0	ID number
VOICE_ST1	Document number
VOICE_ST2	Mother's name
VOICE_ST3	Father's name
VOICE_ST4	Spoken/displayed passphrase

A typical voice payload is an array of entries:

[
  {
    "key": "VOICE_ST4",
    "text": "Read the displayed text aloud",
    "voice": "<base64-audio>"
  }
]

With AmaniUI

When Speech Verifier runs through AmaniUI, the voice provider is created for you from the backend configuration. If the active configuration contains generalconfigs.ttsVoices, AmaniUI uses AmaniVoiceAssistant as the provider; if it is empty, no voice provider is set and the flow runs without voice.

{
  "generalconfigs": {
    "ttsVoices": "https://example.com/speech-verifier-voices.json"
  }
}

No additional code is required.

Playback Lifecycle

• voice guidance is attempted only once at the beginning of a new Speech Verifier session;
• it is not replayed after a mismatch or timeout retry;
• it is not replayed when the flow advances to another step;
• speech recognition starts after the initial voice attempt completes;
• voice loading/playback failures are fail-open: verification continues without voice guidance instead of blocking.

This avoids voice audio interfering with microphone capture during retries and multi-step verification.

Complete Example

import AmaniSpeechVerifier

let verifier = try SpeechVerifier.Builder()
  .session(serverURL: serverURL, token: token)
  .documentType("XXX_ST_0")
  .voiceProvider(voiceProvider)
  .verificationSteps([
    .spokenText([
      SpeechVerifierTextConfiguration(
        text: "I approve the identity verification",
        matchThresholdPercent: 90
      )
    ])
  ])
  .onSuccess { result in
    print("Speech result:", result)
  }
  .onFailure { reason, attempt in
    print("Speech failure:", reason.rawValue, attempt)
  }
  .build()

Permissions

Voice playback does not replace Speech Verifier permissions. Speech Verifier still requires camera, microphone, and speech-recognition access. Voice guidance is playback only; speech recognition is a separate part of the verification pipeline.

Failure Behavior

Voice guidance is not a blocking prerequisite for verification. If playback fails, the module continues with the normal Speech Verifier UI and speech recognition.