GoProX

The missing GoPro workflow and data manager for macOS.

For those with one or more GoPro cameras. When using these action cameras regularly, the limitations of the GoPro ecosystem quickly become very obvious. GoPro is focusing its efforts on its mobile app experience, and not much development is directed toward macOS. GoProX is geared toward (semi-) professionals and prosumers that simply need more from their devices. GoProX is based on a data-first approach to importing, processing and maintaining media generated by various GoPro devices. At this moment the tool is actively developed and tested with GoPro Hero8, Hero9, Hero10, Hero11 and GoPro Max.

Installation

The most common way to install goprox is via home-brew.

To install goprox simply type

brew install fxstein/fxstein/goprox

Alternatively, you can add the fxstein tap manually before installing goprox

brew tap fxstein/fxstein
brew install goprox

Once installed, you can upgrade goprox by simply running

brew upgrade goprox

Alternatively, you can also uninstall and reinstall goprox in case of issues with the upgrade

brew uninstall goprox
brew install goprox

Note: Homebrew will install to /opt/homebrew/bin/goprox on Apple Silicon and /usr/local/bin/goprox on Intel Macs.

Setup

To simplify repeat usage of goprox it supports saving its configuration in ~/.goprox. To create this configurations file, simply execute goprox with its --setup option:

goprox --setup --library "/mylibrary/dir" --source "." --copyright "My Name"

You can also create alternate configuration files by specifying the --config option:

goprox --config "myotherconfig" --setup --library "/myotherlibrary" --source "." --copyright "My Other Name"

All subsequent runs of goprox will by default leverage the setting stored in ~/.goprox unless the --config option is specified with an alternate configuration file.

The --setup option can be rerun as often as desired to change the settings stored in ~/.goprox. Whenever --setup detects a prior configuration it creates a backup copy named like .goprox.bak.1657302965. The configuration file is a simple text file that is sourced in goprox.

As part of the setup, goprox will create a library skeleton unless the library already exists. The default location is ~/goprox, but placing the library on a dedicated storage device is highly encouraged as the data volumes will be very significant.

This is the hierarchy of the goprox library:

goprox/ (named and placed as required)
├── archive/
├── imported/
├── processed/
└── deleted/

All subsequent runs of goprox will validate this storage hierarchy. See the storage hierarchy section for more details

Usage

Once installed and set up GoProX maintains a file system based media library that is organized by time, camera types and media file types. The main goal is to maintain all file details from the original to the processed items, even if media files are further being processed in various apps including e.g. Apple Photos or Blackmagic DaVinci Resolve. Unfortunately, many commonly used apps ignore most of the important metadata, making it very hard for users to filter, sort or search for common things inside ever-growing libraries of media. GoProX performs a few simple tasks that will make your life with GoPro media on Apple platforms a lot easier. First, it renames the files as part of --import and --process tasks. This is an often overlooked step that will lead to the loss of some of the most basic metadata over time. Especially when files get exported, copied or moved, things like the original date & time, and the source of the original image can get lost easily, creating issues down the line.

It then adds additional tags and keywords into the processed media files to make searching, filtering and corrections a lot easier.

GoProX supports --geonames lookups for GPS-based timezone information, --firmware checks and upgrades, --archive of raw media into compressed archives before --import and --process tasks are being applied, a --clean task to remove processed media from storage devices as well as a --timeshift task that makes it possible to bulk change the date and time information of media files. It also makes it easy to apply default --copyright tags to all processed media. Default options can be set using the --setup tasks and settings are being stored in the user's home directory in ~.goprox. The output can be timestamped via the --time option to log long-running tasks. For developers, GoProX comes with a small set of test data from various cameras that allows for testing and validation of changes with the --test option.

Examples

goprox --import

The --import option will read from source (default to the current directory .) and import all image and video media files into library\imported. This is best used for importing media files from the path of a mounted media card. To do so, insert your camera's microSD card into a reader attached to your Mac. Open Finder to see the mounted card, right-click it and select New Terminal at Folder. This will open a new zsh terminal at the mounted card folder.

Alternatively --import can process a tar.gz archive directly. It will first untar the contents into a temp directory and then import from there. This is helpful when re-importing previously archived sd card data

goprox --archive

The --archive option will create a full archive of the source folder as a tarball inside library\archive named like 20220802215621_GoPro_Hero10_2442.tar.gz. This is useful to preserve the full content of the SD card before making any changes to it.

goprox --archive --import --clean

All the options can be performed in a single pass. In this example goprox will first create a new archive of the source, then import all the media files contained on the source and finally remove all media files from the source. The --clean option will only execute when combined with either --archive or --import or both to avoid accidental deletion of media files.

goprox --firmware

The --firmware option will check the camera model and current firmware version of the sd card currently mounted and will upgrade it to the latest GoPro firmware for your model if a newer one exists. Simply put the sd card back into the camera and on the next boot up the camera will upgrade itself.

The labs modifier: goprox --firmware labs will perform the same check for the latest GoPro Labs firmware version. Omitting the labs modifier in a later firmware check will return the camera to the latest official firmware.

goprox --import --time

Adding the --time option creates a timestamped output of the goprox run to aid in logging for long-running tasks that import or process thousands of media files. All output of goprox is getting timestamped like

[2022-08-04 12:15:09] Info: goprox v00.08.08

goprox --archive --import --clean --time --firmware

This example combines the most commonly used features for any import of media files directly from the camera's sd card. --archive creates a full tarball of the content --import imports all media files into the library --clean removes all media files from the sd card upon successful completion of the --archive and --import tasks --time timestamps all goprox output --fimware checks the sd-card for the current firmware version of the camera and if necessary installs the latest firmware onto the card for an automatic upgrade next time the camera is booted up. For this to function properly sd-cards of different cameras should not be mixed.

It is recommended to perform as many import tasks as you have cameras with new footage. Multiple camera sd-card can be imported simultaneously if a multi-card reader is available.

goprox --process --time

The --process option takes unmodified imported media files and rewrites them with enhanced metadata. This is where goprox inserts tags and flags into the media files that are then picked up by the likes of Apple Photos. For GoPro video media (mp4 & 360) --process also performs a UTC timeshift of all the Quicktime tags to allow downstream tools like Apple or Google Photos to display the correct date and time.

By default, process will look for newly imported media files since the last process run. Alternatively, all or any valid time window can be specified *[0-9](y|m|w|d|H|M|S). For example, goprox --process 30d will process the past 30d while goprox --process all will process all imported media files. Caution should be used when reprocessing older media files as the content of a file will change with a newer version of goprox, as any change in metadata will lead to a modified file.

Filenames