ChivoxAI
sign in

/docs

CSharp offline sdk

0.Integration Preparation

Get sample code

Supported operating environment

  • Hardware Configuration：
    CPU：Dual-core 2.0GHz
    Memory：2G RAM
    Hard Drive：The remaining space on the installation disk is greater than 2G

  • Software configuration：
    Operating system: Supports Windows 7 and above.

Authorized account

  • AppKey and SecretKey
  • Developer certificate aiengine.provision

Sdk fils

Download

  • SDK file：aiengine.dll (for Windows)

Integrate SDK in the project

  • Copy the SDK file aiengine.dll to the C# project in the same level directory as the executable program (such as the debug directory);
  • Copy the developer certificate aiengine.provision to the C# project (usually in the assets directory at the same level as the executable program, it is not mandatory, as long as the path written in the code matches the storage path); as shown in the figure below Show:
    C#项目

Overall process

1.Get the activation code

1.1 Function prototype

  • public static native int aiengine_opt(long 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

    string ActiveParameter = "{\"appKey\": \"" + appKey + "\",\"secretKey\": \"" + secretKey + "\",\"userId\":\"" + userId + "\"}";


    byte[] ActiveInfo = new byte[1024];
    char[] strTemp = new char[1024];
    ActiveParameter.CopyTo(0, strTemp, 0, ActiveParameter.Length);

      for (int i = 0; i < strTemp.Length; i++)
          ActiveInfo[i] = Convert.ToByte(strTemp[i]);


    int dataSize = aiengine_opt(m_engine, 6, ActiveInfo, 1024);

    string ActivationInfo = System.Text.Encoding.Default.GetString(ActiveInfo);

    ActivationInfo = ActivationInfo.Substring(0, dataSize);

2.Create an engine

2.1 Function prototype

  • public static native long aiengine_new(String cfg, Object Context);

2.2 Function

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

2.3 Parameter

Argument Description
Cfg Engine related configuration, JSON format, should include appKey, secretKey, provision and other information.
Description of the cfg parameters
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 example

string cfg = "{\"appKey\":\"" + appKey + "\",\"secretKey\": \"" + secretKey + "\", "
	+ "\"provision\": \"XXXXXXXX\",  "
	+ "\"prof\":{\"enable\":0, \"output\":\"log.txt\" }, "
	+ "\"native\": {\"en.word.score\":{\"res\": \"./resource/eng.wrd.g4.P2.N1.0.3\"},"
	+ "\"en.sent.score\":{\"res\": \"./resource/eng.snt.g4.P2.N1.0.4\"}}}";
Console.WriteLine("cfg:" + cfg);

2.5 Return value description

Return Value Description
Return instance pointer Success
NULL Failed, you should check the parameters at this time

2.6 Code sample


 /*Create engine instance*/
string cfg = "{\"appKey\":\"" + appKey + "\",\"secretKey\": \"" + secretKey + "\", "
	+ "\"provision\": \"./assets/aiengine.provision\",  "
	+ "\"prof\":{\"enable\":1, \"output\":\"log.txt\" }, "
	+ "\"native\": {\"en.word.score\":{\"res\": \"./resource/eng.wrd.g4.P2.N1.0.3\"},"
	+ "\"en.sent.score\":{\"res\": \"./resource/eng.snt.g4.P2.N1.0.4\"}}}";
Console.WriteLine("cfg:" + cfg);
if (m_engine == IntPtr.Zero)
{
    m_engine = aiengine_new(cfg);
    if (m_engine == IntPtr.Zero)
    {
        Console.WriteLine("cfg:" + cfg);
        return;
    }
}
Console.WriteLine("engineId:" + m_engine);

3.Make a request

3.1 Function prototype

  • public static native int aiengine_start(long engine, String param, byte[] id, aiengine_callback callback, Object context);

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), request (kernel-related parameters, refer to example 3.3 below).
  • The audio parameters support the following two ways of audio data input

    1.Microphone real-time audio data
    This method is suitable for instant score scenes and supports only one audio format:
    • wav: mono, 16Khz sample rate, 16bite sampling accuracy;

    • 2.Recorded audio files
    This method is suitable for scenes where non-instant score is not immediately available, the time it takes to evaluate audio is related to the length of audio, and the longer the audio, the longer the evaluation time. only one audio format is supported:
    • wav: mono, 16Khz sample rate, 16bite sampling accuracy;
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, refer to 6.receive results
usrdata Callback parameters, passed in at 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 example

 {
	"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 (please refer to 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 Success
-1 Failed, you should call aiengine_stop immediately to get the reason for failure

3.5 Code sample

 string param = "{\"coreProvideType\": \"native\", \"serialNumber\": \"" + serialnumber + "\","
	+ "\"app\": {\"userId\": \"yx_demo\"}, "
	+ "\"audio\": {\"audioType\": \"wav\",\"sampleRate\": 16000,\"channel\": 1,\"sampleBytes\": 2}, "
	+ "\"request\": {\"coreType\": \"en.sent.score\",\"rank\":100,\"precision\":0.5, "
	+ "\"refText\":\"" + EngineText + "\"}}}";            
byte[] parambytes = Encoding.UTF8.GetBytes(param);

rv = aiengine_start(m_engine, parambytes, record_id, _callback, GCHandle.ToIntPtr(GCHandle.Alloc(usrdata, GCHandleType.Normal)));
if (rv != 0)
{
    Console.WriteLine("start aiengine failed");
    return;
}

4.Send audio data

4.1 Function prototype

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

4.2 Function

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

4.3 Parameter

Argument Description
Engine Pointer to engine instance
Data Data corresponding to the action
Size Data size, recommended 320-64000 bytes

4.4 Return value description

Return Value Description
0 Success
-1 Failed, you should call aiengine_stop immediately to get the reason for failure

4.5 Code sample

try
{
	FileStream fs = new FileStream("./audio/sent.wav", FileMode.Open, FileAccess.Read);
    fs.Seek(44, SeekOrigin.Begin); /* skip wav header */
	while ((bytes = fs.Read(buf, 0, buf.Length)) > 0)
    {
        rv = aiengine_feed(m_engine, buf, bytes);
        if (rv != 0)
        {
            Console.WriteLine("feed failed");
            break;
        }
    }
	fs.Close();
    aiengine_stop(m_engine);
}
catch(Exception e)
{
    //Stop();
    aiengine_stop(m_engine);
    Console.WriteLine("aiengine feed failed:"+e);
}

5.Stop request

5.1 Function prototype

  • public static native int aiengine_stop(long engine);

5.2 Function

  • End the current request of the engine, and the result will be returned in the callback function set at aiengine_start

5.3 Parameter

Argument Description
engine Pointer to engine instance

5.4 Return value description

Return Value Description
0 Success
-1 Failed

5.5 Code sample

aiengine_stop(m_engine);

6.Receive the results

6.1 Function prototype

  • public interface aiengine_callback {public abstract int run(byte[] usrdata, byte[] id, int type, byte[] 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 parameter, the usrdata parameter passed in when calling aiengine_start is brought back as it is
id RequestId, corresponding to the unique identifier of the request generated after calling aiengine_start
type The message type returned by the engine, currently supported:
  • AIENGINE_MESSAGE_TYPE_JSON,
  • AIENGINE_MESSAGE_TYPE_BIN (only used when using the speech synthesis kernel)
message Message data returned by the engine
size Message size

6.4 Code sample

private int callback(IntPtr usrdata, string record_id, int type, byte[] message, int size)
{
   if (type == AIENGINE_MESSAGE_TYPE_JSON)
   {
       string userdata = (string)GCHandle.FromIntPtr(usrdata).Target;
	var result = Encoding.UTF8.GetString(message);
       Console.WriteLine(result);  
	var eventArgs = new EvalCallbackEventArgs() { Msg = result };
       RaiseEvent(eventArgs, EvalCallback);
}
   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

  • public static native int aiengine_delete(long engine);

8.2 Function

  • Destroy the engine instance

8.3 Parameter

Argument Description
Engine Pointer to engine instance

8.4 Return value description

Return Value Description
0 Success
-1 Failed

8.5 Calling method description

  • Destroy the engine, it is recommended to call when exiting the application

8.6 Code sample

if (engine != 0){
	AIEngine.aiengine_delete(engine)
	engine = 0;
}

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
Data size Normal
-1 Error

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);

Example of returned data

{
    "version": "aiengine-256-windows_x86_64-2.2.7-20191012101218"
}

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