ChivoxAI
sign in

/docs

Android sdk

0.Integration preparation

Get sample code(Java)

Get sample code(Kotlin)

Dependency
  • Android API Level >=14 (Android 4.0 above)
  • Java 1.7+
Authorized account
  • AppKey and SecretKey
  • Developer certificate aiengine.provision
SDK file
  • library files：libaiengine.so
  • jar files：chivox_android_sdk_release.jar

Integrate SDK into your project


1. Put the jar file chivox_android_sdk.jar into the directory 'libs' of your project；
2. Put required architecture folders into the directory 'JniLibs' of your project；
3. Put your developer certificate aiengine.provision into the directory 'assets' of your project, as shown in the screenshot below：


4. Note: If you use the code obfuscation function, please fill in the following rules in the proguard-rules.pro file:
-keep public class com.chivox.* {*;}

SDK related permissions

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

Overall process

1. Create Engine

1.1 Function Prototype

  • static void create(Context context, JSONObject cfg, Engine.CreateCallback callback);

1.2 Function

  • Create an engine instance, create a global evaluation engine when the app initials or when needed, and reuse the engine for subsequent evaluation.
  • It is recommended that this interface be called at the program entry point, such as the Application, Activity's onCreate method.

1.3 Parameters

Parameter name Description
context Android.content.Context
cfg Engine configuration, In JSON format, refer to the cfg parameters below for details.
callback Return scores or exceptions.

1.4 Cfg Parameters

Name Type Required Description
appKey string true Chivox authorized AppKey
secretKey string true Chivox authorized secretKey
provision string true Chivox authorized provison path or base64 authorization code.
cloud object true
- server string true Server Address
- connectTimeout int false Network connection timeout(in seconds)
- serverTimeout int false The timeout (in seconds) from stopping the request to receiving results
vad object false Voice Activity Detection module node
- enable int false Default 0.
1: Load vad module.
0: Not load vad module.
- res string true when vad is enabled Vad resource path
- sampleRate int false Audio sampleRate，unit Hz
- strip int false Whether to filter the silent frames in the beginning and end, default value is 1, recommend 0
prof object false Log function node
- enable int false Defult 0.
1, enable log function
0, disable log function
It is recommended to enable it during debug and disable it after official release.
- output String true when prof is enabled. The log file save path.
1.5 Create Engine Sample Code
  //Build configuration information
  JSONObject cfg = new JSONObject();
  cfg.put("appKey", "******");            // set AppKey
  cfg.put("secretKey", "******");        // set SecretKey
  cfg.put("provision", "/path/to/aiengine.provision");    // set Provision file
  { // Vad module, optional
    JSONObject vad = new JSONObject();    
    vad.put("enable", 0);    //vad function
    vad.put("res", "/path/to/vad.bin");        //set vad resource path    
    cfg.put("vad", vad);
  }
  { 
    JSONObject prof = new JSONObject();
    prof.put("enable", 1);
    prof.put("output", "/path/to/agn_prof.log");    
    cfg.put("prof", prof);
  }
  { 
    JSONObject cloud = new JSONObject();
    cloud.put("server", "wss://cloud.chivox.com:443"); 
    cfg.put("cloud", cloud);
  }

  Engine.create(context, cfg, new Engine.CreateCallback() {
   @Override
   public void onSuccess(Engine engine) 
   {
    // successfully created, save the Engine object for use directly by subsequent benchmarks
   }
   @Override
   public void onFail(RetValue err) 
   {
    // Creation failed, see errId and Error analysis for reasons
    Log.e("TAG" , err.errId + ", " + err.error);
   }
  });

2. Launch Evaluation Request

2.1 Function Prototype

  • RetValue start(Context context, AudioSrc audioSrc, StringBuilder tokenId, JSONObject param, EvalResultListener listener);

2.2 Function

  • Launch evaluation request. After calling, stop or cancel need to be called to finish the evaluation progress.

2.3 Parameters

Parameter names Description
context Android.content.Context
audioSrc There are two sources of audio data

1.SDK Built-in Recorder: AudioSrc.InnerRecorder;
In this way, you will use the SDk built-in recoder, and you will get scores almost in real time. It only supports one audio format：
  • wav：channel: 1 、 sampleRate: 16Khz、sampleBytes: 16bite
    PS：To use this mode, you need to configure the recorder. Please refer to 2.6 Recorder Parameters for details.

2.External Recorder: AudioSrc.OuterFeed;
In this way, you need to send audio data from outer recorder to the engine for scoring. If you want to score audio file or use your own audio recorder, please choose this one. Support multiple audio formats：
  • wav/pcm： channel: 1、sampleRate: 16Khz、sampleBytes: 16bits;
    Note：
    1)To ensure the accuracy of the scoring, the 44-byte header needs to be removed from the wav audio file；
    2)The audioType of the pcm file is set to wav;
  • mp3：channel: 1、sampleRate: 16Khz、sampleBytes: 16bits;
  • mp3：channel: 1、sampleRate: 44.1Khz、sampleBytes: 16bits；
  • ogg： channel: 1、sampleRate: 16Khz、sampleBytes: 16bits;
