SSTAR SED ALGORITHM USER GUIDE

---

REVISION HISTORY

Revision No.	Description	Date
1.0.0	Initial release	05/09/2023

---

1. OVERVIEW

1.1. Algorithm Introduction

Sound Event Detection (SED) is an algorithm that detects whether there are corresponding sound events. It currently supports the detection of coughing, children's crying and glasses shattering.

• model introduction

  model	function	input dimensions(w*h)	classes
  sed/sed_tbs.img	babycry detection	1x32768	0：negative 1:babycry
  sed/sed_tbl.img	babycry detection (large model)	1x32768	0：negative 1:babycry
  sed/sed_tcs.img	cough detection	1x32768	0:negative 1:cough
  sed/sed_tcbs.img	cough&babycry detection	1x32768	0:negative 1:cough 2:babycry
  sed/sed_tbgl.img	babycry &glasses detection	1x32768	0：negative 1:babycry 2:glasses

1.2. Precautions

The algorithm works with a sampling rate of 16kHz and an input length of 256 sampling points (16ms).

This algorithm uses a 16kHz sampling rate to train the model. When testing, please play audio with a sampling rate greater than 16kHz.

---

2. API INTRODUCTION

2.1. Function Module API

API Name	Function
IaaSed_GetBufferSize	Get the memory size required to run SED algorithm.
IaaSed_Init	Initialize SED algorithm.
IaaSed_SetConfig	Set SED algorithm parameters.
IaaSed_GetConfig	Print out SED algorithm parameters.
IaaSed_GetInputSamples	Get the length of sampling points input by SED algorithm.
IaaSed_LoadData	Load operating data of SED algorithm.
IaaSed_Run	Run SED algorithm.
IaaSed_Free	Release resource from SED algorithm.
IaaSed_setCallbackFunc	Callback function of SED algorithm verification.

2.2. IaaSed_GetBufferSize

• Function

  Get the memory size required to run SED algorithm.

• Syntax

  int IaaSed_GetBufferSize(void);
  

• Parameter

  Parameter Name	Description	Input/Output

• Return Value

  The return value is the memory size required to run SED algorithm.

• Dependency

  • Header File: AudioSedProcess.h

  • Library File: libSED_LINUX.so/ libSED_LINUX.a

• Note

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

• Example

  N/A.

2.3. IaaSed_Init

• Function

  Initialize the memory required to run SED algorithm.

• Syntax

  SED_HANDLE IaaSed_Init(AudioSedInit_t *sedInit);
  

• Parameter

  Parameter Name	Description	Input/Output
  sedInit	Pointer to the initialization structure of SED algorithm.	Input

• Return Value

  Return Value	Result
  handle	Successful.
  NULL	Failed.

• Dependency

  • Header File: AudioSedProcess.h

  • Library File: libSED_LINUX.so/ libSED_LINUX.a

• Note

  • The SED algorithm only supports 16kHz sampling rate and 16bit sampling width.

• Example

  N/A.

2.4. IaaSed_SetConfig

• Function

  Set parameters of SED algorithm.

• Syntax

  int IaaSed_SetConfig(SED_HANDLE handle, AudioSedConfig_t* sedConfig);
  

• Parameter

  Parameter Name	Description	Input/Output
  handle	The handle of SED algorithm.	Input
  sedConfig	Pointer to the parameter configuration structure of SED algorithm.	Input

• Return Value

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

• Dependency

  • Header File: AudioSedProcess.h

  • Library File: libSED_LINUX.so/ libSED_LINUX.a

2.5. IaaSed_GetConfig

• Function

  Set parameters of SED algorithm.

• Syntax

  int IaaSed_Run(SED_HANDLE handle);
  

• Parameter

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

• Return Value

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

• Dependency

  • Header File: AudioSedProcess.h

  • Library File: libSED_LINUX.so/ libSED_LINUX.a

2.6. IaaSed_GetInputSamples

• Function

  Get the length of the sampling points input by SED algorithm.

• Syntax

  int IaaSed_GetInputSamples(SED_HANDLE handle,int* s32SampleLength);
  

• Parameter

  Parameter Name	Description	Input/Output
  handle	The handle of SED algorithm.	Input
  s32SampleLength	The length of each sampling point.	Output

• Return Value

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

• Dependency

  • Header File: AudioSedProcess.h

  • Library File: libSED_LINUX.so/ libSED_LINUX.a

2.7. IaaSed_LoadData

• Function

  When SED algorithm loads data function, IaaSed_LoadData will continuously obtains data. When the data reaches the detectable threshold, it will return 1, otherwise it will returns 0.

• Syntax

  int IaaSed_LoadData(SED_HANDLE handle, const short *data, int* detectFlag);
  

• Parameter

  Parameter Name	Description	Input/Output
  handle	The handle of SED algorithm.	Input
  input	Pointer to input data.	Input
  detectFlag	Flag showing whether data is ready, 1 means ready.	Output

• Return Value

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

• Dependency

  • Header File: AudioSedProcess.h

  • Library File: libSED_LINUX.so/ libSED_LINUX.a

2.8. IaaSed_Run

