This section contains short examples of what it looks like to use the Voysis Android library and make a query request, along with some information on the callback structure and what all the notifications mean. Note: This is a short reference. Be sure to see the full documentation to get a better understanding of our service.

Callback structure

The Voysis Android library provides a interface so that applications can receive callbacks about important events occurring within the library. Entrypoints to the library allow the application to supply a callback implementation that will receive these events. The full structure of the interface can be referenced at https://github.com/voysis/voysis-android/blob/master/library/src/main/java/com/voysis/events/Callback.kt but an example of typical callbacks an application may receive are:

success: called when a query to a Voysis Voice AI is successful, receiving the details of the response.
failure: called when a query to a Voice AI has failed. The details of the failure are supplied.
recordingStarted: called when the microphone has been opened and audio is being streamed to the Voice AI.
recordingFinished: called when the microphone has been closed.

This is not a comprehensive list of the callbacks the library provides.

Service instantiation and query request

A Service object is instantiated via the ServiceProvider.makeCloud() method by first creating a config object using refreshToken, URL and VAD settings and providing that along with context.

In order to stream audio to a voice AI, an application must invoke the startAudioQuery method on the Service instance. This method is non-blocking and will return immediately. The Callback instance that is supplied when invoking startAudioQuery will receive important query lifecycle events from the library. The API of the Callback interface can be referenced here

What follows is a simplified example of an Android activity that instantiates a Voysis Service and initiates a query. A fully functional app example is available in the Android SDK source tree

class MainActivity : AppCompatActivity(), Callback {

    private val config = DataConfig(isVadEnabled = true, url = URL("INSERT_URL"), refreshToken = "INSERT_TOKEN")
    private val service = ServiceProvider().makeCloud(this, config)
    private var context = hashMapOf<String, Any>()

    fun onClick(){
        service.startAudioQuery(context = context, callback = this)
    }
    
    override fun success(response: StreamResponse) {
        //do something.
    }

    override fun failure(error: VoysisException) {
        //do something.
    }
    
}

Supporting Wakeword

In order to support wakeword in your application, you must first obtain a wakeword model from Voysis. This model must be made available within your application under the name wakeword.tflite at the resource location identified by your SDK configuration implementation. Instantiating a Service that supports wakeword is then a matter of having your configuration implementation return the WAKEWORD enumeration value from its serviceType property. This is best illustrated through an example:

val config = DataConfig(
    isVadEnabled = true,
    url = URL("wss://example.voysis.io/websocketapi"),
    refreshToken = "myRefreshToken",
    userId = theUserId,
    serviceType = ServiceType.WAKEWORD,
    // This specifies a sub-path relative to your application's resources.
    // In this case, your wakeword model should be placed in
    // src/main/assets/models/wakeword.tflite
    resourcePath = "models"
)
val service = ServiceProvider.makeCloud(this, config)
// It is safe to cast the service as a WakewordService due to the config supplied
val wakewordService = service as WakewordService
// Turn on listening for wakeword. This method will return and listening
// continues on a background thread.
wakewordService.startListening(myCallback, emptyMap(), InteractionType.QUERY)
// Listening can be paused at any time..
wakewordService.stopListening()
// ..and restarted
wakewordService.startListening(myCallback, emptyMap(), InteractionType.QUERY)

A fully functional example of an Android activity supporting wakeword can be found in the Android SDK source tree