For Developers

Kedgi requires the classifiers or detectors to have uniform format to avoid any potential incompatibility. The detector/classifier ought to be saved in archived file format (file extensions include zip, rar, tar only) for better portability and distribution.

The process of Kedgi consists of following steps:

  1. Unzips the archived detector/classifier file

  2. Invokes one thread to run the classifier/detector, and use thread pipeline to capture the output and forward to the frontend

The toy_detector (can be found within this project) examplifies the basic structure of the detector/classifier folder and it has following structure:

toy_detector_1/

  1. detector.py The main entry to the detector program, accepts inputs, load relevant data and generate output (Please Note: The script has to be named as detector.py otherwise kedgi is not able to find your detector file.)

  2. cli_conf.json It lists all the CLI arguments, their usages as well as their default values

  3. settings.json It is the place for extra task related configuration

  4. spec_conf.json It is specific to the configuration of spectrogram visualization

detector.py

Parse input arguments

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    parser = argparse.ArgumentParser(description="Toy Detector Example 1 for Kedgi Application ")
    parser.add_argument('--audio_folder', type=str, default=None,
                        help='path to the folder containing the audio files listed in --input_list. Not relevant if using --hdf5_input')
    parser.add_argument('--output', type=str, default=None,
                        help='the .csv file where the detections will be saved')
    parser.add_argument('--step_size', type=float, default=0.5,
                        help='step size (in seconds) used when ovelapping the spectrograms')
    parser.add_argument('--threshold', type=float, default=0.5,
                        help='minimum score value for a segment to be considered as a detection (ranging from 0 to 1)')
    parser.add_argument('--show_progress', type=bool, default=True,
                        help='Show progress bar and estimated time of completion')
    args = parser.parse_args()

The above code snippet translates the input arguments stated in the cli_conf.json file to the program variables. It is mandatory for every script.

Note: currently the dataset for this toy_detector_1 is available within the same directory. But in real cases, the dataset might be in other locations.

Specifying the right directory path for your files

Example:

1
    spec_config = load_audio_representation(os.path.join(sys.path[0],'spec_conf.json'), name='spectrogram')

The above code snippet reads the input argument from the spec_conf.json. And you could see the use of sys.path[0] here, because the working directory is the directory from where Kedgi app is called (not the detector directory). In other words, you will receive a ‘File not found’ error if you do not specify this parameter because the current script will try to search the spec_conf.json file inside the folder of kedgi app instead of the current folder.

Note: If you want to use any files in the detector folder, please includes sys.path[0] as the prefix to them.

cli_conf.json

It contains the arguments to be parsed in the above script. It has two main properties:

  1. type: tells what the type of file it is,

  2. cli_opts: object. A array-like inputs with all the CLI commands useful for the application. NOTE, --audio_folder and --output are required parameters telling the input dataset and output file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
    {
          "type": "cli_opts",
          "cli_opts": [
            {
              "param": "--audio_folder",
              "default_val": "",
              "description": "path to the folder containing the audio files "
            },
            {
              "param": "--output",
              "default_val": "",
              "description": "the .csv file where the detections will be saved"
            },
            {
              "param": "--threshold",
              "default_val": 0.5,
              "description": "minimum score value for a segment to be considered as a detection (ranging from 0 to 1)"
            },
            {
              "param": "--step_size",
              "default_val": 0.5,
              "description": "step size (in seconds) used when ovelapping the spectrograms"
            }
          ]
    }

settings.json

It contains extra parameters that would be used by the detector. Similarly it requires two properties:

  1. type: tell what the type of file it is,

  2. settings: object. A key-value object.

1
2
3
4
{
  "type": "settings",
  "settings": {}
}

spec_conf.json

This file stores the configuration of spectrogram. It has two entries:

  1. type: indicates the file type,

  2. spectrogram: object. A key-value object has configurations of the spectrogram.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    {
      "type": "spectrogram",
      "spectrogram": {
        "rate": "1000 Hz",
        "window": "0.256 s",
        "step": "0.032 s",
        "freq_min": "0 Hz",
        "freq_max": "500 Hz",
        "window_func": "hamming",
        "type": "MagSpectrogram"
      }
    }