Managing the SDK and Engine Lifecycle - Android

Introduction

Proper management of the VSDK and its engines is critical to ensure stability, performance, and resource efficiency in your applications. This guide explains how to correctly initialize the VSDK and its engines, use them safely, and release all associated resources when they are no longer needed. Following these procedures helps prevent memory leaks, unexpected crashes, and other runtime issues, providing a solid foundation for building reliable software.

Whether you are integrating the SDK for the first time or maintaining an existing application, this documentation provides clear, step-by-step guidance for managing the full lifecycle of the SDK and its engines.

Before initializing the Vsdk, ensure that all required assets are correctly deployed on the device’s file system and that the Vsdk libraries are properly integrated into your project. These elements are essential for the SDK and its engines to function correctly.
For detailed setup instructions, refer to the following documentation pages:

• Managing Vsdk Assets – explains how to place and configure required assets on the file system.

• Integrating Vsdk Libraries – describes how to include the Vsdk libraries in your project build.

Initializing Vsdk

Before using any engine, you must initialize the Vsdk using the com.vivoka.vsdk.Vsdk.init method. This method loads the configuration file vsdk.json from the file system and initializes all components required by the engines.

public static void init(android.content.Context context, String configPath,
                        androidx.core.util.Consumer<Boolean> onReady)
  throws Exception;

Parameters

• context – A valid Context that persists throughout the application lifecycle. It is strongly recommended to use the Application context rather than an Activity context to avoid memory leaks or unexpected behavior.

• configPath – The file system path to the vsdk.json configuration file.

• onReady – A callback triggered when initialization completes. Receives true if initialization succeeded, false otherwise.

Important Notes

1. The context is essential for the proper functioning of Vsdk, as it is used for resource management, configuration, and runtime operations. If the context becomes invalid (e.g., an Activity context is destroyed), Vsdk may become unusable, potentially causing errors or crashes.

2. To ensure stability, always provide a context that remains valid for the entire lifecycle of the application. Once initialized, the SDK relies on this context for all operations.

3. Initialization is asynchronous – Use the onReady callback to safely start using the engine only after initialization completes.

Initializing engines

Each Vsdk engine must be initialized after the SDK itself has been initialized. The getInstance() method of any engine always returns the same instance, regardless of whether the engine is initialized or released.

The initialization pattern for engines is:

com.vivoka.vsdk.[technology].[sdk].Engine.getInstance().init(androidx.core.util.Consumer<Boolean> onFinish)

com.vivoka.vsdk.asr.csdk.Engine.getInstance().init(success -> {
    if (success) {
        // Engine is ready to use
    } else {
        // Handle initialization failure
    }
});

com.vivoka.vsdk.tts.csdk.Engine.getInstance().init(success -> {
    if (success) {
        // Engine is ready to use
    } else {
        // Handle initialization failure
    }
});

com.vivoka.vsdk.speechenhancement.s2c.Engine.getInstance().init(success -> {
    if (success) {
        // Engine is ready to use
    } else {
        // Handle initialization failure
    }
});

com.vivoka.vsdk.biometrics.idvoice.Engine.getInstance().init(success -> {
    if (success) {
        // Engine is ready to use
    } else {
        // Handle initialization failure
    }
});

com.vivoka.vsdk.biometrics.tssv.Engine.getInstance().init(success -> {
    if (success) {
        // Engine is ready to use
    } else {
        // Handle initialization failure
    }
});

Important Notes

1. VSDK must be initialized first – Engine initialization depends on the VSDK being properly initialized.

2. Initialization is asynchronous – Use the onFinish callback to safely start using the engine only after initialization completes.

3. Single initialization per engine – Each engine should be initialized only once per application lifecycle. Re-initializing an already initialized engine may cause errors or unexpected behavior.

4. Error handling – Always check the onFinish result to handle cases where initialization fails, which could be due to missing resources, invalid configuration, or other runtime issues.

Creating and Releasing Engine resources

If you don’t need any more a resource such as a recognizer, a model, a channel or an enhancer you can release them by calling the remove method in the engine.

Before removing a resource, make sure to stop all pipelines that use that resource.

When calling the get the engine will create the resource it’s the first time. This resource can be released by calling remove. The following table summarizes the resource creation and release methods available for each engine type:

