Skip to main content

Voice Assistant SDK Android

Overview​

The Voice Assistant SDK provides an easy-to-use features for integrating Voice Assistant capabilities into your Android applications. With this SDK, you can initialize voice data, play voice messages, and handle playback callbacks effortlessly.

Build Up​

  • Voice URL: A URL that contains the voices from remote data source
  • Init: Load TTS voice configurations from a remote source.
  • Play Voice: Play voice messages with customizable callbacks for play, stop, and error events.
  • Stop Voice: Stop the playback whenever required.

Integration​

1. Add the SDK Dependency​

Ensure your project is configured to use JitPack as a repository source.

Settings in settings.gradle:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

Dependency in build.gradle:

Replace Tag with the latest appropriate release as 

dependencies {
    implementation 'ai.amani:Android.SDK.AmaniVoiceAssistant:Tag'
}

2. Permissions​

Ensure your app has the necessary permissions for internet access as the SDK fetches remote resources.

<uses-permission android:name="android.permission.INTERNET" />

Usage​

Voice URL​

Voice URL is a string URL given in the SDK init phase to fetch the sounds from the remote data source. You can set this string URL in two ways.

  1. Getting Voice URL From Amani Remote Config: In order to use this feature, AmaniSDK must be integrated in your application. If it is not integrated, you can reach the link to see how to integrate it.
import ai.amani.sdk.Amani

/**
* This function is a function of AmaniSDK. It is used to retrieve remote data to get VoiceURL.
*/
private fun getVoiceURL() {
        Amani.sharedInstance().AppConfig().fetchApplicationConfig(object : AppConfigObserver {
            override fun result(applicationConfig: ResGetConfig?, errorCode: Int?) {
                //Voice URL fetched, you can use it inside init method
                val voiceURL = applicationConfig?.generalConfigs?.ttsVoices
                //...
            }
        })
    }

  1. Creating Manual URL: In order to use this feature, you must create a URL link in accordance with the JSON format below and the URL must be a URL that directly downloads the JSON.
caution

The audio files in the JSON must be in the "voice":"data:audio/mp3;base64 format.

  • Voice URL JSON Format:
[
    {
        "key":"VOICE_ID0",
        "text":"Lütfen kimlik belgenizin ön yüzünü tarayın",
        "voice":"data:audio/mp3;base64,long_base64_string"
    },
    {
        "key":"VOICE_ID1",
        "text":"Lütfen kimlik belgenizin arka yüzünü tarayın",
        "voice":"data:audio/mp3;base64,long_base64_string"
    },
    {
        "key":"VOICE_NFC",
        "text":"Lütfen kimlik belgenizi yaklaştırın, böylece cihazınızın arka kısmına değsin",
        "voice":"data:audio/mp3;base64,long_base64_string"
    },
    {
        "key":"VOICE_SUCCESS",
        "text":"Teşekkür ederiz! Kimlik doğrulama tamamlandı",
        "voice":"data:audio/mp3;base64,long_base64_string"
    },
    {
        "key":"VOICE_SE0",
        "text":"Kaliteli bir selfie çekmek için yüzünüzü kameraya doğru hizalayın, iyi bir ışık kaynağı kullanın, doğal bir ifade takının, cihazınızı sabit tutun ve lensinizin temiz olduğundan emin olun.",
        "voice":"data:audio/mp3;base64,long_base64_string"
    } 
]

Init​

Initialize the SDK by providing a URL to the voice configuration JSON file.

AmaniVoiceAssistant.init(
    url = "VOICE_URL",
    callBack = object : AmaniVAInitCallBack {
        override fun onSuccess(voices: List<TTSVoice>) {
            // Handle success with the list of voices
        }

        override fun onFailure(exception: Exception) {
            // Handle initialization failure
        }
    }
)

Play The Voice​

Play a voice message by providing the context, a key for the voice message, and a callback to handle playback events.

AmaniVoiceAssistant.play(
    context = this@MainActivity,
    key = "VOICE_ID0", //It should be set according to the key value defined in the JSON file.
    callBack = object : AmaniVAPlayerCallBack {
        override fun onPlay() {
            //The voice has been started
        }

        override fun onStop() {
            //The voice has been stopped    
        }

        override fun onFailure(exception: Exception) {
            //An error occurred while playing audio
        }
    }
)

Stop The Voice​

Ensure playback is stopped when the app is paused or as needed.

override fun onPause() {
    super.onPause()
    AmaniVoiceAssistant.stop()
}

Callbacks​

  • AmaniVAInitCallBack: Handles the result of SDK initialization.

    • onSuccess(voices: List<TTSVoice>): Triggered when initialization is successful.
    • onFailure(exception: Exception): Triggered when an error occurs during initialization.

  • AmaniVAPlayerCallBack: Handles playback events.

    • onPlay(): Triggered when playback starts.
    • onStop(): Triggered when playback stops.
    • onFailure(exception: Exception): Triggered when an error occurs during playback.

Example Project​

Refer to the example project for a complete implementation.