Public Config Reference¶

The publicConfig.json file is a JSON file that contains the configuration for the studies that you can run.

The file is usually located in the config directory of the Automator installation, and it is also implicitly stored inside the Surfmeter Lab extension.

Example File¶

Here is an example file without content, which you can use as a template for filling out:

{
  "$schema": "https://aveq.info/jsonschema/PublicConfigSectionDataV1.json",
  "version": 1,
  "credentials": {},
  "studies": [
    // (1)
  ],
}

This is where you should specify each study. See Study Descriptions for more information.

The $schema property is optional, but it is recommended to include it for better validation in some editors. Now let's go through the different sections of the config file.

Properties¶

Root Properties¶

These are the root items of the config file.

Property	Value	Description
`version`	1	Internal version. Do not change this!
`studies`	array of Study Descriptions	A list of studies
`credentials`	Credentials (optional)	Credentials for individual services
`revision`	string (optional)	The revision of the config file. Can be a Git hash, a date, or anything else that makes sense for version control.

Study Descriptions¶

A study description is an object that describes a study. It has the following properties:

Property	Value	Description
`id`	string	A unique identifier for the study
`type`	string	The general type of study, must be one of `WEB`, `VIDEO`, `SPEEDTEST`, or `NETWORK`
`subject`	Subject	The subject of the study (i.e., the specific measurement technology)
`params`	Study Params	The parameters for the study
`names`	Study Names	Study names (textual descriptions)
`native`	Native Study Params (optional)	Custom options for native studies

Examples¶

Website StudyNetflix StudyNative Ping Study

This runs a web study using the browser.

{
  "id": "STUDY_TOP5_WEBSITES",
  "subject": "website",
  "type": "WEB",
  "names": {
    "en_US": {
      "short": "Web Top 5",
      "long": "Test queue for 5 of the most visited websites in the U.S."
    }
  },
  "params": {
    "timeout": 30,
    "urls": [ "google.com", "youtube.com", "facebook.com", "amazon.com", "yahoo.com" ]
  }
}

This runs a Netflix study. Note that this will only work if you have specified the credentials for Netflix.

{
  "id": "STUDY_NETFLIX",
  "subject": "netflix",
  "type": "VIDEO",
  "names": {
    "en_US": {
      "short": "Netflix",
      "long": "Netflix test"
    }
  },
  "params": {
    "duration": 60,
    "timeout": 30,
    "video": {
      "src": "https://www.netflix.com/watch/80094026?t=0",
      "contentType": "feature"
    },
    "playMode": "normal"
  }
}

This runs a ping test against a list of hosts.

{
  "id": "STUDY_PING",
  "subject": "icmpping",
  "type": "NETWORK",
  "names": {
    "en_US": {
      "short": "Ping",
      "long": "Ping test"
    }
  },
  "params": {
    "host": ["google.com", "youtube.com", "facebook.com", "amazon.com", "yahoo.com"]
  },
  "native": {
    "enabled": true
  }
}

Subjects¶

The subject keyword defines the specific measurement technology that is used for the study, or, for video, the service that will be called.

The following subjects are supported per type of measurement. Click on the name of the subject to see the parameters that can be configured.

Note

All video subjects use the same kind of parameters, so if they are not linked here you can assume default behavior. The link will take you to the service-specific documentation which you can also find here.

VIDEO:
- 3q
- 3sat
- amazon_trailer
- ardmediathek
- dashjs
- facebook
- joyn
- magentade
- netflix
- netflix_trailer
- nfl
- orf
- rakuten
- rtlplus
- servustv
- srf
- tiktok
- instagram
- waiputv
- youtube
- zattoo
- zdfmediathek

WEB:
- website
- lighthouse

SPEEDTEST:
- fastcom
- nperf

NETWORK:

CONFERENCING:
- googlemeet
- microsoftteams

Study Params¶

For each type of study and subject, there are different parameters that can be specified in the params object of the study description.

Video Study Params¶