• Function

  Run SED algorithm.

• Syntax

  int IaaSed_Run(SED_HANDLE handle, int* eventIndex);
  

• Parameter

  Parameter Name	Description	Input/Output
  handle	The handle of SED algorithm.	Input
  eventIndex	The event category, which bears different meanings depending on the input model. Please refer to Algorithm Introduction	Output

• Return Value

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

• Dependency

  • Header File: AudioSedProcess.h

  • Library File: libSED_LINUX.so/ libSED_LINUX.a

• Example

  Please refer to Demo code.

2.9. IaaSed_Free

• Function

  Release the resource from SED algorithm.

• Syntax

  int IaaSed_Free(SED_HANDLE handle);
  

• Parameter

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

• Return Value

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

• Dependency

  • Header File: AudioSedProcess.h

  • Library File: libSED_LINUX.so/ libSED_LINUX.a

• Note

  • Please call IaaSed_Free before releasing the memory used by SED algorithm.

2.10. IaaSed_setCallbackFunc

• Function

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

• Syntax

  int IaaSed_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: AudioSedProcess.h

  • Library File: libSED_LINUX.so/ libSED_LINUX.a

---

3. SED DATA TYPE

3.1. Definition of Data Type Related to SED Module

Data Type	Definition
AudioSedInit_t	The structure type of SED algorithm initialization data.
AudioSedConfig_t	The structure type of SED algorithm parameter configuration.
AudioSedMode_e	The detection mode of SED algorithm.
SED_HANDLE	The handlle type of SED algorithm.

3.2. AudioSedInit_t

• Description

  Define the structure type of SED algorithm parameter configuration.

• Definition

  typedef struct{
  
      int sampleRate;
  
      int bitWidth;
  
      char modelPath[SED_MAX_FILE_PATH_LEN];
  
  }AudioSedInit_t;
  

• Members

  Member Name	Description
  sampleRate	Audio sampling rate.
  bitWidth	Audio sampling bitwidth.
  modelPath	Detection model path.

• Note

  • The sampling bitwidth only supports 16bit, the sampling rate only supports 16kHz, and the channel only supports single channel. SED_MAX_FILE_PATH_LEN size is 256

• Related Data Type and Interface

  IaaSed_Init

3.3. AudioSedConfig_t

• Description

  Define the parameter structure of SED algorithm.

• Definition

  typedef struct{
      int smoothLength;
      float vadThreshold;
      AudioSedMode_e detectMode;
      float eventThreshold[SED_MAX_EVENT_NUM];
      int minTriggerTimes[SED_MAX_EVENT_NUM];
  }AudioSedConfig_t;
  

• Members

  Member Name	Description
  eventThreshold	Sound event detection threshold, value range [0,1].
  detectMode	Sound event detection mode.
  smoothLength	Smoothing length when detection mode is IAA_ROBUST_MODE.
  minTriggerTimes	IaaSed_Run will return a positive event only when scores surpass threshold for minTriggerTimes times in smoothLength time window, default times is 1

• Note:

  • The SED_MAX_EVENT_NUM value is 2. If sed_tbs.img is loaded, you only need to set the first threshold {0.5, 0}. If sed_tcbs.img is loaded, set {0.5, 0.5}.

• Related Data Type and Interface

  IaaSed_SetConfig

3.4. AudioSedMode_e

• Description

  Define SED algorithm detection mode.

• Definition

  typedef enum{
  
      IAA_SENSTITVE_MODE = 0,
  
      IAA_ROBUST_MODE
  
  }AudioSedMode_e;
  

• Members

  Member Name	Description
  IAA_SENSTITVE_MODE	Sensitive mode, which is more sensitive to sound events.
  IAA_ROBUST_MODE	Stable mode, in which the sound event detection results will be stable. The results will be smoothed when this mode is enabled.

• Related Data Type and Interface

  IaaSed_SetConfig

3.5. SED_HANDLE

• Description

  Define the handle type of SED algorithm.

• Definition

  typedef void* SED_HANDLE;
  

• Members

  Member Name	Description

• Note

  N/A.

• Related Data Type and Interface

  IaaSed_Init

  IaaSed_SetConfig

  IaaSed_GetConfig

  IaaSed_Free

  IaaSed_Run

4. Error Codes

SED API Error Codes are shown in the following table:

Error Code	Macro Definition	Description
0x00000000	ALGO_SED_RET_SUCCESS	SED algorithm runs successfully.
0x80000401	ALGO_SED_RET_INVALID_LICENSE	Invalid license.
0x80000402	ALGO_SED_RET_INVALID_HANDLE	Invalid handle.
0x80000403	ALGO_SED_RET_INVALID_SAMPLERATE	Invalid sampling rate.
0x80000404	ALGO_SED_RET_INVALID_BITWIDTH	Invalid sampling bitwidth.
0x80000405	ALGO_SED_RET_INVALID_MODEL	Invalid model.
0x80000406	ALGO_SED_RET_INVALID_DETECT_MODE	Invalid detection mode.
0x80000407	ALGO_SED_RET_INVALID_THRESHOLD	Invalid detection threshold value.