docs(README): add a full README to the project

README.md

@@ -0,0 +1,137 @@
+# 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
+
+## Quick Start
+
+### Installation
+
+Download the latest release from the [releases page](https://git.aria.coffee/aria/fps-go-brr/releases) or build from source:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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](https://git.aria.coffee/aria/fps-go-brr)  
+**Mirror (GitHub)**: [https://github.com/BuyMyMojo/fps-go-brr](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](https://github.com/urfave/cli)
+- **Video Processing**: [AlexEidt/Vidio](https://github.com/AlexEidt/Vidio)
+- **Image Processing**: Go standard library
+
+<!-- The tool uses a sophisticated two-pass analysis architecture to ensure accurate frame timing calculations for professional visualization tools. -->
+<!-- ??? -->
+
+## Inspirations
+
+This project draws inspiration from:
+
+- **[Digital Foundry](https://www.youtube.com/@DigitalFoundry)** - Professional video game performance analysis and technical reviews
+- **[Brazil Pixel](https://www.youtube.com/@brazilpixel)** - Technical video analysis and frame rate studies
+- **[TRDrop](https://github.com/cirquit/trdrop)** - Raw video analysis program for framerate estimation and tear detection
+- **[Original Python implementation](https://web.archive.org/web/20250613174657/https://snippets.aria.coffee/snippets/2)** - Early proof-of-concept for frame persistence analysis
+
+The goal is to provide similar professional-grade video analysis capabilities for the open-source community.
+
+## License
+
+SPDX-License-Identifier: MIT OR Apache-2.0
+
+This project is dual-licensed under your choice of:
+- MIT License - see [LICENSE.MIT](LICENSE.MIT) file for details
+- Apache License 2.0 - see [LICENSE.Apache-2.0](LICENSE.Apache-2.0) file for details
+
+Copyright (c) 2025 Aria, Wicket
+
+---