Voice Assistant

Speech Verifier can use AmaniVoiceAssistant to play an instruction before the verification session begins.

Voice guidance is enabled by default in SpeechVerifier.

Voice Source Priority

Speech Verifier resolves the voice source in this order:

setEnableSpeechVoices(false)
        ↓
voice disabled

setEnableSpeechVoices(true)
+ setSpeechVoicesURL(valid URL)
        ↓
custom URL

setEnableSpeechVoices(true)
+ no custom URL
        ↓
AppConfig.generalconfigs.ttsVoices

The rules are:

1. Explicitly disabling voice guidance wins over every other source.
2. A valid custom URL overrides AppConfig.
3. Without a custom URL, the SDK uses generalconfigs.ttsVoices from AppConfig.

Default — AppConfig Voice Source

When the active AppConfig contains generalconfigs.ttsVoices, no additional configuration is required:

let verifier = amani.speechVerifier()
  .setText("I approve the identity verification", 90)

Voice guidance remains enabled and the SDK attempts to prepare the Voice Assistant from AppConfig before binding the verification view.

Disable Voice Guidance

let verifier = amani.speechVerifier()
  .setEnableSpeechVoices(false)
  .setText("I approve the identity verification", 90)

Disabling voice guidance does not disable Speech Verifier recognition. Camera, microphone, and Apple Speech permissions are still required.

Custom Voice URL

Use setSpeechVoicesURL(...) to override the AppConfig URL for the current SpeechVerifier instance:

let verifier = amani.speechVerifier()
  .setEnableSpeechVoices(true)
  .setSpeechVoicesURL(
    "https://example.com/speech-verifier-voices.json"
  )
  .setText("I approve the identity verification", 90)

The URL must use http or https.

Passing nil clears the custom URL:

verifier.setSpeechVoicesURL(nil)

After clearing the custom URL, the normal AppConfig source is used when voice guidance remains enabled.

Voice Payload

The configured URL is consumed by AmaniVoiceAssistant. A typical payload is an array of voice entries:

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

For flows that can begin with different Speech Verifier step types, provide the required keys.

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

Playback Lifecycle

The current iOS behavior is intentionally conservative:

• voice guidance is attempted only once at the beginning of a new Speech Verifier session;
• it is not replayed after a mismatch retry;
• it is not replayed after a timeout retry;
• it is not replayed again when the flow advances to another runtime 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 indefinitely.

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

AppConfig Example

A remote configuration can provide the voice source through generalconfigs.ttsVoices:

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

Direct Core SDK integrations can override it per instance with setSpeechVoicesURL(...).

Complete Example

let verifier = amani.speechVerifier()
  .documentType("XXX_ST_0")
  .setEnableSpeechVoices(true)
  .setSpeechVoicesURL(
    "https://example.com/speech-verifier-voices.json"
  )
  .setText(
    "I approve the identity verification",
    90
  )
  .onSuccess { result in
    print("Speech result:", result)
  }
  .onFailure { reason, attempt in
    print("Speech failure:", reason.rawValue, attempt)
  }

Permissions

Voice playback itself does not replace or remove Speech Verifier permissions.

Speech Verifier still requires:

• camera access;
• microphone access;
• speech-recognition access.

The Voice Assistant is guidance/playback. Speech recognition is a separate part of the verification pipeline.

Failure Behavior

Voice guidance is not a blocking prerequisite for verification. If voice preparation or playback fails, the module clears the unavailable Voice Assistant instance and continues with normal Speech Verifier UI and speech recognition.