Property	Type	Description
`duration`	number	The length of the video to play in seconds
`timeout`	number (optional)	The timeout to use when requesting the video
`video`	Video Params	The description of the video to load
`playMode`	string (one of: `embedded`, `lab_embedded`, `normal`, `unknown`)	The type of video player mode that is used. Choose `normal` or `unknown` if you don't know.
`credentials`	object with properties: `password`, `username` (optional)	The credentials to use when requesting the video
`player`	Player Params (optional)	The parameters to use when playing the video.
`statisticsCalculation`	Statistics Calculation Params (optional)	The parameters to use when calculating statistics

`Video Params`¶

The video params specify which video should be loaded. This can either be done by channel title or by video source. Note that you cannot specify both!

Property	Type	Description
`channelTitle`	string	The title of the channel to play. The list of possible channel titles depends on the service itself. Please ask our support for that list.
`src`	string	The URL of the video to play. Note that this depends on the particular service; some services have no permanent video URLs, or the URLs may be dynamically generated, so you should use a channelTitle instead. In case of questions you can ask us for a sample configuration.
`contentType`	string (one of: `advertisement`, `feature`, `lab`, `live`, `trailer`, `unknown`)	The type of video that is played. Choose `unknown` if you don't know.

`Player Params`¶

Property	Type	Description
`height`	number (optional)	The height of the video player (only supported by the `dashjs` player at the moment)
`width`	number (optional)	The width of the video player (only supported by the `dashjs` player at the moment)
`skipAds`	boolean (optional)	Whether to skip ads (only supported by YouTube at the moment)

`Statistics Calculation Params`¶

Property	Type	Description
`forceNominalBitrate`	boolean (optional)	Whether to force the nominal bitrate from the manifest to be used for calculations instead of the actually measured bitrate

Web Study Params¶

`website`¶

A web study for one or more websites loaded through the browser.

Property	Type	Description
`randomize`	`boolean` (optional)	randomize the URLs
`timeout`	`number` (optional)	How long in seconds before load is cancelled
`urls`	`array` of `string`	A list of URLs to load in the study

`lighthouse`¶

A web study for one or more websites loaded with Google Lighthouse. Requires the lighthouse CLI tool. For details, see the Lighthouse specification

Property	Type	Description
`emulatedFormFactor`	`string` (one of: `desktop`, `mobile`, `none`) (optional)	How emulation (useragent, device screen metrics, touch) should be applied. `none` indicates Lighthouse should leave the host browser as-is
`emulatedUserAgent`	`string` (optional)	The user agent string that the emulation should use
`maxWaitForLoad`	`number` (optional)	The maximum amount of time to wait for a page to load, in ms
`randomize`	`boolean` (optional)	randomize the URLs
`throttling`	`object` with properties: `cpuSlowdownMultiplier`, `downloadThroughputKbps`, `requestLatencyMs`, `rttMs`, `throughputKbps`, `uploadThroughputKbps` (optional)	The network throttling to apply to the run
`throttlingEnabled`	`boolean` (optional)	Whether to enable network throttling
`throttlingMethod`	`string` (one of: `devtools`, `provided`, `simulate`) (optional)	The method used to throttle the network
`timeout`	`number` (optional)	How long in seconds before load is cancelled
`urls`	`array` of `string`	A list of URLs to load in the study

Speedtest Study Params¶

`fastcom`¶

A speedtest study on fast.com.

Property	Type	Description
`maxConnections`	`number` (optional)	The maximum number of connections to use
`maxDuration`	`number` (optional)	Maximum test duration in seconds
`measureUploadLatency`	`boolean` (optional)	Whether to measure loaded latency
`minConnections`	`number` (optional)	The minimum number of connections to use
`minDuration`	`number` (optional)	Minimum test duration in seconds

`nperf`¶

This subject has no parameters to configure.

Network Study Params¶

`dns`¶

A network study implementing the DNS protocol, making one or more DNS queries against a specified host, optionally using a specific nameserver.

If DNS caching is used, this means that the first request will take longer, as the cache is warmed up, and subsequent requests will be faster.

Running a DNS study requires the dig CLI tool, unless the useGetAddrInfo flag is set to true, in which case, the getaddrinfo system call is used via Node.js.

