fps-go-brr

⚠️ Work in Progress: This project is actively under development and not yet feature-complete!

A Go CLI tool for video frame analysis and comparison. Analyze frame persistence, detect dropped frames, and export data for visualization tools like those used by Digital Foundry.

Features

• Frame Persistence Analysis: Detect consecutive duplicate frames and measure persistence duration
• CSV Export: Generate data compatible with video analysis visualization tools
• Multi-format Support: Works with any video format supported by FFmpeg
• Configurable Tolerance: Adjust pixel difference sensitivity for noisy videos
• Real-time Analysis: Stream processing for efficient memory usage
• Two-pass Architecture: Accurate frame timing calculations for smooth visualizations
• Resolution Measurements: Using the resdet cli to log dynamic resolutions (Requires resdet to be installed seperately)

Quick Start

Installation

Download the latest release from the releases page or build from source:

# Clone the repository
git clone https://git.aria.coffee/aria/fps-go-brr.git
cd fps-go-brr

# Build normally
go build -o fps-go-brr .

# Or build compact version (requires UPX)
./build-compact.sh

Basic Usage

# Analyze frame persistence with CSV export
./fps-go-brr analyze-frame-persistence video.mp4 --csv-output analysis.csv

# With tolerance for noisy videos
./fps-go-brr analyze-frame-persistence video.mp4 --tolerance 10 --csv-output analysis.csv

# Count total frames in a video
./fps-go-brr count-frames video.mp4

# Compare two individual frames
./fps-go-brr compare-frames frame1.png frame2.png

CSV Output Format

The analyze-frame-persistence command generates CSV files with the following columns:

Column	Description
frame	Frame number (starts on 1)
average_fps	Running effective FPS calculation
frame_time	Current frame persistence duration (ms)
unique_frame_count	Cumulative unique frame count
real_frame_time	Total persistence time for smooth visualization

Use Cases

• Game Performance Analysis: Detect frame drops and stuttering in gameplay footage
• Technical Reviews: Generate data for Digital Foundry-style analysis

Development Status

This project is under active development. Current feature wish list:

• Enhanced frame comparison algorithms
• Performance optimizations for large videos
• Additional export formats
• Cross-platform testing and compatibility
• Documentation improvements
• Graph generation from CSV

Building

Prerequisites

• Go 1.21 or later
• UPX (optional, for compact builds)

Commands

# Standard build
go build -o fps-go-brr .

# Compact build with UPX compression
./build-compact.sh

Repository

Main Repository: https://git.aria.coffee/aria/fps-go-brr
Mirror (GitHub): https://github.com/BuyMyMojo/fps-go-brr

The main development happens on the personal Forgejo instance. The GitHub mirror also accepts pull requests and bug reports for convenience.

Contributing

This is an early-stage project. Contributions, bug reports, and feature requests are welcome on either the main repository or the GitHub mirror!

Technical Details

Built with:

• CLI Framework: urfave/cli/v3
• Video Processing: AlexEidt/Vidio
• Image Processing: Go standard library

Inspirations

This project draws inspiration from:

• Digital Foundry - Professional video game performance analysis and technical reviews
• Brazil Pixel - Technical video analysis and frame rate studies
• TRDrop - Raw video analysis program for framerate estimation and tear detection
• Original Python implementation - Early proof-of-concept for frame persistence analysis

The goal is to provide similar professional-grade video analysis capabilities for the open-source community.

Note on AI use

The use of AI in this project is minor and just an experiment, all major design decisions and functionality are heavily worked on by humans!

I do hope for future AI tools with ethical models to be avaliable and verifiable in the future!

The testing phase for Claude's coding agent in this repo is finished and it shall not contribute more to the code at the current time.

License

SPDX-License-Identifier: MIT OR Apache-2.0

This project is dual-licensed under your choice of:

• MIT License - see LICENSE.MIT file for details
• Apache License 2.0 - see LICENSE.Apache-2.0 file for details

Copyright (c) 2025 Aria, Wicket

---