tokenId Used to save the evaluation ID.
If the evaluation progress is successful, tokenId will save the the evaluation ID, which is consistent with the tokenId returned in the evaluation result.
param For details, please refer to 2.5 Evaluation Request Parameters.
listener Evaluation result listener, for details, please refer to5.Receiving results

2.4 Return Value Description

Return value RetValue.errId explain
0 success
other failure
2.5 Evaluation Request Parameters
Name Type Required Description
param object true Evaluation content
- coreProvideType string true Setting "cloud" means using the online evaluation function
- soundIntensityEnable int false Whether to return the volume in real time.
Set 0: Disable;
Set 1: Enable. The volume is returned by the onSoundIntensity interface in 5. Receiving results The field is "sound_intensity", and the value range is 0~100;；
- vad object false Sound detection function
- - vadEnable int false Default 0
1: Enable VAD.
0: Disable the VAD.
- - refDuration int false Default 0
Set how long will the vad be disbaled after recording starts (unit: seconds)
- - speechLowSeek int false Silence sensitivity, 20ms per frame, set N means after N*20ms of silent audio, it would return 2(time to stop engine)
- app object false App related information
- - userId string false User identification.
It is recommended to fill in with real user account, Facilitate troubleshooting.
- audio object true Audio information
- - audioType string true Audio coding format
- - channel int true Number of audio recording channels
- - sampleBytes int true Audio sampling bits
- - sampleRate int true Audio sampling rate
- request object true Evaluation request, different kernels have different parameters, please refer to English Kernel Doc, Chinese Kernel Doc
2.6 Recorder Parameters
Name Type Required Description
audioSrc object true Recording mode
1. AudioSrc.InnerRecorder()，built-in recorder mode. See the example code in 2.7.1 below；
2. AudioSrc.OuterFeed()，external recorder mode. the external recording mode. See the example code in 2.7.2 below；
- recordParam.sampleBytes true true Sampling bits of built-in recorder
- recordParam.sampleRate int true Built-in recorder sampling rate
- recordParam.saveFile file true Recording file save path including the audio name
- recordParam.duration int true Recording duration (unit: ms)
Different kernels have different audio time limit, please refer to English Kernel Doc, Chinese Kernel Doc

2.7 Built-in Recorder sample code

2.7.1 Built in recording mode sample code
// Configure evaluation parameters
JSONObject param = new JSONObject();
try {
  param.put("coreProvideType", "cloud");  
  { // Set the VAD parameter if necessary
    JSONObject vad = new JSONObject();
    vad.put("vadEnable", 1);
    vad.put("refDuration", 10);
    param.put("vad", vad);
  }
  //param.put("soundIntensityEnable", 1);   //Whether to return the volume in real time. The value is 0,1, and the default value is 0. 1, indicating the real-time return volume. 0 means no return.

  { // Set app related information
    JSONObject app = new JSONObject();
    app.put("userId", "this-is-userid");    // It is convenient to check the user's data according to the user ID.
    param.put("app", app);
  }
  { // Set the audio properties, built-in recording mode to support wav, 16bit, 1600 sampling rate of this audio format
    JSONObject audio = new JSONObject();
    audio.put("audioType", "wav");
    audio.put("channel", 1);
    audio.put("sampleBytes", 2);
    audio.put("sampleRate", 16000);
    param.put("audio", audio);
  }
  { // Kernel request parameters
    JSONOjbect request = new JSONObject();
    request.put("coreType", "en.word.score");   //Evaluation kernel, English word kernel
    request.put("accent", 1);   //American or British accent
    request.put("refText", "present");  //Evaluation text
    request.put("rank", 100);  //Scoring system
    request.put("attachAudioUrl", 1);  //Whether to return the audio URL. 1: yes. 0: no.
    param.put("request", request);
  }
} catch(JSONException e) {
  // exception
  return;
}

// Configure recorder options
AudioSrc.InnerRecorder innerRecorder = new AudioSrc.InnerRecorder();
innerRecorder.recordParam.sampleBytes = 2;
innerRecorder.recordParam.sampleRate = 16000;
innerRecorder.recordParam.saveFile = null;    // If you need to save a recording file, set up a file
innerRecorder.recordParam.duration = 3000;    // If you need to stop recording automatically, you can set the recording time.

