Configuration Settings

Using the configurations.yml file

A configurations.yml file is an easy way to control tool behavior as well as keep a record of the settings used each time. A template, called configurations-template.yml, is provided in the repository. Make a copy of this file and rename it to avoid overwriting the template. The most important settings in this file to pay attention to are:

The directory containing the videos to process
The directory containing the CSV metadata file and the relevant column headers
The directory where the new stitched video should be saved

These and other configuration options are detailed in the docs.

The configuration file is a YAML file structured as key: value pairs. The order in which these entries are presented in the file does not matter, but all keys need to be included and match exactly as expected unless otherwise noted. For example:

configurations.yml

# ----- PATH SETTINGS -----
input_directory: "C:\\Users\\user.name\\Documents\\videos"
output_directory: "C:\\Users\\user.name\\Documents\\videos"
csv_path: "C:\\Users\\user.name\\Documents\\videos\\SEFIS test vids.csv"
col_foldername: "foldername"
col_timebottom: "timebottom"

# ----- PROCESSING SETTINGS -----
clear_log: false
diagnostic_mode: false
reprocess: false
use_gpu: false

# ----- VIDEO PROCESSING UTILITIES (OPTIONAL) -----
ffmpeg_path: "ffmpeg/bin/ffmpeg.exe"
ffprobe_path: "ffmpeg/bin/ffprobe.exe"

It is recommended to create a new branch for any changes or experiments, including creating and modifying configuration files. This allows you to work without affecting the main branch and minimize version conflicts in the future.

A note on reproducibility

For the sake of documenting workflows and facilitating future reproducibility, consider creating new configuration files for each collection of videos processed (for example, one for each parent folder containing multiple deployments). There is no restriction on what this file can be called; you will tell the script which file to use when you execute the script. Thus, some convention like configuration-2025.yml might be sensible. It is best practice to avoid spaces and special characters other than underscores and hyphens in file names to avoid issues with file paths.

Where to save your configuration file

There are two schools of thought when it comes to organizing configuration files. It is ultimately up to the user to choose whichever convention is best for them.

Option 1: Alongside the script

Storing the configurations.yml file in the same directory as the processing script is advantageous when running the utility because you will not need to include the full directory path when you specify which configuration file to use. Since you will be executing the utility from the directory that script resides, the system will automatically find the configurations.yml file in that same directory.

The disadvantage to this option is that your directory may quickly become cluttered with different configuration files for different processing sessions.

Option 2: Alongside the data

One might opt instead to store the configurations.yml file in the same directory as the videos to be processed or the directory where the new video will be written out. This is helpful for documenting workflows and ensuring reproducibility since it will be easy to see how a given data set was processed.

The disadvantage to this option is that it will require the full directory path to be included when running the utility if executing in command line and specifying the configuration file to use.

Note

These are by no means the only options. Whatever convention is adopted, consistency is key. Your future self will thank you some day.