ChivoxAI
sign in

/docs

C offline sdk

0.Integration preparation

Get sample code

Supported operating environment

  • Windows 7 and above
  • Linux (glibc minimum version 2.12)
  • Mac

Authorized account

  • AppKey
  • SecretKey

Sdk files

Download

  • Interface file：aiengine.h
  • Library file
    aiengine.dll
    libaiengine.so

Integrate SDK in the project

  • Copy the SDK aiengine.dll to the syspath directory of the C/C++ project (e.g. the root of the project);
  • Copy the developer certificate aiengine.provision to the C/C++ project's assets directory; As shown in the figure below：

Overall process

1.Get the activation code

1.1 Function prototype

  • struct aiengine * aiengine_opt(IntPtr engine, int opt, byte[] data, int size);

1.2 Function

  • Extend the operation, get the activation code, and when the function is called, the device needs to be networked (note that this will consume the license)

  • The resulting activation code (the number of the serialNumber field in the data is returned below),
    It is recommended to save to the local, and then when the evaluation module is started, it can be read directly and used without having to network each time to get the activation code.

  • The same device with the same account is activated multiple times, the activation code obtained is the same, only counted as a licence.

  • The acquired activation code is passed in to the engine in the make a request interface

1.3 Parameter inputJson description

Return value Description Description
Appkey Required Chivox authorized AppKey
SecretKey Required Chivox authorized SecretKey
UserId Required User Id

1.4 Returns value sample

  • aiengine_opt
//Acquire the activation code for the first time successfully 
{
	"serialNumber": "XXXX-XXXX-XXXX-XXXX-XXXX",
	"provision": "XXXXXXXXXX",
	"tips": "a new provision for userId XXXXXX"
}
//Not the first time to obtain the activation code successfully 
{
	"serialNumber": "XXXX-XXXX-XXXX-XXXX-XXXX",
	"provision": "XXXXXXXXXX",
	"tips": "deviceId with your userId already exists"
}
//Failed to get activation code 
{
	"error": "getaddrinfo fail"
}

1.5 return value description

Return value Description
The size of the data Getting the activation code successful
Sperror Failed to get the activation code
Null Failed to get the activation code

1.6 Code sample

	char appKey[] = "your appKey";
	char secretKey[] = "your secretKey";
	char userId[256] = "your user id";
	
	char cfg_opt[256] = "\
						{\
						\"appKey\": \"%s\",\
						\"secretKey\": \"%s\",\
						\"userId\": \"%s\"\
						}";

    char activeCodeInfo[1024] = { 0 };
			
    sprintf_s(activeCodeInfo, cfg_opt, appKey, secretKey, userId);

	//Request activation code from server
	int result = aiengine_opt(NULL, 6, activeCodeInfo, sizeof(activeCodeInfo));

	printf("active info: %s\n", activeCodeInfo);

2.Create an engine

2.1 Function prototype

  • struct aiengine * aiengine_new(const char * cfg);

2.2 Function

  • Create an instance of the engine, create a global evaluation engine when the product starts or enters the evaluation module, and subsequent evaluations can reuse the engine. the engine can be reused all the time as long as it is not destroyed.

2.3 Parameter

Argument Description
Cfg Engine-related configuration, JSON format, should include appKey, secretKey, provision and other information.
cfg sample
Name Type Option Description
appKey string required Chivox authorized AppKey
secretKey string required Chivox authorized SecretKey
provision string required The content of the provision field in the activation code obtained in Get activation code.
native object required Score resources and paths offline
- timeout int false The timeout (in seconds) from stopping the request to receiving results
vad object optional Voice activity detection
- enable int optional The default is 0.
1, indicates that voice activity detection is turned on.
0, which means that voice activity detection is turned off.
- res string optional Vad resource path
- sampleRate int optional Audio sample rate in Hz
- strip int optional When passing audio data to the upper layer, whether to cut off the first and last blanks, generally set to 0
（avoid miseversaling）
prof object optional Log functionality
- profEnable int optional The default is 0.
1, indicates that the log function is turned on.
0, indicates that the log function can be turned on when the debug is turned off, and the feature can be turned off when it is online.
- profOutput String optional The log file save path

2.4 Cfg sample

	char cfg[] = "\
		{\
			\"appKey\": \"*************\",\
			\"secretKey\": \"**********************\",\
			\"prof\":{\
			\"enable\": 1,\
			\"output\": \"******log.txt\" },\
			\"provision\": \"aiengine.provision\",\
			\"native\":{\"en.word.score\": {\"res\": \"assets/resource/eval/bin/eng.wrd.g4.P2.N1.0.3\"},\
			\"en.sent.score\" : {\"res\":\"assets/resource/eval/bin/eng.snt.g4.P2.N1.0.4\"},\
			\"en.pred.exam\":{\"res\":\"assets/resource/exam/bin/eng.pred.aux.P2.V5.4\"}}\
		}";

