User Guide

Heads up: SharkTrack is free and we love hearing from people who use it. If you do, please tell us by filling in this 30-second form.

Overview

This page walks you through downloading SharkTrack and running it on your videos. This completes Step 1 of the BRUVS analysis workflow: automatic processing.

Given a folder or hard drive of BRUVS, SharkTrack processes the videos automatically, detects elasmobranchs, saves detection metadata to a CSV and exports a screenshot for each detected individual.

Once you have the output, jump to Step 2: Annotation Pipeline to compute MaxN.

---

Installing SharkTrack

If you don’t have Python experience, don’t worry, follow this guide step by step and you’ll be running SharkTrack in minutes.

Pre-requirements

You need Python 3.9 or above.

On Windows

• Open Command Prompt (type cmd in the search bar)
• Run: python --version

On macOS

• Open Terminal (Spotlight, or Applications → Utilities)
• Run: python3 --version

If you don’t have Python 3.9+, install it from python.org/downloads.

Download the model

1. Download the latest release from GitHub Releases (the zip file).
2. Unzip to extract sharktrack.
3. Move sharktrack to your Desktop.

On Windows

• Open the extracted sharktrack folder.
• If using Command Prompt: replace the address-bar text with cmd and press Enter.
• If using Anaconda: copy the address, open Anaconda Prompt, and run cd {the address}.

On macOS / Linux

• Right-click the sharktrack folder.
• Select “New Terminal at Folder” (sometimes nested under Services).

Familiar with Git? Just clone the repository.

Set up the environment

With your terminal opened in the sharktrack folder:

If you use Anaconda

conda create -n sharktrack anaconda
conda activate sharktrack
pip install -r requirements.txt

On Windows (no Anaconda)

python -m venv venv
venv\Scripts\activate.bat
pip install -r requirements.txt

On macOS / Linux

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

---

Running SharkTrack

You’re set up. From now on, whenever you want to run SharkTrack, follow these steps.

Move your videos into ./input_videos inside the SharkTrack folder, or pass a custom path with --input.

Anaconda

conda activate sharktrack
python app.py

Windows

venv\Scripts\activate.bat
python app.py

macOS / Linux

source venv/bin/activate
python app.py

When the model finishes, check the output folder. Time to generate MaxN, head to the Annotation Pipeline.

The model takes roughly 0.75% of video time to run on CPU. For faster processing, use Peek mode.

Configuration

Configure SharkTrack with command-line arguments:

python app.py --arg1 {val1} --arg2 {val2} --arg3

Argument	Description	Default
--input {path}	Path to the video folder. Processes all .mp4 videos recursively.	./input_videos
--stereo_prefix {prefix}	Only process videos whose filename starts with this prefix (Stereo-BRUVS).	-
--limit {n}	Maximum number of videos to process.	1000
--conf {value}	Confidence threshold.	0.25
--output {path}	Output folder.	./outputs
--peek	Run in Peek mode.	False
--chapters	Aggregate video chapters into one video.	False
--resume	Skip videos already analysed in the output path.	False

Example

python app.py --input G:\BRUVS_2023 --peek --stereo_prefix L

Runs SharkTrack peek mode on all videos from G:\BRUVS_2023 starting with “L”.

---

Peek mode

Peek mode extracts interesting frames without full tracking, 5× faster, but no MaxN.

python app.py --peek

The output contains a peek_frames/ folder listing all detections.

Peek mode only outputs frames; it can’t compute MaxN. Try the default mode first for finer-grained, more accurate information.

---

Performance

Mode	Feature	Inference time	Limitations	Best for
analyst (default)	Compute MaxN	~27 min per video-hour	Slower; some GoPro versions unsupported	Species ID & MaxN
peek	Extract frames	~9 min per video-hour	No annotation; more frames to review	Quick frame extraction

The pipeline is tuned to minimise false negatives. The low confidence threshold ensures almost all sharks are detected, at the cost of ~5× “garbage” detections that the user manually rejects.

---

Troubleshooting

Installation & setup

• Terminal says I need git, install from git-scm.com, or download the source from Releases.
• python -m venv venv says python not found, try python3 -m venv venv or py -m venv venv.
• venv module not found, check your Python version (python --version). Ensure 3.9+. If not, install from python.org.

GoPro limitation

If you see this warning:

[ WARN:0@379.898] global cap_ffmpeg_impl.hpp:1541 grabFrame packet read max attempts exceeded...

your GoPro version is incompatible. Use the reformatting script:

You’ll need ffmpeg installed. Check with ffmpeg -version. If missing, install from ffmpeg.org.

python utils/reformat_gopro.py --input {original} --output {new}

Recommended GoPro workflow

1. Collect BRUVS videos.
2. Transfer from SD card using the reformat script:

   python utils/reformat_gopro.py --input PATH_TO_SD --output COPY_DESTINATION
   

3. Run SharkTrack overnight:

   python app.py --input COPY_DESTINATION
   

---

Next step

→ Annotation Pipeline, review SharkTrack’s output and compute species-specific MaxN.