pubspec.yaml

0.Integration preparation

Get sample code

Supported platforms

• Android API Level >=14 (Android 4.0 above)
• iOS 6.0 and above

Authorized account

• AppKey and SecretKey
• Developer certificate aiengine.provision

Import SDK

• Local Import
  Flutter SDK download

# pubspec.yaml
  dependencies:
    chivox_aiengine:
        path: ***    # Flutter sdk path

Overall process

1.Create Engine

1.1 Function Prototype

• static Future create(String cfg)

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
cfg	Engine configuration, In JSON format, refer to the cfg parameters below for details.

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

    Map cfg = {
      "appKey": appKey,
      "secretKey": secretKey,
      "provision": provisionB64,
      "cloud": {"server": "wss://cloud.chivox.com:443"}
    };
    try {
      _engine = await ChivoxAiengine.create(json.encode(cfg));
    } on PlatformException catch (e) {
      print(e.code);
      print(e.message);
      return;
    }

2. Request

2.1 Function Prototype

• Future start(Map<String, dynamic> audioSrc, String param, ChivoxAiengineResultListener 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
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;
param	For details, please refer to 2.4 Evaluation Request Parameters.
listener	Evaluation result listener, for details, please refer to 5.Receiving results

2.4 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.5 Recorder Parameters

Name	Type	Required	Description
audioSrc	object	true	Recording mode 1. AudioSrc.InnerRecorder()，built-in recorder mode. 2. AudioSrc.OuterFeed()，external recorder mode.
- 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.6 Sample code

Built in recording mode sample code

    var audioSrc = {
      "srcType": "innerRecorder",
      "innerRecorderParam": {
        "duration": 20000,
        "channel": 1,
        "sampleBytes": 2,
        "sampleRate": 16000,
      },
    };
    var param = '''{
      "soundIntensityEnable": 0,
      "coreProvideType": "cloud",
      "app": {
        "userId": "flutter-test-user"
      },
      "vad": {
        "vadEnable": 0,
        "refDuration": 2,
        "speechLowSeek": 50
      },
      "audio": {
        "audioType": "wav",
        "sampleRate": 16000,
        "sampleBytes": 2, 
        "channel": 1
      },
      "request": {
        "rank": 100,
        "refText": "I want to know the past and present of Hong Kong.",
        "coreType": "en.sent.score",
        "attachAudioUrl": 1
      }
}''';

    try {
      await _engine!.start(
          audioSrc,
          param,
          ChivoxAiengineResultListener(
              onEvalResult: (ChivoxAiengineResult result) {
            print(result.tokenId);
            print(result.text);
          }, onBinaryResult: (result) {
            // code
          }, onError: (result) {
            // code
          }, onVad: (result) {
            // code
          }, onSoundIntensity: (result) {
            // code
          }, onOther: (result) {
            // code
          }));
    } on PlatformException catch (e) {
      print(e.code);
      print(e.message);
      return;
    }

3.Send Audio Data

3.1 Function Prototype

• Future feed(Uint8List bytes, int length)

3.2 Function

• The Built-in recorder mode needs to call this function to send audio data.
  

3.3 Parameters

bytes： Audio data
length： Data length

3.4 Sample code

    try {
      await _engine!.feed(Uint8List(4096), 4096);
    } on PlatformException catch (e) {
      print(e.code);
      print(e.message);
      return;
    }

4. Stop Request

4.1 Function Prototype

• Future stop()

4.2 Function

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

Note: The stop() method must be called in pairs with the start() method that sends the request, otherwise the next start() will report an error. If the recording duration is specified when using the built-in recorder , stop() will be automatically called in the SDK when the recording duration reaches, and you may not need to call manually.

4.3 Sample Code

        try {
          await _engine!.stop();
        } on PlatformException catch (e) {
          print(e.code);
          print(e.message);
          return;
        }

5. Receiving results

5. ChivoxAiengineResultListener

• It is set in the request listener parameter settings: 2.Request

  //Evaluation results
  void Function(ChivoxAiengineResult result) onEvalResult = (result) {};

  //Abnormal evaluation
  void Function(ChivoxAiengineResult result) onError = (result) {};

  //VAD test results
  void Function(ChivoxAiengineResult result) onVad = (result) {};

  //audio volume
  void Function(ChivoxAiengineResult result) onSoundIntensity = (result) {};

  //Reserved expansion interface
  void Function(ChivoxAiengineResult result) onOther = (result) {};
  

6. Cancel Request

6.1 Function Prototype

• Future cancel()

6.2 Function

• Cancel the current evaluation request.
  

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

6.3 Sample code

    try {
      await _engine!.cancel();
    } on PlatformException catch (e) {
      print(e.code);
      print(e.message);
      return;
    }

7.Destroy Engine

7.1 Function Prototype

• Future destroy()

7.2 Function

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

Note: You need to call destroy manually

7.3 Sample code

    try {
      await _engine!.destroy();
    } on PlatformException catch (e) {
      print(e.code);
      print(e.message);
      return;
    }