2.5 Return value description

Return value Description
Returns the instance pointer Succeed
NULL Failed, at which point the parameters should be checked

2.6 Code sample

engine = aiengine_new(cfg);

3.Make a request

3.1 Function prototype

  • int aiengine_start(struct aiengine * engine, const char * param, char id[64], aiengine_callback callback, const void * usrdata);

3.2 Parameter

Argument Description
engine Pointer to engine instance
param Start parameters, JSON format.

Includes three parts:
app (app-related information),
audio (audio format parameters, wav, mono only, 16Khz sample rate audio format),
request (kernel-related parameters, see example 3.3 below).)。
  • where audio parameters support audio data input in two ways

    1.Microphone real-time audio data
    This method is suitable for instant fractional scenes

    2.Recorded audio files
    This method is suitable for non-instant score scenes, the evaluation of audio time is related to the length of audio, the longer the audio is the longer the evaluation time.
id RequestId, an array of incoming empty characters before the call, in which the SDK records the unique request ID generated, corresponding to tokenId in the evaluation results
callback The callback function, the scoring results, and the exceptions in the score are all triggered into this callback function, see6.receive results
usrdata Callback parameters, passed in when aiengine_start, can be brought back as is in the callback function

3.3 Evaluation request parameter description

Name Type Option Description
param object required Review the content
- coreProvideType string required Set up "native"
- serialNumber string required The content of the serialNumber field in the activation code obtained in Get activation code.
- soundIntensityEnable int Optional Whether to return the volume in real time, default 0, if set 1, the volume size through 6.Receive the resultsof the onSoundIntensity interface callback,
he parameter is "sound_intensity", the value range 0 to 100;
- vad object optional Sound detection
- - vadEnable int optional The default is 0.
1 indicates that vaD functionality is enabled for this review.
0 indicates that vad is not enabled in this review.
- - refDuration int optional Sets the length of time the audio vad delay takes effect (in seconds),
which is to mask the VAD within seconds of the start of recording
- - speechLowSeek int optional Sensitivity, in 20ms, set N (default 15), indicates that the speech stops after 20 x N milliseconds are determined to be the end
- app object optional App-related information
- - userId string optional End-user identification.
It is recommended to fill in the user Id according to the user account number,
so as to facilitate troubleshooting.
- audio object required Audio information
- - audioType string required Audio encoding format
- - channel int required The number of audio channels
- - sampleBytes int required The number of audio samples
- - sampleRate int required Audio sample rate
- request object required Evaluation requests, different kernel request parameters are different, for details, please refer to Offline Kernel Document

3.4 param sample

 {
	"coreProvideType": "native",   // Required，offline evaluation needs to be configured as "native"
	"serialNumber": "xxxxxx", //Required，Obtained from the interface for obtaining the activation code
    "soundIntensityEnable": 0  //Optional, default 0, that is, no volume value is returned. If set to 1, the volume value is returned. 
	                           //The value is returned by callback, the parameter is "sound_intensity", the value range is 0-100
	"vad": {   //Optional, Sound detection function
        "vadEnable": 0,  //Optional, default 0. Setting 1 means the VAD function is enabled for this evaluation. Setting 0 means that the vad function is not enabled for this evaluation.
        "refDuration": 2, //Optional, set the duration of audio vad delay (unit: seconds), that is, block VAD within a few seconds of the first recording
        "speechLowSeek": 50 //Optional, sensitivity, unit 20ms, set to N, it means that 20*N milliseconds after the stop of speaking is judged to be the end
	},
    "app": {                   // part1: application related information
        "userId": "guest",       // Optional, the user ID in the application
    },
    "audio": {                 // part2: audio format parameters
        "audioType": "wav",    // required, audio encoding format
        "channel": 1,          // required, currently only supports mono, only 1
        "sampleBytes": 2,      // required, the number of bytes per sample, support: 1 (single byte, 8 bits) and 2 (double byte, 16 bits)
        "sampleRate": 16000   // required, the sampling rate must be consistent with the actual audio
    },
    "request": {               // voice service parameters (**see the kernel documentation** for details)
	    "coreType": "en.sent.score", 
        "refText": " I want to know the past and present of Hong Kong.", 
        "accent": 1,
        "rank": 100, 
        "attachAudioUrl": 1, 
    }
}

