ChivoxAI
sign in

/docs

C sdk

0.Integration preparation

Get sample code

Supported operating environment

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

Authorized account

  • AppKey and SecretKey
  • Developer certificate aineine.provision

SDK FILES

Download

  • Interface file：aiengine.h
  • Library file
    aiengine.dll (for Windows)
    libaiengine.so (for linux/Mac)

Server address

  • wss://cloud.chivox.com:443

Integrate SDK in the project

  • Copying the SDK file aiengine.dll/libaiengine.so copy to the C/C++ project in the same level as the executable directory (e.g. debug directory);
  • Copy the developer certificate aiengine.provision to the C/C++ project (usually in the assets directory of the same level of the executable program, not mandatory, as long as the path written in the code matches the storage path); As shown in the figure below：

Overall process

1. Create an engine

Function prototype

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

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.

Parameter:

Argument Description
cfg Engine-related configuration, JSON format, should include appKey, secretKey, provision and other information.

Cfg sample

 {
    "appKey": "**********", //Required
    "secretKey": "a3bed5523bbc020cf4a****", //Required
    "provision": "path-of-provision-profile",//Required, development certificate storage path
    "cloud": {
		"server": "wss://cloud.chivox.com:443", // required, cloud service address
		"connectTimeout": 20, //Optional, the default is 20s, the timeout period for establishing a network connection, the time is calculated from when the interface is called
		"serverTimeout": 60 //Optional, the default is 60s, the response timeout time, the time starts from stopping the engine
    },
	"vad": {//Optional, voice activity detection
		"enable": 1, //Optional, default 0. Set to 1 means that the engine created this time loads the voice activity detection function module. Setting it to 0 means that the engine created this time does not load the voice activity detection function.
		"res": "./assets/vad.0.12.bin", //optional, vad resource path
		"sampleRate": 16000, //optional, audio sampling rate, unit is Hz
		"strip": 0 //Optional, whether to cut off the leading and trailing blanks when transmitting the audio data to the upper layer, generally set to 0
	},
    "prof": {//Debug function, optional
        "enable": 0, //Debugging switch, disabled by default. Generally open during development and debugging stage, it is recommended to close before the product goes online
        "output": "log-file-path" //If the debugging function is enabled, it must be selected, the debug log path, after configuration, the log information will be output to this directory
    }
}

Return value description

Return value Description
returns the instance pointer succeed
RETURN TO NULL failed, at which point the parameters should be checked

Create engine sample code 

//AIEngine_new Config
char cfg[] = "\
	{\
	 \"appKey\": \"153561523900002b\",\
	 \"secretKey\": \"d25f8d296d29888e71707056f3ee0858\",\
	      \"prof\":{\
              \"enable\": 0,\
              \"output\": \"log.txt\" },\
	 \"provision\": \"assets/aiengine.provision\",\
	 \"cloud\": {\
			\"server\": \"wss://cloud.chivox.com:443\"\
			}\
	 }";
engine = aiengine_new(cfg);
	if (engine){
		printf("Engine Created Success\n");
	}
	else
	{
		printf("Engine Created Failed\n");
		return -1;
	}

2.Make a request

Function prototype

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

Function

  • start this request

Parameter:

Argument Description
engine Pointer to engine instance
param Startup parameter, JSON format.
Includes three parts: app (application-related information), audio (audio format parameters), request (kernel-related parameters).
  • The audio parameters support the following two ways of audio data input

    **1. Real-time microphone audio data; **
    This method is suitable for instant score scenarios. Only one audio format is supported:
    • wav: mono, 16Khz sampling rate, 16bite sampling accuracy;

    • **2. Recorded Good audio files; **
    This method is suitable for scenarios where scores are not instantaneously given. The time consumed for evaluating audio is related to the audio duration. The longer the audio, the longer the evaluation time. Support multiple audio formats:
    • wav: mono, 16Khz sampling rate, 16bite sampling accuracy;
      Note：
      1)To ensure scoring accuracy,wav audio files need to remove 44 bytes header;
      2) pcm file audioType set to wav;
    • mp3: single channel, 16kHz sampling rate, 16bite sampling accuracy;
    • mp3: mono, 44.1kHz sample rate, 16bite sampling accuracy;
    • ogg: single channel, 16kHz sampling rate, 16bite sampling accuracy;
id requestId, pass in an empty character array before the call, after the call, the SDK will record the unique request ID generated in it, which corresponds to the tokenId in the evaluation result
callback Callback function, scoring results and exceptions in scoring will be triggered in this callback function
usrdata Callback parameters, passed in at aiengine_start, can be brought back as-is in the callback function

Evaluation request parameter description

