5.11. Config File

Note

The configuration corresponds to the probe version 2.1.4 (2022.10.21 10:53:16 UTC)

5.11.1. General Information

Configuration File

This is the monitor.cfg file received from the archive file via your personal account and located in the directory together with the streamMonitor executable file. A configuration file is intended for the probe settings storage including a tasklist. While controlling the probe, setting tasks for analysis and other actions performed on the server, a configuration file is modified by the probe application. When starting, restarting or in case of unexpected restart, the probe uses the monitor.cfg file to restore the recently saved configurations.

Be aware of the fact that the monitor.cfg file does not include the project settings. Consequently, all trigger notifications settings, system notifications settings (thresholds and triggers), project access settings are not applied to the configuration file. Thresholds settings are contained in the monitor.cfg file; however, when starting the probe, the server-stored settings will be applied.

  • One of the methods of setting tasks to the probe is to modify the monitor.cfg file.

  • One of the methods of transferring settings and backup is to save and copy the monitor.cfg file.

Important

If the probe is managed via browser, all settings and adjustments are applied to the monitor.cfg file. Moreover, the file content will be updated automatically in compliance with the default format of the currently used probe. So, if you are going to set tasks to the probe by editing the monitor.cfg file, always save a backup copy of the file.

Configuration File Editing

Before start editing a configuration file, look through basic information described below:

  1. Minimal set of parameters required for successful start of the probe application is included in the monitor.cfg file contained in the downloaded archive file.

  2. Invalid JSON syntax is the most common reason for errors. It is recommended to validate any data planned to be used.

  3. The monitor.cfg file must be saved as utf-8.

  4. While debugging, save a copy of the monitor.cfg file before start controlling from browser.

  5. To start the probe, setting a simple task list in the monitor.cfg is only required. Other probe settings can be configured in a browser at any time.

Configuration is saved in the format similar to JSON. In addition:

  • C-type comments are supported:
    • Text starting with /* and ending with */ forms a comment block;

    • Text starting with // and till the end of the line is a comment.

  • A trailing comma (after the last value in a data object or in an array) is supported.

5.11.2. File Structure

General Configuration

Contains probe settings and description of a limited number of settings which applied to all tasks.

Configuration from the downloaded archive

A configuration file received from the archive contains probe settings required for successful connection with the server. The file does not contain any information about monitoring tasks.

Configuration from the downloaded archive
 {
   "config":{
     "AppDescription":"My probe name", // probe description
     "server":"https://api.boro.elecard.com",
     //"proxy":"http://192.168.1.2:3128", // proxy to connect with Boro server
   }
 }

General configuration

Below is an example of configuration with all possible settings specified. Having successfully launched the probe, a user added two monitoring tasks using a web-interface.

