The Finals Stats Tracker

Automatically extracts ranked tournament stats from screenshots of The Finals and pushes them to a Google Sheet — zero manual data entry.

How It Works

1. Save/screenshot your tournament result screen to your SCREENSHOT_DIR (default: ~/Pictures/Screenshots/the_finals_stats/)
2. A background systemd service detects the new file via inotify (zero CPU when idle)
3. Gemini Vision (gemini-2.5-flash) reads the screenshot and extracts: RS, placement, difficulty, seed
4. Stats are pushed to Google Sheets via an Apps Script web app
5. A desktop notification shows the result

Extracted Fields

Field	Example	Description
rs	28152	Rank Score from "RANK SCORE UPDATE"
placement	3, 5/6	Final tournament placement
difficulty	Easy, Intermediate, Challenging	Tournament difficulty
seed	2	Team's starting seed

Setup

Prerequisites

• Linux with systemd (user services)
• Python 3.10+
• A Gemini API key (free tier works)

1. Google Sheet Setup

Follow the Google Apps Script Setup Guide to create your sheet and deploy the web app endpoint.

Quick version:

1. Create a new Google Sheet
2. Extensions > Apps Script — paste app_script.gs
3. Select setupStats from the function dropdown and click Run
4. Deploy > New deployment — Web app, access: Anyone
5. Copy the deployment URL

2. Install

git clone ssh://git@forge.wolfhound.dev/wolfhound/the-finals-tracker.git
cd the-finals-tracker
./install.sh

The install script will:

• Create a Python virtual environment and install dependencies
• Prompt for your Gemini API key and Apps Script URL
• Install and start the systemd background service

Manual Install

If you prefer to set things up yourself:

python3 -m venv .venv
source .venv/bin/activate
pip install google-genai python-dotenv requests inotify_simple Pillow pydantic

Create .env:

GEMINI_API_KEY=<your-gemini-api-key>
APPS_SCRIPT_URL=<your-apps-script-deployment-url>
SCREENSHOT_DIR=~/Pictures/Screenshots/the_finals_stats

Install the systemd service:

mkdir -p ~/.config/systemd/user
# Edit finals-tracker.service and replace /path/to/the_finals_tracker with your actual path
cp finals-tracker.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now finals-tracker

Usage

Automatic (recommended)

The systemd service watches your SCREENSHOT_DIR. Just save a tournament result screenshot there and it handles the rest.

# Check service status
systemctl --user status finals-tracker

# View logs
journalctl --user -u finals-tracker -f

One-shot capture

./capture_stats.sh

Opens a region selector — draw around the tournament result screen, and it extracts + pushes automatically. By default uses Spectacle (KDE). See the Desktop Environment Guide for GNOME, XFCE, Hyprland/Sway, and other DEs.

Manual CLI

# Process the latest unprocessed screenshot
./extract_stats.py

# Process a specific file
./extract_stats.py --file path/to/screenshot.png

# Reprocess all screenshots
./extract_stats.py --reprocess

# Watch mode (what the systemd service runs)
./extract_stats.py --watch

Desktop Environments

The background service works on any Linux DE. The one-shot capture script (capture_stats.sh) defaults to KDE Spectacle but can be adapted for any DE. See the Desktop Environment Guide for instructions on:

• KDE Plasma — Spectacle (default)
• GNOME — gnome-screenshot
• XFCE — xfce4-screenshooter
• Hyprland / Sway — grim + slurp
• Any DE — Flameshot (universal)

Files

File	Purpose
extract_stats.py	Main script — extraction, sheet push, watch mode
capture_stats.sh	One-shot region capture (KDE default, see DE guide)
app_script.gs	Google Apps Script — paste into your sheet (setup guide)
install.sh	Automated setup script
finals-tracker.service	systemd service template
.env	API keys (not committed)
.processed_screenshots.json	Tracks processed files by MD5 hash

Google Sheet

The Apps Script doPost() endpoint receives JSON and appends a row with the extracted stats. Running setupStats from the Apps Script editor sets up:

• Columns A-M with game data and auto-calculated formulas (W/L, RS change, win rate, rank, tier)
• A themed Stats Dashboard (columns O-Q) with current status, RS stats, progression, and class breakdown
• Conditional formatting for rank tiers (Bronze through Ruby)
• The Finals color scheme (red, gold, dark backgrounds)