//Call start to start the evaluation
StringBuilder tokenId = new StringBuilder(); // tokenId - Used to receive the evaluation task ID
RetValue ret = engine.start(context, innerRecorder, tokenId, param, new EvalResultListener() {
  @Override
  void onError(String tokenId, EvalResult result) {
    // Evaluation failed, please check result.errId , result.error Analyze the cause of failure.

  }
  @Override
  void onEvalResult(String tokenId, EvalResult result) {
    // Return to evaluation results
  }
  @Override
  void onBinResult(String tokenId, EvalResult result) {
    // Binary results, the current audio synthesis kernel returns data through this interface
  }
  @Override
  void onVad(String tokenId, EvalResult result) {
    // Real time VAD results are returned when VaD is enabled

  }
  @Override
  void onSoundIntensity(String tokenId, EvalResult result) {
    // Real time sound intensity results, returned with soundintensity enabled
  }
  @Override
  void onOther(String tokenId, EvalResult result) {
    // Reserved expansion interface
  }
});
// Determine whether the start call is successful
if (0 != ret.errId) 
{
  // Call to start failed, please check ret.errId , ret.error Analyze the reasons
  return;
}
2.7.2 External recorder Sample Code

// Configure evaluation parameters
JSONObject param = new JSONObject();
try {
  param.put("coreProvideType", "cloud");    
  { // Set the VAD parameter if necessary
    JSONObject vad = new JSONObject();
    vad.put("vadEnable", 0);
    vad.put("refDuration", 10);
    param.put("vad", vad);
  }
  { // Set app related information
    JSONObject app = new JSONObject();
    app.put("userId", "this-is-userid");    // It is recommended to use the user account to set this parameter to facilitate troubleshooting 
    param.put("app", app);
  }
  { // Set the audio property to match the actual audio
    JSONObject audio = new JSONObject();
    audio.put("audioType", "wav");
    audio.put("channel", 1);
    audio.put("sampleBytes", 2);
    audio.put("sampleRate", 16000);
    param.put("audio", audio);
  }
  { // Kernel request parameters
    JSONOjbect request = new JSONObject();
    request.put("coreType", "en.word.score");   //Evaluation kernel, English word kernel
    request.put("accent", 1);   //English and American distinguishing marks

    request.put("refText", "present");  //Evaluation text

    request.put("rank", 100);  //Scoring system
    request.put("attachAudioUrl", 1);  //Whether to return the audio URL. 1: Back. 0: no return.
    param.put("request", request);
  }
} catch(JSONException e) {
  // exception
  return;
}

// Call start
StringBuilder tokenId = new StringBuilder();    // tokenId - Used to receive the evaluation task ID
RetValue ret = engine.start(context, new AudioSrc.OuterFeed(), tokenId, param, new EvalResultListener() {
  @Override
  void onError(String tokenId, EvalResult result) {
    // Evaluation failed, please check result.errId , result.error Analyze the cause of failure.
    // When you enter here, please call engine.cancel () the interface resets the engine, otherwise it cannot start normally next time.

    engine.cancel();
  }
  @Override
  void onEvalResult(String tokenId, EvalResult result) {
    // Return to evaluation results
  }
  @Override
  void onBinResult(String tokenId, EvalResult result) {
    // Binary results, the current audio synthesis kernel returns data through this interface

  }
  @Override
  void onVad(String tokenId, EvalResult result) {
    // Real time VAD results are returned when VaD is enabled

  }
  @Override
  void onSoundIntensity(String tokenId, EvalResult result) {
    // Real time sound intensity results, returned with soundintensity enabled
  }
  @Override
  void onOther(String tokenId, EvalResult result) {
    // Undefined results
  }
});
if (0 != ret.errId) {
  // Call to start failed, please check ret.errId , ret.error Analyze the reasons

  return;
} 

// Call the feed to pass in audio, which may be tuned many times

ret = engine.feed(data, len);
if (0 != ret.errId) {
  // Call to feed failed
  return;
}

3. Send Audio Data


3.1 Function Prototype

  • RetValue feed(byte[] data, int size);

3.2 Function

  • Only external recorder needs to call this interface to send audio data.

3.3 Parameters

data：Audio data
size：Data length

3.4 Returned Value Description

  • RetValue.errId == 0 indicates the call is successful, otherwise failed.

3.5 Sample code

RetValue ret = engine.feed(buffer, size);
if (0 != ret.errId) {
  // Call feed failed, generally due to the wrong call sequence. Please check ret.errId , ret.error Analyze the reasons
  // It is recommended to call here eval.cancel () cancel evaluation

  return;
}
// Running at this point indicates that the call to the feed is successful

4. Stop Request


4.1 Function Prototype

  • RetValue stop();

4.2 Function

  • End the current evaluation request, After calling, it will enter the stage of waiting for evaluation results.