General configuration
 {
   "config":{
     "allowDownloadPcapDump": false,
     "AppDescription":"My Probe address and description",
     "server":"https://api.boro.elecard.com",
     "proxy":"http://10.192.173.239:3128",
     "defaultBindAddress":"10.10.30.152",
     "epsnrCalc":false,
     "captureThumbnails":false,
     "checkFreeze":true,
     "videoFreezePeriod":5,
     "EITMessages":false,
     "ottAllRenditions":false,
     "checkMasterPlaylist":false,
     "uri":[
       {
         //Task configuration #1
       },
       {
         //Task configuration #2
       }
     ]
   }
 }
  • allowDownloadPcapDump - a logical type, allows/denies downloading of Pcap records. This functionality is disabled by default due to security reasons;

  • AppDescription - a string, text description/name of the probe;

  • server - a string, address of data collection server. The field is set automatically when downloading probe’s archive. It is not recommended to change the field value;

  • proxy - a string, specifies proxy server for communication of Boro-probe with the server. Proxy server for analyzed data receiving is configured separately in a task configuration;

  • defaultBindAddress - a string, defines NIC IP as a default IP address. The probe will receive data through a specified interface if another value is not specified in a task configuration;

  • epsnrCalc - a logical type, enables/disables EPSNR calculation 1. Applied to all analyzed streams if another value is not specified in a task configuration. Disabled by default;

  • captureThumbnails - a logical type, enables/disables the thumbnail capturing. Applied to all analyzed streams if another value is not specified in a task configuration. Disabled by default;

  • checkFreeze - a logical type, enables/disables video freeze analysis. Applied to all analyzed streams if another value is not specified in a task configuration. Disabled by default;

  • videoFreezePeriod - an integer value, specifies a period in seconds. If scene freeze exceeds the stated period, the Video Freeze Error state is detected. Applied to all analyzed streams if another value is not specified in a task configuration. 0s is set by default;

  • EITMessages - a logical type, enables/disables sending EIT data to the server. Disabled by default. It is not supported by the server;

  • ottAllRenditions - a logical type, the mode of OTT analysis. Applied to all analyzed streams if another value is not specified in a task configuration:
    true - the analysis mode of all Alternative Renditions of all Variant Streams. The probe analyzes all Alternative Renditions URLs contained in a Master playlist (even if a Rendition is not associated with any Variant Stream). Further, a main task is created as well as subtasks for each Rendition analysis. If the configuration applied to a main task is edited, the probe implements the new settings to all subtasks. The monitor.cfg file includes the main task configurations only;
    false (default) - the “Player” mode. The probe uses a standard algorithm inherent to OTT media players, i.e. the probe downloads and analyzes the Variant Stream with the highest bitrate allowed by the network bandwidth at this time. If a Variant Stream contains media of different types (AUDIO, VIDEO, SUBTITLES), all of them are analyzed, i.e. a main task is created as well as subtasks for each Rendition analysis. If a Variant Stream contains set of Renditions, the default Rendition (DEFAULT=YES) is analyzed. If none of the Renditions is set as default in a group, an arbitrary Rendition URL from this group is used.
  • checkMasterPlaylist - a logical type, enables/disables Master playlist update. Applied to all analyzed streams if another value is not specified in a task configuration. Disabled by default. If enabled, a playlist updates in accordance with the period specified in the masterPlaylistUpdatePeriod setting;

  • uri - an array of objects, defines each task configuration.

Attention

Configuring task by specifying general settings is a deprecated method.
It is advisable to configure tasks using web-interface after launching the probe. In this case, settings will be saved as individual task configurations.

Task Configuration

Contains description of all settings of a particular task. The addr field is required, other fields will be added as the probe is launched. Task settings have priority over corresponding ones in general settings.