When dig is used, it will make a simple A query by default, and we measure the time for the single request. When using getaddrinfo, an A and AAAA query are made at the same time, and the time to complete both queries is measured.

Property	Type	Description
`host`	`array` of `string`, or `string`	The host(s) to query
`nameserver`	`string` (optional)	The DNS nameserver to use (if unset, will use system default). Not applicable when useGetAddrInfo is true.
`queryCount`	`number` (optional)	The number of queries to send, default: 1
`useGetAddrInfo`	`boolean` (optional)	Use getaddrinfo instead of dig, and make an A and AAAA query at the same time

`icmpping`¶

A network study implementing the ICMP ping protocol. Requires the ping CLI tool.

Property	Type	Description
`discardFirstPacket`	`boolean` (optional)	Discard the first packet (e.g. to avoid DNS lookup interfering with)
`host`	`array` of `string`, or `string`	The host(s) to ping
`interval`	`number` (optional)	In seconds
`ipVersion`	`string` (one of: `v4`, `v6`) (optional)	Default: v4
`packetCount`	`number` (optional)	How many to send
`packetSize`	`number` (optional)	In bytes
`totalTime`	`number` (optional)	In seconds

`ooklaspeedtest`¶

A network study implementing the Ookla Speedtest CLI. Requires the speedtest CLI tool.

Property	Type	Description
`host`	`string` (optional)	The server via its host's fully qualified domain name
`server`	`string` (optional)	The server via its ID

`traceroute`¶

A network study implementing the traceroute CLI. This is based on the Linux (and, where possible, the macOS) traceroute CLI.

Property	Type	Description
`asLookup`	`boolean` (optional)	Perform AS path lookups in routing registries and print results directly after the corresponding addresses. Only with GNU traceroute or macOS traceroute.
`gateway`	`string` (optional)	Add an IP source routing option to the outgoing packet that tells the network to route the packet through the specified gateway(s). Comma-separate multiple gateways.
`host`	`array` of `string`, or `string`	The host(s) to traceroute to
`interface`	`string` (optional)	Specifies the interface through which traceroute should send packets. By default, the interface is selected according to the routing table.
`ipVersion`	`string` (one of: `v4`, `v6`) (optional)	Explicitly force IPv4 or IPv6 traceouting. By default, the program will try to resolve the name given, and choose the appropriate protocol automatically. If resolving a host name returns both IPv4 and IPv6 addresses, traceroute will use IPv4.
`maxHops`	`number` (optional)	Specifies the maximum number of hops (max time-to-live value) traceroute will probe. The default is 30.
`probeCount`	`number` (optional)	Sets the number of probe packets per hop. The default is 3.
`probeInterval`	`number` (optional)	Minimal time interval between probes (default 0). If the value is more than 10, then it specifies a number in milliseconds, else it is a number of seconds (float point values allowed too). Useful when some routers use rate-limit for icmp messages.
`useIcmp`	`boolean` (optional)	Set to true to explicitly use ICMP (if unset, will default to what traceroute does by default)
`useTcp`	`boolean` (optional)	Set to true to explicitly use TCP (if unset, will default to what traceroute does by default)
`waitTime`	`number` (optional)	Set the time (in seconds) to wait for a response to a probe (default 5.0 sec).

Conferencing Study Params¶

`googlemeet`¶

A conferencing study that joins a conference and measures the performance and quality.

Property	Type	Description
`duration`	`number`	Duration of the study in seconds
`mode`	`string` (one of: `host`, `join`) (optional)	The mode of the conference, if host, will attempt to let others join
`timeout`	`number` (optional)	Timeout for joining in seconds
`url`	`string`	The URL of the conference to join

`microsoftteams`¶

A conferencing study that joins a conference and measures the performance and quality.

Property	Type	Description
`duration`	`number`	Duration of the study in seconds
`mode`	`string` (one of: `host`, `join`) (optional)	The mode of the conference, if host, will attempt to let others join
`timeout`	`number` (optional)	Timeout for joining in seconds
`url`	`string`	The URL of the conference to join

Native Study Params¶

