Read the Docs

Python utility for clipping and stitching GoPro video from SEFIS video surveys

About

This is a Python utility used for merging GoPro videos collected during SEFIS video surveys. GoPro cameras are deployed and record continuously for about an hour at a time. These video files are automatically split into 4GB chunks by GoPro video processing software to prevent data loss, with each file containing approximately 15 minutes of footage. Current science protocol involves processing a 20-minute video segment from each deployment relative to the time the camera reaches the bottom:

  • Video folders are named using a collection number convention consisting of a combination of a project code, year, collection, and camera.
  • Each folder is a single deployment of a trap with a camera and contains a board file (a brief video prior to deployment showing metadata information) and a number of underwater video files.
  • A metadata CSV file contains a timestamp for each unique collection number indicating a reference point relative to the elapsed time from when the video files start to when the trap lands on the bottom.
  • The objective is to extract a segment of video starting exactly 8 minutes after the trap lands on bottom (rounded up to the nearest 30 seconds) and ending 24 minute later. This involves slicing some videos and stitching relevant segments together.1
  • The new stitched video is named exactly like the folder containing the files (i.e., the collection number).

This script does three things:

  1. Determines where in the collection of deployment videos the desired 24-minute segment is located using the CSV timestamps and metadata extracted from the video files themselves (e.g., duration, frame rate, etc.)
  2. Clips the relevant portion of partial videos at the appropriate start and end times, as needed
  3. Stitches the required videos together into a single video file for each deployment

Some key features:

  • Frame-Accurate Seeking: Uses FFmpeg filters to ensure exact millisecond alignment across GoPro chapter seams.
  • NTSC Correction: Automatically2 handles GoPro 29.97 fps (30000/1001) timing to prevent timecode drift in long deployments.
  • Diagnostic Overlays: Provides optional burned-in timecode with HH:MM:SS:FF format for frame-by-frame verification.
  • Parallel Processing: Supports parallel processing and automatically ensure resources are not exceeded.
  • *GCP Upload: Optionally upload new files to a GCP bucket after creation.

An optional diagnostic mode can be used to embed an authoritative video timestamp into the video frames (formatted HH:MM:SS:FF) to help find the splice times. This is useful because some video software do not preserve the original frame rate or do not display frame number during playback. This embedded timestamp is fundamentally independent of the timestamp shown in most video players, which is merely a count from the start of the video. A video player would not know, for example, if a bad stitching operation inadvertently skips a frame or chunk of frames. Engaging diagnostic mode will also print out a table of the stitch times for each deployment to the console including where in the original video files the segments were taken. To assess the performance of the script, compare the frames in the new video at and around the stitch times (“NEW VIDEO TIME”) to the appropriate clip timestamps in the corresponding source files (“SOURCE TIMESTAMP”). If, for example, the stitch caused the same file to be read twice, the video player clock will keep advancing but the embedded timestamp in the video will reset or stutter. If the stitch is correct, the embedded timestamp will advance monotonically across the stitch.

Note

This table is always added to a log file even when diagnostic mode is off, but printing to the screen can be convenient for evaluation or troubleshooting.

Dependencies

This project requires the following software and libraries:

  • Python >= 3.14

    Be sure to check the box to add Python to your system PATH during installation, or add it manually yourself after installation. This will allow you to run Python from the command line and ensure that the utility can find the Python executable when running. On Windows, you may also need to turn off app execution aliases related to Python (e.g., python.exe',python3.exe`.)

  • ffmpeg and ffprobe >= 6.1

    The ffmpeg and ffprobe utilities are automatically downloaded when the setup script is run; otherwise, they are available here. Both utilities are included in the ffmpeg download.

Python Libraries

  • pandas >= 3.0.2
  • pyyaml >= 6.0.3
  • tqdm >= 4.67.3

Recommendations

  • Git CLI for repository cloning and version control via command line
    or
    GitHub Desktop for repository cloning and version control via GUI
  • Anaconda for virtual environment implementation

Release Notes

Version History
  • Version 2026.0.1 (BETA) (Apr 2026): Initial version for testing

License

Software code created by U.S. Government employees is not subject to copyright in the United States (17 U.S.C. §105). The United States/Department of Commerce reserve all rights to seek and obtain copyright protection in countries other than the United States for Software authored in its entirety by the Department of Commerce. To this end, the Department of Commerce hereby grants to Recipient a royalty-free, nonexclusive license to use, copy, and create derivative works of the Software outside of the United States.

Disclaimer

This software is a scientific product and is not official communication of the National Oceanic and Atmospheric Administration, or the United States Department of Commerce. All NOAA software and project code is provided on an “as is” basis and the user assumes responsibility for its use. Any claims against the Department of Commerce or Department of Commerce bureaus stemming from the use of this software will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government.

Footnotes

  1. Both of these time windows are user-configurable, if desired. The default values are based on the current science protocol but can be adjusted as needed. See Options for more information.↩︎

  2. The frame rate is extracted from the video metadata, rather than being hard-coded into the script, in an effort to make the utility camera-agnostic.↩︎