Task configuration example
 {
   "taskId":199498,
   "addr":"udp://235.0.0.5:1234",
   "name":"1st Channel",
   "protocol":"udp",
   "iface":"10.10.30.203",
   "closeCaptions":false,
   "proxy":"172.16.1.2:3128",
   "igmpSourceFilter":[
     "10.10.30.5"
   ],
   "ottGreedyVOD":false,
   "DSM-CC":{
     "enable":true,
     "additional_tag":[
       5
     ]
   },
   "freeze":{
     "enable":true,
     "threshold":5,
     "forceCheck":60
   },
   "ottAllRenditions":false,
   "checkMasterPlaylist":false,
   "thumbnail":{
     "enable":true,
     "default_period":10,
     "freeze_period":"startEnd",
     "scte35_period":1,
     "storeThumbLocal":false,
     "keepAspectRatio":false,
     "jpeg_quality":70,
     "resolutions":[
       {
         "width":264,
         "height":148
       },
       {
         "width":468,
         "height":264
       }
     ]
   },
   "record_triggers":{
     "VideoFreeze":{
       "enable":false
     },
     "Scte35":{
       "enable":false
     }
   },
   "audio":{
     "enableAnalysis":true,
     "checkDecodability":true
   },
   "avrgBitrateInterval":10,
   "video":{
     "epsnr":false,
     "DecodabilityMode":"off"
   },
   "usePcr":"auto",
   "srt":{
     "maxListenerRenditions":5,
     "receiveLatency":120,
     "mode":"caller",
     "username":"user",
     "password":"pass",
     "keyLength":"AES-128"
   },
   "cdi":{
       "adapterType":"EFA",
       "protocolType":"AVM",
       "audio":{
           "bitPerSample":16
       },
       "video":{
           "componentsFormat":"Planar",
           "orderFormat":"YUV"
       }
   },
   "thresholdsProfile":{       //The *thresholds* profile
     "eth":{
       "enabled":true,
       "IAT_error":50,
       "IAT_warning":45,
       "MLR_error":8,
       "MLR_warning":1,
       "bitrate_max":15000,
       "bitrate_min":100
     },
     "etr290":{
       "enabled":true,
       "maxPmtInterval":500,
       "maxPatInterval":500,
       "maxPidVAInterval":5000,
       "maxPidInterval":5000,
       "maxPTSInterval":1000,
       "excludeType":[
         "0x86",
         "0x5",
         8191
       ],
       "excludeCCType":[
         "0x86",
         8191
       ],
       "excludeTimestampType":[
         "0x86"
       ]
     },
     "etr290p2":{
       "enabled":true,
       "maxPTSRepetitionPeriod":700,
       "pcrRepetitionTime":40
     },
     "etr290p3":{
       "enabled":true,
       "deliverySystem":"Auto",
       "defIntervals":{
         "defMinInterval":25,
         "defBatInterval":10000,
         "defTotTdtInterval":30000,
         "defNitInterval":{
           "actual":10000,
           "other":10000
         },
         "defSdtInterval":{
           "actual":2000,
           "other":10000
         },
         "defEitInterval":{
           "actual":2000,
           "other":10000
         },
         "defEitSheduleInterval":{
           "actual":10000,
           "other":30000
         }
       }
     },
     "freeze":{
       "interval":5,
       "psnrThreshold":42
     },
     "audio":{
       "silence_threshold":-70,
       "DecodabilityThreshold":50
     },
     "video":{
       "DecodabilityThreshold":50
     },
     "ott":{
       "enabled":false,
       "download_speed_error":100,
       "download_speed_warning":80,
       "actual_bitrate_min":50,
       "actual_bitrate_max":200,
       "identical_playlist_cnt":3,
       "manifest_size":500000,
       "min_profiles":1,
       "check_hls_segments":0,
       "masterPlaylistUpdatePeriod":30,
       "hlsAnalyzeFrom":"default",
       "dashAnalyzeFrom":"default",
       "ottDownloadKey":"auto",
       "Source_only":false,
       "download_period":0,
       "noBodyMethod":"head",
       "regTextBandError":false
     },
     "OttOnEndOfStream":"restart",
     "http_url_params":[
       {
         "key":"key1",
         "value":"val2",
         "force":false,
         "type":"url"
       }
     ],
     "ottCustomTagDetection":{
       "case_sensitive":true,
       "filter":[
         {
           "tag":"DATERANGE",
           "includes":[
             "DURATION"
           ],
           "excludes":[
             "SCTE35-IN"
           ]
         }
       ]
     },
     "bufferCheck":{
       "enable":true,
       "bufferUpperBound":2000,
       "bufferLowerBound":0
     },
     "digitalProgramInsertion":{
       "scte35TagInOttSubs":true,
       "adInsertionMode":"auto",
       "resetStateOnBadSource":"5"
     }
   }
 }
  • taskId - an integer value, a task identifier;

  • addr - a string (array of strings), specifying (a) path(-s) to the analyzed streams. The following prefixes are supported: file://, udp://, rtp://, http://, https://. HLS format is supported as well (URL should end with .m3u or .m3u8);

  • name - a string, the stream name (e.g. a channel name);

  • protocol - a string, specifies a stream (service) protocol forcibly. It has priority over the protocol specified in a task URI. The following variants are supported: file, udp, rtp, http, https, hls;

  • iface - a string, IPv4/IPv6 address of a interface;

  • closeCaptions - a logical type, the field is reserved for future use;

  • proxy - a string, a proxy server for data receipt when analyzing HLS service;

  • igmpSourceFilter - an array of strings, contains IPv4 unicast addresses of sources (for IGMPv3 only);

  • ottGreedyVOD - a logical type, sets the HLS VoD analysis mode:
    true - VoD analysis mode (aggressive download mode). Content is analyzed with maximum possible speed;
    false (default) - “live” analysis, i.e. analyzing speed is equal to a segment playback speed.
  • DSM-CC - an object, describes DSM-CC parsing settings 2:
    • enable - a logical type, enables/disables DSM-CC parsing. Disabled by default;

    • additional_tag - an array of integer values, a list of elementary stream types which should be considered as streams containing DSM-CC data. Empty by default.

  • freeze - an object, containing settings for video freeze detection:
    • enable - a logical type, enabling/disabling video freeze detection. Disabled by default. It has priority over the checkFreeze global setting;

    • threshold - an integer value, specifies a ratio of I frames to P frames. If the ratio exceeds the stated threshold, both neighboring I frames are compared to detect video freeze. 5 is set by default;

    • forceCheck - an integer value, specifies a period in seconds upon which two neighboring I frames are forcibly compared by the probe to detect video freeze. I.e. initial check results are ignored, and a forcible check of the second level is automatically performed. 60 seconds is set by default.

  • ottAllRenditions - a logical type, the mode of OTT analysis. It has priority over the ottAllRenditions global setting:
    true - the analysis mode of all Alternative Renditions of all Variant Streams. The probe analyzes all Alternative Renditions URLs contained in a Master playlist (even if a Rendition is not associated with any Variant Stream). Further, a main task is created as well as subtasks for each Rendition analysis. If the configuration applied to a main task is edited, the probe implements the new settings to all subtasks. The monitor.cfg file includes the main task configurations only;
    false (default) - the “Player” mode. The probe uses a standard algorithm inherent to OTT media players, i.e. the probe downloads and analyzes the Variant Stream with the highest bitrate allowed by the network bandwidth at this time. If a Variant Stream contains media of different types (AUDIO, VIDEO, SUBTITLES), all of them are analyzed, i.e. main task is created as well as subtasks for each Rendition analysis. If a Variant Stream contains set of Renditions, the default Rendition (DEFAULT=YES) is analyzed. If none of the Renditions is set as default in a group, an arbitrary Rendition URL from this group is used.
  • checkMasterPlaylist - a logical type, enables/disables updating of a Master playlist. It has priority over the checkMasterPlaylist global setting. Disabled by default. If enabled, a playlist updates in accordance with the period specified in the masterPlaylistUpdatePeriod setting;

  • thumbnail - an object, containing configurations for the thumbnail capture. Periods have the following action priority (in descending precedence order): scte35_period, freeze_period, default_period:
    • enable - a logical type, enables/disables the thumbnail capturing. Disabled by default. It has priority over the captureThumbnails global setting;

    • default_period - an integer value or a string. An integer value specifies an interval between thumbnail captures in seconds. 0 value disables the thumbnail capturing during the program broadcast. 10 s is set by default. A string specifies an operation mode:
      off - disables the thumbnail capturing;
      allIFrame - the probe will capture thumbnails from each keyframe.
    • freeze_period - an integer value or a string. An integer value specifies an interval between thumbnail captures in seconds. 0 value disables the thumbnail capturing during the video freeze. 10 s is set by default. A string specifies an operation mode:
      off - disables the thumbnail capturing;
      startEnd - capture thumbnails at the beginning and at the end of the event (for the video freeze only);
      allIFrame - the probe will capture thumbnails from each keyframe.
    • scte35_period - an integer value or a string. An integer value specifies an interval between thumbnail captures in seconds. 0 value disables the thumbnail capturing during the Ad display (SCTE35 event). 1 s is set by default. A string specifies an operation mode:
      off - disables the thumbnails capturing;
      allIFrame - the probe will capture thumbnails from each keyframe.
    • storeThumbLocal - a logical type, true - the probe will send Thumbnail events without thumbnails to the server 2. Thumbnails will be saved in the thumb folder next to the executable file. False is set by default;

    • keepAspectRatio - a logical type, true - thumbnails will be captured while keeping the original aspect ratio 2. False is set by default;

    • jpeg_quality - an integer value, specifies jpeg compression quality within the interval from 0 to 100. 70 is set by default.

    • resolutions - an array of objects, describing thumbnails resolution 2:
      • width - an integer value, specifies a thumbnail width in pixels. 160 is set by default;

      • height (optional field) - an integer value, specifies a thumbnail height in pixels. If not specified or 0 is set, height will be calculated automatically to keep the original aspect ratio. 0 is set by default.

  • record_triggers - an object, specifies triggers which are set to start recording automatically:
    • VideoFreeze - record on Video Freeze event. Record includes Pre-buffering period, Record Duration after event detection and, if event has been lasting for a long period, End of State separately;
      • enable - a logical type, enables/disables recording on the Video Freeze event.

    • SCTE35 - record on Ad insertion (SCTE35 event). Record includes Pre-buffering period, Record Duration after event detection and, if event has been lasting for a long period, End of State separately;
      • enable - a logical type, enables/disables recording on the SCTE35 event.

  • audio - an object, containing settings of accompanying sound QoE analysis 3 :
    • enableAnalysis - a logical type (false by default), enables/disables the following measurements:
      1) Program loudness and peak levels of audio signals according to EBU R 128-2011;
      2) Audio silence detection.
    • checkDecodability - a logical type, enables/disables audio decodability estimation (ratio of audio decoder output bitrate to declared bitrate). Disabled by default.

  • avrgBitrateInterval - an integer value, a time interval for average bitrate calculation used by the probe (used for Delay Factor calculation). 10 is set by default. For internal use only. It is not recommended to change the default value;

  • video - an object, containing settings of video QoE analysis:
    • epsnr - a logical type, allows enabling/disabling EPSNR 1 calculation for a particular task. Disabled by default. It has priority over the epsnrCalc global setting;

    • DecodabilityMode - a string, enables/disables video decodability estimation. It compares the number of correctly decoded frames with the declared framerate. Modes:
      off - the metric is disabled;
      lite - the mode performs semantic analysis of an elementary stream without further decoding. Measuring accuracy is approximate, resource consumption is medium. This mode is sufficient to estimate video decodability, but it disregards possible issues occurring inside a frame;
      full - the mode performs full decoding. Measuring accuracy is precise, resource consumption is high. The correctly decoded frame corresponds to the lack of errors.
  • usePcr - a string, sets a time counter to be used for calculating bitrates of streams, analysis of ETR290, etc.
    auto (default mode) - automatic selection (PTS/DTS for OTT and PCR for all other stream types);
    off - use PTS/DTS;
    on - use PCR.
  • srt - an object, containing settings of the SRT protocol analysis:
    • maxListenerRenditions - an integer value, maximum number of connections to one task in listener mode. 5 is set by default;

    • receiveLatency - an integer value, defines the minimum receiver buffering delay before delivering an SRT data packet from the receiving SRT socket to the receiving application, 120 is set by default;

    • mode - a string, a connection mode over the SRT protocol:
      caller (default mode) - in this mode, the probe itself initiates the connection to the SRT stream source;
      listener - in this mode, the probe waits for incoming connection;
      rendezvous - in this mode, both the SRT source and probe are ready to establish the SRT connection as soon as an SRT stream starts. The mode is used when both nodes are behind the firewall and allows for establishing connection without the firewall configuration.
    • username (optional field) - a string, a username;

    • password (optional field) - a string, a password;

    • keyLength (optional field) - a string, a cryptographic key length:
      AES-128 - 16 bytes;
      AES-192 - 24 bytes;
      AES-256 - 32 bytes.
    • cdi - an object, contains settings for analyzing the AWS CDI protocol:

    • adapterType - a string, a network contoller type for receiving data:
      EFA (default mode) - Elastic Fabric Adapter is a network interface for Amazon EC2 instances;
      SOCKET - allows to perform CDI task analysis without the use of basic EFA equipment, with data transfer over UDP;
      SOCKET_LIBFABRIC - the libfabric socket adapter provides a reliable transport over UDP and is recommended for creating prototypes on platforms different from EFA.
    • protocolType - a string, type of transmitted data:
      RAW - is designed for transmitting data that should not be parsed;
      AVM (default mode) - is designed for transmitting audio/video/metadata.
    • audio - an object, contains settings for audio
      • bitPerSample - an integer, the number of bits in each sample.

    • video - an object, contains settings for video
      • componentsFormat - a string, the order of YUV data planes:
        Planar (default mode) - the components of Y, U, and V are respectively grouped together;
        Packed - the components of Y, U, and V are interleaved.
      • orderFormat - a string, the order of YUV components:
        YUV (default mode) - for the Planar mode;
        UYVY - for the Packed mode.

