Skip to content

SSTAR KWS ALGORITHM USER GUIDE

REVISION HISTORY

Revision No.
Description
 Date
1.0.0
  • Initial release
    		•  05/01/2021
    2.0.0
  • Updated to Version 2.0
    		•  11/29/2022
    2.0.1
  • Remove c++ code in header
    		•  04/11/2023
    2.0.2
  • Modified parameters for multi-keywords and ipu model
    		•  07/14/2023
    2.1.0
  • Added new vad mode; Added support to set keywords in IaaKws_Init
    		•  08/08/2023
    2.1.1
  • Add break duration parameter
    		•  12/14/2023

    1. OVERVIEW

    1.1. Algorithm Introduction

    Keywords Spotting (KWS) is an algorithm that detects whether there are specified wake-up words in the speech stream.

    1.2. Precautions

    The wake-up word can be customized, please contact FAE if necessary.

    2. API INTRODUCTION

    2.1. Function Module API

    API Name Function
    IaaKws_GetBufferSize Get the memory size required to run KWS algorithm.
    IaaKws_Init Initialize KWS algorithm.
    IaaKws_SetConfig Set KWS algorithm parameters.
    IaaKws_ResetConfig Reset KWS algorithm parameters.
    IaaKws_GetConfig Print out KWS algorithm parameters.
    IaaKws_GetInputSamples Get the number of sampling points input by KWS algorithm.
    IaaKws_Run Run KWS algorithm.
    IaaKws_Free Release resource from KWS algorithm.
    IaaKws_setCallbackFunc Callback function of KWS algorithm verification.

    2.2. IaaKws_GetBufferSize

    • Function

      Get the memory size required to run KWS algorithm.

    • Syntax

      int IaaKws_GetBufferSize(void);

    • Parameter

      Parameter Name Description Input/Output

    • Return Value

      Return Value is the memory size required to run KWS algorithm.

    • Dependency

      • Header File: AudioKwsProcess.h

      • Library File: libKWS_LINUX.so/ libKWS_LINUX.a

    • Note

      This interface only returns the memory size required to run KWS algorithm; to apply and release the memory, you need to use other APIs.

    • Example

      N/A.

    2.3. IaaKws_Init

    • Function

      Initialize the memory required to run KWS algorithm.

    • Syntax

      KWS_HANDLE IaaKws_Init(AudioKwsInit_t *kwsInit);

    • Parameter

      Parameter Name Description Input/Output
      kwsInit Pointer to the initialization structure of KWS algorithm. Input

    • Return Value

      Return Value Result
      handle Successful.
      NULL Failed.

    • Dependency

      • Header File: AudioKwsProcess.h

      • Library File: libKWS_LINUX.so/ libKWS_LINUX.a

    • Note

      • KWS algorithm supports 16kHz sampling rate only, and 16bit sampling bitwidth.

    • Example

      N/A.

    2.4. IaaKws_SetConfig

    • Function

      Set KWS algorithm parameter.

    • Syntax

      int IaaKws_SetConfig(KWS_HANDLE handle, AudioKwsConfig_t kwsConfig);

    • Parameter

      Parameter Name Description Input/Output
      handle The handle of KWS algorithm. Input
      kwsConfig The structure of KWS algorithm parameter configuration. Input

    • Return Value

      Return Value Result
      0 Successful.
      Non-Zero Failed. Please refer to Error Code

    • Dependency

      • Header File: AudioKwsProcess.h

      • Library File: libKWS_LINUX.so/ libKWS_LINUX.a

    2.5. IaaKws_ResetConfig

    • Function

      Reset KWS algorithm parameters.

    • Syntax

      int IaaKws_ResetConfig(KWS_HANDLE handle, AudioKwsConfig_t kwsConfig);

    • Parameter

      Parameter Name Description Input/Output
      handle The handle of KWS algorithm. Input
      kwsConfig The structure of KWS algorithm parameter configuration. Input

    • Return Value

      Return Value Result
      0 Successful.
      Non-Zero Failed. Please refer to Error Code

    • Dependency

      • Header File: AudioKwsProcess.h

      • Library File: libKWS_LINUX.so/ libKWS_LINUX.a

    2.6. IaaKws_GetConfig

    • Function

      Print out parameters required by KWS algorithm.

    • Syntax

      int IaaKws_GetConfig(KWS_HANDLE handle);

    • Parameter

      Parameter Name Description Input/Output
      handle The handle of KWS algorithm. Input

    • Return Value

      Return Value Result
      0 Successful.
      Non-Zero Failed. Please refer to Error Code

    • Dependency

      • Header File: AudioKwsProcess.h

      • Library File: libKWS_LINUX.so/ libKWS_LINUX.a

    2.7. IaaKws_GetInputSamples

    • Function

      Get the number of sampling points input by KWS algorithm.

    • Syntax

      int IaaKws_GetInputSamples(KWS_HANDLE handle, int *samples);

    • Parameter

      Parameter Name Description Input/Output
      handle The handle of KWS algorithm. Input
      samples The number of sampling points input by KWS algorithm. Output

    • Return Value

      Return Value Result
      0 Successful.
      Non-Zero Failed. Please refer to Error Code

    • Dependency

      • Header File: AudioKwsProcess.h

      • Library File: libKWS_LINUX.so/ libKWS_LINUX.a

    2.8. IaaKws_Run

    • Function

      Run KWS algorithm.

    • Syntax

      int IaaKws_Run(KWS_HANDLE handle, short *input, int *kwsIndex);

    • Parameter

      Parameter Name Description Input/Output
      handle The handle of KWS algorithm. Input
      input Pointer to input data. Input
      kwsIndex key word index Output

    • Return Value

      Return Value Result
      0 Successful.
      Non-Zero Failed. Please refer to Error Code

    • Dependency

      • Header File: AudioKwsProcess.h

      • Library File: libKWS_LINUX.so/ libKWS_LINUX.a

    • Example

      Please refer to the Demo code

    2.9. IaaKws_Free

    • Function

      Release the resource from KWS algorithm.

    • Syntax

      int IaaKws_Free(KWS_HANDLE handle);

    • Parameter

      Parameter Name Description Input/Output
      handle The handle of KWS algorithm. Input

    • Return Value

      Return Value Result
      0 Successful.
      Non-Zero Failed. Please refer to Error Code

    • Dependency

      • Header File: AudioKwsProcess.h

      • Library File: libKWS_LINUX.so/ libKWS_LINUX.a

    • Note

      • Please call IaaKws_Free before releasing the memory used by KWS algorithm.

    2.10. IaaKws_setCallbackFunc

    • Function

      The callback function of KWS algorithm verification (currently not supported).

    • Syntax

      int IaaKws_setCallbackFunc(int(*log)(const char *szFmt, ...),
                        int(*envSet)(char *key, char *par),
                        int(*envGetString)(char *var, char *buf, unsigned int size),
                        int(*envSave)(void),
                        int(*readUuid)(unsigned long long *u64Uuid));

    • Dependency

      • Header File: AudioKwsProcess.h

      • Library File: libKWS_LINUX.so/ libKWS_LINUX.a

    3. KWS DATA TYPE

    DATA TYPE Definition
    KWS_MAX_FILE_NAME_LEN The maximum length of KWS algorithm file name.
    KWS_MAX_NUM The maximum number of key words of KWS algorithm.
    KWS_MAX_LEN The maximum length of key words of KWS algorithm.
    AudioKwsInit_t Type of KWS algorithm initialization data structure.
    AudioKwsConfig_t Type of KWS algorithm parameter configuration structure.
    KWS_HANDLE Type of KWS algorithm handle.

    3.2. KWS_MAX_FILE_NAME_LEN

    • Description

      Define the maximum length of KWS algorithm file name.

    • Definition

      #define KWS_MAX_FILE_NAME_LEN    (256)

    3.3. KWS_MAX_NUM

    • Description

      The maximum number of key words of KWS algorithm.

    • Definition

      #define KWS_MAX_NUM    (100)

    3.4. KWS_MAX_LEN

    • Description

      The maximum length of key words of KWS algorithm.

    • Definition

      #define KWS_MAX_LEN    (20)

    3.5. AudioKwsInit_t

    • Description

      Define KWS algorithm initialization structure.

    • Definition

      typedef struct{
    int sampleRate;
    int bitWidth;
    int channel;
    int ipuMaxSize;
    int keywordNum;

    char keywords[KWS_MAX_NUM][KWS_MAX_LEN];
    char modelPath[KWS_MAX_FILE_NAME_LEN];
    char graphPath[KWS_MAX_FILE_NAME_LEN];
    char dictPath[KWS_MAX_FILE_NAME_LEN];
}AudioKwsInit_t;

    • Members

      Member Name Description
      sampleRate The sampling rate of speech.
      bitWidth The sampling bitwidth of speech.
      channel The channel number of speech.
      ipuMaxSize IPU max model size
      keywordNum The number of key words.
      keywords The list of key words.
      modelPath The path to model.
      graphPath The path to decoding graph.
      dictPath The path to dictionary.

    • Note

      • The sampling bitwidth only supports 16bit, and the sampling rate only supports 16kHz.

    • Related Data Type and Interface

      IaaKws_Init

    3.6. AudioKwsConfig_t

    • Description

      Define KWS algorithm parameter structure.

    • Definition

      typedef struct{
    int vadMode;
    int breakDuration;
    float skipDuration;
    float vadThreshold;
    float kwsThreshold[KWS_MAX_NUM];
}AudioKwsConfig_t;

    • Members

      Member Name Description
      vadMode VAD mode: 0 indicates energy detection mode, while 1 indicates probability detection mode
      breakDuration Break time between two utterances
      skipDuration Skip detection time.
      vadThreshold The threshold value of sound activity detection. When VAD mode is set to 0, the value range is [-80,0]; when VAD mode is set to 1, the value range is [0,1]
      kwsThreshold The threshold value of keyword detection. The value range is [-50,0]

    • Related Data Type and Interface

      IaaKws_SetConfig

      IaaKws_ResetConfig

    3.7. KWS_HANDLE

    4. Error Codes

    KWS API Error Codes are shown in the following table:

    Error Code Macro Definition Description
    0x00000000 ALGO_KWS_RET_SUCCESS KWS runs successfully.
    0x90000401 ALGO_KWS_RET_INVALID_LICENSE Invalid license.
    0x90000402 ALGO_KWS_RET_INVALID_HANDLE Invalid handle.
    0x90000403 ALGO_KWS_RET_INVALID_SAMPLERATE Invalid sampling rate.
    0x90000404 ALGO_KWS_RET_INVALID_BITWIDTH Invalid sampling bitwidth.
    0x90000405 ALGO_KWS_RET_INVALID_CHANNEL Invalid speech channel.
    0x90000406 ALGO_KWS_RET_INVALID_VAD_MODE Invalid VAD mode.
    0x90000407 ALGO_KWS_RET_INVALID_SKIP_DURATION Invalid skip duration.
    0x90000408 ALGO_KWS_RET_INVALID_KWSTHRESHOLD Invalid KWS threshold value.
    0x90000409 ALGO_KWS_RET_INVALID_VADTHRESHOLD Invalid VAD threshold value.
    0x9000040A ALGO_KWS_RET_INVALID_BREAK_DURATION Invalid break duration