Note: The stop interface must be called in pairs with the start interface, otherwise the next calling will report an error. If the recording duration is specified when using InnerRecorder mode, the stop interface will be automatically called within SDK, and you don't need to call manually.

4.3 Returned Value Description

  • RetValue.errId == 0 Indicates the call is successful, otherwise failed.

4.4 Sample Code

RetValue ret = aiengine.stop();
if (0 != ret.errId) {
// Call stop failed, please check ret.errId , ret.error Analyze the reasons
Log.i(TAG, "stop_errorid" + ret.errId);
return;
}

5. Receiving results

5.1 Evaluation Result Listener Interface:

-Interface EvalResultListener

It was set in the request listener parameter settings:send request.

//Abnormal evaluation
void onError(Eval eval, EvalResult result);
//Evaluation results
void onEvalResult(Eval eval, EvalResult result);
//Binary results
void onBinResult(Eval eval, EvalResult result);
//VAD test results
void onVad(Eval eval, EvalResult result);
//audio volume 
void onSoundIntensity(Eval eval, EvalResult result);
//Reserved expansion interface
void onOther(String tokenId, EvalResult result);

5.2 Class EvalResult

  • Evaluation result class

Instance Method

  • String tokenId(); Return the evaluation unique ID.

  • boolean isLast(); Return whether it is the final result of this evaluation.

  • String text(); Return the result data when the following EvalResultListener interfaces are called:

void onError(Eval eval, EvalResult result);
void onEvalResult(Eval eval, EvalResult result);
void onVad(Eval eval, EvalResult result);
void onSoundIntensity(Eval eval, EvalResult result);
  • byte[] data(); Return the result data when the following EvalResultListener interface are called:
void onBinResult(Eval eval, EvalResult result);
  • String recFilePath(); Return recording file path if the recording file is saved successfully, otherwise return null.

5.3 Return Result Code Example


  @Override
  void onError(String tokenId, EvalResult result) {
    // Evaluation failed, please check result.errId , result.error Analyze the cause of failure
  }
  @Override
  void onEvalResult(String tokenId, EvalResult result) {
    // Return to evaluation results
    Log.e(TAG, "recordEvalResult" + evalResult);
    Log.e(TAG, "recordEvalResult.recFilePath:" + evalResult.recFilePath());
    Log.e(TAG, "recordEvalResult.text:" + evalResult.text());
  }
  @Override
  void onBinResult(String tokenId, EvalResult result) {
    // Binary results, the current audio synthesis kernel returns data through this interface

  }
  @Override
  void onVad(String tokenId, EvalResult result) {
    // Real time VAD results are returned when VaD is enabled
	// Return result example：{"vad_status": 0, "sound_intensity": 12.0}
	   //vad_status: VAD detection status, values are 0,1,2, state description： 
       //0:vad Start detection, in silent state; 
       //1:vad Recording detected
; 
       //2:vad After the detection, the recording is in mute state again

	   
    }
  @Override
  void onSoundIntensity(String tokenId, EvalResult result) {
    // Real time sound intensity results, returned with soundintensity enabled
  }
  @Override
  void onOther(String tokenId, EvalResult result) {
    // Reserved expansion interface

  }

6.Cancel Request


6.1 Function Prototype

  • void cancel();

6.2 Fuction

  • Cancel the current evaluation request.

Note: if you call cancel() after calling start(), you do not need to call Stop().

6.3 Sample code


// Cancel current evaluation
aiengine.cancel();

7.Destroy Engine


7.1 Function Prototype

  • void destroy();

7.2 Function

  • Destroy engine and Release resources. After the engine is destroyed, it can't be used for evaluation.

Note: It will also be called automatically by the GC when the engine is recycled if you don't call this method manually. However, the timing of the engine recycled is uncertain, so it is recommended to call manually.

7.3 Code Sample


// Destroy engine
aiengine.destroy();

8. Playback Audio


class AudioPlayer

Audio playback class

  • [Static method]
    static AudioPlayer sharedInstance();
    Function: Return singleton of AudioPlayer.
  • [Member method]
    void play(String path, final Listener listener);
    Function：Playback the audio in path. parameter：path - Audio file path;
    listener - Monitoring events;
  • [Member method]
    void cancel();
    Function：Cancel playback.

Sample code

player.play("path/to/file.wav", new AudioPlayer.Listener() {
  void onStarted(AudioPlayer ap) {
    // Start playing events
  }
  void onStopped(AudioPlayer ap) {
    // Stop playing events

  }
  void onError(AudioPlayer ap, String info) {
    // An error occurred

  }
});

9.Other interface

Get SDK version

String sdkVersion = SdkInfo.singleton().commonSdkVersion +"-" + SdkInfo.singleton().version;
       Log.e(TAG, "sdk version:" + sdkVersion);

SDK, API, MCP and Function Calling documentation on this site.