// Get or create recognizer
com.vivoka.vsdk.asr.csdk.Engine.getInstance().getRecognizer("rec", listener);

// Release the recognizer
com.vivoka.vsdk.asr.csdk.Engine.getInstance().removeRecognizer("rec");

// Get or create dynamic model
com.vivoka.vsdk.asr.csdk.Engine.getInstance().getDynamicModel("model");

// Release dynamic model
com.vivoka.vsdk.asr.csdk.Engine.getInstance().removeDynamicModel("model");

// Get or create channel
com.vivoka.vsdk.tts.csdk.Engine.getInstance().getChannel("rec", listener);

// Release the channel
com.vivoka.vsdk.tts.csdk.Engine.getInstance().removeChannel("rec");

// Get or create speech enhancer
com.vivoka.vsdk.speechenhancement.s2c.Engine.getInstance().getSpeechEnhancer("enhancer");

// Release the speech enhancer
com.vivoka.vsdk.speechenhancement.s2c.Engine.getInstance().removeSpeechEnhancer("enhancer");

// Get or create model
com.vivoka.vsdk.biometrics.idvoice.Engine.getInstance().getModel("model", type);

// Release the model
com.vivoka.vsdk.biometrics.idvoice.Engine.getInstance().removeModel("model");

// Get or create authenticator
com.vivoka.vsdk.biometrics.idvoice.Engine.getInstance().getAuthenticator("auth", model, listener);

// Release the authenticator
com.vivoka.vsdk.biometrics.idvoice.Engine.getInstance().removeAuthenticator("auth");

// Get or create identificator
com.vivoka.vsdk.biometrics.idvoice.Engine.getInstance().getIdentificator("ident", model, listener);

// Release the identificator
com.vivoka.vsdk.biometrics.idvoice.Engine.getInstance().removeIdentificator("ident");

// Get or create model
com.vivoka.vsdk.biometrics.tssv.Engine.getInstance().getModel("model", type);

// Release the model
com.vivoka.vsdk.biometrics.tssv.Engine.getInstance().removeModel("model");

// Get or create authenticator
com.vivoka.vsdk.biometrics.tssv.Engine.getInstance().getAuthenticator("auth", model, listener);

// Release the authenticator
com.vivoka.vsdk.biometrics.tssv.Engine.getInstance().removeAuthenticator("auth");

// Get or create identificator
com.vivoka.vsdk.biometrics.tssv.Engine.getInstance().getIdentificator("ident", model, listener);

// Release the identificator
com.vivoka.vsdk.biometrics.tssv.Engine.getInstance().removeIdentificator("ident");

Releasing engines

Before releasing an Engine, make sure that all pipelines that use the engine resources (e.g., recognizers, models, channels, enhancers, …) are stopped.

Releasing an engine automatically releases all resources it manages by calling Engine.Release. However, you can release individual resources earlier if they are no longer needed.

You will need to call Engine.init to use the engine again.

com.vivoka.vsdk.[technology].[sdk].Engine.getInstance().release()

com.vivoka.vsdk.asr.csdk.Engine.getInstance().release();

com.vivoka.vsdk.tts.csdk.Engine.getInstance().release();

com.vivoka.vsdk.speechenhancement.s2c.Engine.getInstance().release();

com.vivoka.vsdk.biometrics.idvoice.Engine.getInstance().release();

com.vivoka.vsdk.biometrics.tssv.Engine.getInstance().release();

Releasing the Vsdk

Properly releasing resources is critical to avoid memory leaks and ensure that your application shuts down cleanly. Both the Vsdk and individual engines provide a release() method.

Calling Vsdk.release() will automatically:

1. Release all initialized engines (if not already released).

2. Free the Vsdk resources and configurations.

3. Render the SDK unusable until re-initialized.

Summary

Before releasing any resource, engine or Vsdk make sure that all the pipelines that uses it are stopped.

You do not need to manually release each engine if they are releasing the Vsdk; Vsdk.release() handles it for you.

Explicitly releasing engines can still be done if you want to free engine resources before releasing the Vsdk.

After Vsdk.release(), no further Vsdk or engine operations should be performed unless the Vsdk is re-initialized.