Name Type Option Description
param object required Review the content
- coreProvideType string required Set up "cloud"
- soundIntensityEnable int optional Whether to return the volume in real time, default 0, if set 1, the volume size through5.Receive the results of the onSoundIntensity interface callback,
the 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 Kernel-related parameters, different kernel request parameters are different, please refer to English Kernel Doc, Chinese Kernel Doc

Param sample

 {
	"coreProvideType": "cloud", // Required, online evaluation needs to be configured as "cloud"
	"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": 1, //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": 3, //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": {// part3: voice service parameters (**see the kernel documentation** for details)
       ......
    }
}

**Note: Different kernel types can be imported into the request node according to the needs of the product. For details, please refer to English Kernel Doc, Chinese Kernel Doc

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

Code sample

char params[] = "\
		{\
		 \"coreProvideType\": \"cloud\",\
		 \"app\": {\
			  \"userId\": \"aidemo\"\
			},\
		 \"audio\": {\
			  \"audioType\": \"wav\",\
			  \"sampleRate\": 16000,\
			  \"channel\": 1,\
			  \"sampleBytes\": 2\
			},\
		 \"request\": {\
			  \"coreType\": \"en.sent.score\",\
			  \"refText\": \"Hello world!\",\
			  \"rank\": 100,\
			  \"attachAudioUrl\": 1\
		 }\
		}";
	aiengine_start(engine, params, id, _callback, 0);

3.Send audio data

Function prototype

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

Function

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

Parameter：

Argument Description
engine the pointer to the engine instance
data data corresponding to the action
size the size of the data

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

Code sample

  • Microphone real-time audio data
//micro callback function
static DWORD CALLBACK MicCallback(HWAVEIN hwavein, UINT uMsg, DWORD dwInstance, DWORD dwParam1, DWORD dwParam2)
{
       switch(uMsg)
       {
           case WIM_OPEN:
              break;
 
           case WIM_DATA:
               aiengine_feed(engine, ((PWAVEHDR)dwParam1)->lpData, ((PWAVEHDR)dwParam1)->dwBytesRecorded);   //feed audio data
	        fwrite(((PWAVEHDR)dwParam1)->lpData, 1, ((PWAVEHDR)dwParam1)->dwBytesRecorded, fp);  //audio write to file 
               if(isContiuneRec){
				waveInAddBuffer (hwavein, (PWAVEHDR) dwParam1, sizeof (WAVEHDR)) ;
			}
               break;
 
           case WIM_CLOSE:
               break;
           default:
               break;
       }
       return 0;
   }

4.Stop the request

Function prototype

  • int aiengine_stop(struct aiengine * engine);

Function

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

Parameter：

Argument Description
engine the pointer to the engine instance

Return value description

Argument Description
0 succeed
-1 fail

Stop the engine sample code

  • Microphone real-time audio data
error = waveInStart(hWaveIn);//start recording  
	if (error != MMSYSERR_NOERROR){
        printf("failed record in [waveInStart]\n");
        return -1;
    }
	
	Sleep(i*1000);//wait record
	
	waveInStop(hWaveIn);//stop record
	isContiuneRec = false;
	printf("\stop record\n");

	fclose(fp);	
	aiengine_stop(engine);
	printf("\n aiengine_stop.\n");

5. Receive the result

Function prototype

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

Function

  • Asynchronous callback interfaces, scoring results, and exceptions in scoring are triggered into this callback function

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

note

  • CALLBACKS MUST NOT DO ANY UI OPERATIONS, IO OPERATIONS, COMPLEX CALCULATIONS, AND ANY OTHER OPERATIONS THAT MAY CAUSE BLOCKING OR WAITING, WHICH SHOULD BE SUBMITTED TO OTHER THREADS IF NECESSARY.

Call the method description

after the engine stops, the scoring results are obtained in the method.

Code sample

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

ReleaseSemaphore(hsem, 1, NULL);
return 0;
}

6. Destroy the engine

Function prototype

  • int aiengine_delete(struct aiengine * engine);

Function

  • Destroy the engine instance

Parameter：

Argument Description
engine the pointer to the engine instance

Return value description

Return value Description
0 succeed
-1 fail

Call the method description

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

Code sample

	waveInClose(hWaveIn);

	WaitForSingleObject(hsem, INFINITE);//wait signal

	CloseHandle(hsem);
	aiengine_delete(engine);
	system("PAUSE");

7.Other interfaces

Get the sdk version number

Function prototype

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

Function

  • Extend the operation.

Return value description

Return value Description
the size of the data normal
-1 mistake

Get the version number sample code

char version[512] = {0};
aiengine_opt(NULL, AIENGINE_OPT_GET_VERSION, version, sizeof(version));

Returns an example of the data

  • AIENGINE_OPT_GET_VERSION
 {
    	"version": "aiengine-2.y.z-20190819085959"
 }

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