These are custom options for native studies. Native studies run on the host operating system — they are not run in the browser.

Property	Type	Description
`enabled`	`boolean`	Must be set to true by user to actively enable this study
`cmdPrefix`	`array` of `string` (optional)	Prepend to the native command
`cmdSuffix`	`array` of `string` (optional)	Append to the native command
`cwd`	`string` (optional)	Override the current working directory
`env`	`object` (optional)	Pass custom environment variables
`executable`	`string` (optional)	Override the executable for the native measurement

You must set enable to true for a native study to work.

Automator Parmas¶

These are custom options for the Automator.

Property	Type	Description
`enableFullscreen`	`boolean` (optional)	Enable fullscreen playback for video if possible. This is true by default. Set to false to disable.

Examples¶

Enabling a Native StudyAdding a command suffix

Always pass enable: true to enable a native study.

{
    "id": "STUDY_LIGHTHOUSE",
    "type": "WEB",
    "subject": "lighthouse",
    "names": { "en_US": { "long": "Lighthouse web study", "short": "Lighthouse" } },
    "params": {
        "urls": ["https://www.google.com"],
    },
    "native": {
        "enabled": true,
    }
}

This may be a bit contrived, but you can pass any command line arguments to the native study.

{
    "id": "STUDY_DNS",
    "type": "NETWORK",
    "subject": "dns",
    "names": { "en_US": { "long": "DNS Network test", "short": "DNS" } },
    "params": {
        "host": "example.com"
    },
    "native": {
        "enabled": true,
        "cmdSuffix": ["-p", "53"] // overriding the port
    }
}

Study Names¶

The study names are used to display the study in the UI. The names are specified in a dictionary, with the language code as the key. The following languages are supported:

Language	Code
English	`en_US`
German	`de_DE`
French	`fr_FR`

Each object has a short and long key.

To specify the names, you must at least use the en_US key.

Example¶

The following example shows the names for a study in English and German:

publicConfig.json

{
    // ...
    "studies": [
        {
            "id": "STUDY_WEB",
            // ... other params
            "names": {
                "en_US": {
                    "short": "Web Top 5",
                    "long": "Test queue for 5 of the most visited websites in the U.S."
                },
                "de_DE": {
                    "short": "Web Top 5",
                    "long": "Test-Queue für 5 der meistbesuchten Websites in den USA"
                }
            }
        }
        // ... other studies
    ]
}

Credentials¶

A credentials dictionary is required when measuring a closed-access service such as Netflix. It contains one key for each service, and the value is a dictionary with the username and password for that service.

For a list of possible service keys, see the list of subject values.

Tip

These credentials are likely to be different per device. Use the local config feature to specify different credentials for different devices.

Warning

The credentials are stored in plain text in the publicConfig.json file. Do not commit this file to a public repository. Ideally, change the permissions of the file so that only the user running the Automator can read it, i.e. chmod 600 publicConfig.json.

Example¶

publicConfig.json

{
    "credentials": {
        "netflix": {
            "username": "foo@example.com",
            "password": "bar"
        }
    },
    "studies": [
        // ...
    ]
}

Public Config Reference¶

Example File¶

Properties¶

Root Properties¶

Study Descriptions¶

Examples¶

Subjects¶

Study Params¶

Video Study Params¶

Video Params¶

Player Params¶

Statistics Calculation Params¶

Web Study Params¶

website¶

lighthouse¶

Speedtest Study Params¶

fastcom¶

nperf¶

Network Study Params¶

dns¶

icmpping¶

ooklaspeedtest¶

traceroute¶

Conferencing Study Params¶

googlemeet¶

microsoftteams¶

Native Study Params¶

Automator Parmas¶

Examples¶

Study Names¶

Example¶

Credentials¶

Example¶

`Video Params`¶

`Player Params`¶

`Statistics Calculation Params`¶

`website`¶

`lighthouse`¶

`fastcom`¶

`nperf`¶

`dns`¶

`icmpping`¶

`ooklaspeedtest`¶

`traceroute`¶

`googlemeet`¶

`microsoftteams`¶