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**


.. code-block:: python
    :linenos:

        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:

.. code-block:: python
    :linenos:

        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.

.. code-block:: python
    :linenos:

        {
              "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.

.. code-block:: python
    :linenos:

    {
      "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.

.. code-block:: python
    :linenos:

        {
          "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"
          }
        }