**Note: Different kernel types can be imported into the request node according to the needs of the product. for details, please refer to Offline Kernel Document

3.4 Return value description

Return value Description
0 Succeed
-1 Failed, at which point the aiengine_stop should be called immediately to get the reason for the failure

3.5 Code sample

	char params[] = "\
		{\
			\"coreProvideType\": \"native\",\
			\"serialNumber\":\"a1f1-49db-ab38-093d-461b\",\
			\"app\": {\
			\"userId\": \"aidemo\"\
			},\
			\"audio\": {\
			\"audioType\": \"wav\",\
			\"sampleRate\": 16000,\
			\"channel\": 1,\
			\"sampleBytes\": 2\
		},\
			\"request\": {\
				\"coreType\": \"en.sent.score\",\
				\"refText\": \"I want to know the past and present of hong kong\"\
			}\
		}";
		
	aiengine_start(engine, params, id, _callback, NULL);

4.Send audio data

4.1 Function prototype

  • int aiengine_feed(struct aiengine * engine, const void * data, int size);

4.2 Function

  • Perform specified actions, such as passing in audio data to the engine (audio data must have removed header information)

4.3 Parameter

Argument Description
Engine The pointer to the engine instance
Data Data corresponding to the action
Size The size of the data

4.4 Return value description

Return value Description
0 Succeed
-1 Fail

4.5 Code sample


file = fopen("data/I know the place very well.wav", "rb");//audio path
while ((bytes = (int)fread(buf, 1, 1024, file))) {
	ret = aiengine_feed(engine, buf, bytes);
	if (ret)
	{
			printf("feed error!");
	}
}

5.Stop the request

5.1 Function prototype

  • int aiengine_stop(struct aiengine * engine);

5.2 Function

  • Ends the engine's current request, and the result is returned in the callback callback function set when the aiengine_start

5.3 Parameter

Argument Description
Engine The pointer to the engine instance

5.4 Return value description

Argument Description
0 Succeed
-1 Fail

5.5 Code sample

aiengine_stop(engine);

6.Receive the results

6.1 Function prototype

  • typedef int (AIENGINE_CALL *aiengine_callback)(const void *usrdata, const char *id, int type, const void *message, int size);

6.2 Function

  • Asynchronous callback interface, scoring results and exceptions in scoring will be triggered in this callback function

Do not do any UI operations, IO operations, complex calculations, and any other operations that may cause blocking or waiting in the callback. If necessary, these operations should be submitted to other threads for completion

6.3 Parameter

Argument Description
usrdata Callback parameters, call aiengine_start when the incoming usrdata parameter is brought back as is
id RequestId, which corresponds to the unique identity of the request generated after the call aiengine_start
type The engine returns the message type, which is currently supported:
  • AIENGINE_MESSAGE_TYPE_JSON,
  • AIENGINE_MESSAGE_TYPE_BIN (ONLY WHEN USING THE SPEECH SYNTHESIS KERNEL)
message The message data returned by the engine
size The size of the message

6.4 Code sample

static int AIENGINE_CALL _callback(const void *usrdata, const char *id, int type, const void *data, int size)
{
printf("%s - %.*s\n", id, size, (char *)data);

GetResult -= 1;

return 0;
}

7.Cancel the request

7.1 Function prototype

  • public static native int aiengine_cancel(long engine);

7.2 Function

  • After this method is called, the current evaluation request is canceled

7.3 Parameters

Argument Description
Engine The pointer to the engine instance

7.4 Return value

Return value Description
0 Succeed
-1 Fail

7.5 Code sample

aiengine_cancel(engine);

8.Destroy the engine

8.1 Function prototype

  • int aiengine_delete(struct aiengine * engine);

8.2 Function

  • Destroy the engine instance

8.3 Parameter

Argument Description
Engine The pointer to the engine instance

8.4 Return value description

Return value Description
0 Succeed
-1 Fail

8.5 Call the method description

  • Destroy the engine, which is recommended to be called when exiting the app.

8.6 Code sample

aiengine_delete(engine);

9.Other interfaces

9.1 Get the sdk version number

9.2 Function prototype

  • public static native int aiengine_opt(long engine, int opt, byte[] data, int size);

9.3 Return value description

Return value Description
The size of the data Normal
-1 Mistake

9.4 Code sample

byte[]version = new byte[512];
int ret = AIEngine.aiengine_opt( 0, AIEngine.AIENGINE_OPT_GET_VERSION, version, 512 );
String sdkversion = new String(version,0, ret);
Returns an example of the data
{
    "version": "aiengine-256-windows_x86_64-2.2.7-20191012101218"
}

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