Verification (On-Device)

The On-Device v1 libraries are currently released as beta.

Speech Verification is also available to run On-Device. This particular solution is targeted at more recent mid to higher end devices.

On-Device Requirements

To run Verification On-Device, a number of assets are required.

Libraries

The SoapBox Labs On-Device solution is available as Shared/Dynamic C++ Libraries that support both IOS & Android ArmV8.

Models

Running Verification On-Device also requires a Models archive.

Licence Key

A valid Licence Key is also required if using in Production. An invalid, expired or missing licence key will result in the libraries defaulting into Evaluation mode.

Getting Started

Permitted Audio

Make sure to review the documentation around Audio Encoding and Best Practices.

Verification Concepts

Familiarise yourself with the concepts of Speech Verification.

Authentication

Review the On-Device Authentication documentation.

Library Overview

Method Signatures

The following are the method signatures available to run Verification On-Device. These are only relevant if you intend to integrate the libraries yourself. Typically we would recommend using one of the available client libraries or sample code examples.

 Method Signatures

const char *Engine_init(const char *path, const char *default_model);

void Engine_cleanup();

const char *Engine_access_status();

const char *Engine_load_model(const char *model_key, const char *locale);

const char *Engine_unload_model(const char *model_key);

const char *Verification_run(char *audio_buf, int len, char *targets[], const char *model_key);

Status Codes

Every call to the On-Device libraries will return the following minimum results.

{
     "results": [],
     "message": "This is a string for success or failure",
     "status_code": 500,
     "status": 1
 }

This should be inspected on every call. If the “status“ is 1, then an issue has occurred processing the request and the “status_code“ and “message“ fields will be populated with a description of the issue that occurred.

Library Integration across Languages

Each development language/framework (C#, C++, Python etc…) has its own way of importing and calling native libraries. For example in Python it is known as “extensions”.
A selection of examples are located below.

Submitting an On-Device Speech Verification Request

Initialising the Engine

The first step required is to initialise the Engine. Initialising the Engines performs some required setup steps and also loads the required Models into memory. This can be done as follows…

C# Example

string init = Engine_init("LOCATION-OF-MODELS-ARCHIVE");

A status message is returned which should be inspected to ensure the Engine initialised correctly.

Submitting Audio

The audio needs to be stored as a byte array. This is language specific.

C# Example

string result = Verification_run(bytes, bytes.Length, targets, "");

If successful, the verification is stored in the “result“ variable.

Sample Code

The following are examples of how to hook up the libraries using a variety of languages. The examples presented here use Dynamic Libraries.

 C# Sample Code

The following code sample is a minimum working example highlighting how to integrate the libraries into a C# environment.

using System;
using System.IO;
using System.Runtime.InteropServices;

namespace SBLOfflineTest {
    class SBL {
    	// import the SBL library and setup native lib method signature hook
        [DllImport("LOCATION-OF-SBL-LIBRARY")]
        public static extern string Engine_init(string x);
        [DllImport("LOCATION-OF-SBL-LIBRARY")]
        public static extern string Engine_access_status();
        [DllImport("LOCATION-OF-SBL-LIBRARY")]
        public static extern string Verification_run(byte[] x, int y, string[] z, string model_key);
        
        // entry point
        static void Main(string[] args) {
        	// set the verification targets.
        	// these are the targets/prompts you would like to search for in the audio file.
        	// in this case we are checking for the target "right" in the audio file
            // add null to denote the end of the array (WIP)
            string[] targets = {"right", null};

            // run business logic
            try {
                // initialise the engine. this is mandatory. 
                // the location of the models archive should be passed as a parameter
                // the engine will initialise and load the models into memory
                string init = Engine_init("LOCATION-OF-MODELS-ARCHIVE");
                Console.WriteLine(init);
                
                // check engine status - optional
                string status = Engine_access_status();
                Console.WriteLine(status);

                // read in the test audio file as a byte array
                string path = @"LOCATION-OF-AUDIO-FILE";
                byte[] bytes = File.ReadAllBytes(path);

                // run the audio verification service, passing the audio byte array 
                // and the list of targets to check for
                Console.WriteLine("Running Verification");
                string result = Verification_run(bytes, bytes.Length, targets, "");
                Console.WriteLine("Result: " + result);
            } catch (Exception e) {
                Console.WriteLine($"An error occurred - '{e}'");
            }
        }
    }
}

Client Libraries

More fully featured Client Libraries are also available.

On-Device Performance

We regularly measure On-Device performance to ensure it remains stable. The results can be viewed here.

Search