5.11.3. Examples of Tasks Setting

To set tasks from a configuration file, it is enough to specify the mandatory field addr. Other settings may be specified in web-interface after launching the probe.

Important

After launching the probe, the config file content will be updated automatically in compliance with the default format of the currently used probe. So, if you are going to set tasks to the probe by editing the monitor.cfg file, always save a backup copy of the file.

It is possible to add tasks using a simple URI list:

A simple URI list
 {
   "config":{
     "AppDescription":"My probe name",
     "server":"https://172.16.11.111",
     "uri":[
       "udp://239.0.0.22:1234",
       "udp://239.0.0.41:1234",
       "udp://239.0.0.71:1234",
       "udp://239.0.0.73:1234",
       "udp://239.0.0.181:1234"
     ]
   }
 }

If it is required to add several task parameters, e.g. URI, Name and Network Interface IP, they are specified as object fields of a task.

Tasks with parameters
 {
   "config":{
     "AppDescription":"My probe",
     "server":"https://boro.elecard.ru",
     "uri":[
       {
         "addr":"udp://239.0.0.22:1234",
         "name":"Channel_1",
         "iface":"10.10.30.197"
       },
       {
         "addr":"udp://239.0.0.41:1234",
         "name":"Channel_2",
         "iface":"10.10.30.197"
       },
       {
         "addr":"udp://239.0.0.71:1234",
         "name":"Channel_3"
       },
       {
         "addr":"udp://239.0.0.73:1234",
         "name":"Channel_4"
       },
       {
         "addr":"udp://239.0.0.181:1234",
         "name":"Channel_5"
       }
     ]
   }
 }

See below the same example formatted in string. This is a convenient way to make a configuration file in spreadsheet editors, when configuration should be formed from a channel plan.

Task with parameters in string
 {
   "config": {
     "AppDescription": "My probe",
     "server": "https://boro.elecard.ru",
     "uri": [
       {"addr": "udp://239.0.0.22:1234","name": "Channel_1","iface":"10.10.30.197"},
       {"addr": "udp://239.0.0.41:1234","name": "Channel_2","iface":"10.10.30.197"},
       {"addr": "udp://239.0.0.71:1234","name": "Channel_3"},
       {"addr": "udp://239.0.0.73:1234","name": "Channel_4"},
       {"addr": "udp://239.0.0.181:1234","name": "Channel_5"}
     ]
   }
 }