https://github.com/sound-barrier/recall
Tracks your Overwatch match history by OCR-ing post-match screenshots into a local SQLite database, with optional Prometheus metrics and a bundled Grafana dashboard.
https://github.com/sound-barrier/recall
desktop-app gaming go golang grafana match-history ocr overwatch performance-tracker prometheus screenshot sqlite tesseract vue wails
Last synced: 4 days ago
JSON representation
Tracks your Overwatch match history by OCR-ing post-match screenshots into a local SQLite database, with optional Prometheus metrics and a bundled Grafana dashboard.
- Host: GitHub
- URL: https://github.com/sound-barrier/recall
- Owner: sound-barrier
- License: apache-2.0
- Created: 2026-05-18T08:34:02.000Z (17 days ago)
- Default Branch: main
- Last Pushed: 2026-05-25T07:32:54.000Z (10 days ago)
- Last Synced: 2026-05-25T09:04:48.212Z (10 days ago)
- Topics: desktop-app, gaming, go, golang, grafana, match-history, ocr, overwatch, performance-tracker, prometheus, screenshot, sqlite, tesseract, vue, wails
- Language: Go
- Homepage:
- Size: 2.99 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Recall
[](https://github.com/sound-barrier/recall/actions/workflows/ci.yml)
[](https://github.com/sound-barrier/recall/actions/workflows/release.yml)
[](https://github.com/sound-barrier/recall/actions/workflows/pages.yml)
[](https://github.com/sound-barrier/recall/actions/workflows/codeql.yml)
[](https://github.com/sound-barrier/recall/releases/latest)
[](LICENSE)
[](https://go.dev/)
[](https://vuejs.org/)
[](https://sound-barrier.github.io/recall/)
[](https://sound-barrier.github.io/recall/api/)
[](CODE_OF_CONDUCT.md)
**Recall** is a desktop app for Overwatch players who want to understand
their performance trends over time. It watches a folder of OW post-match
screenshots, reads them with Tesseract OCR, and stores per-match data in a
local database. Optionally it exposes the match history as Prometheus metrics
so a bundled Grafana dashboard can chart win rates, SR trends, and per-hero stats.
```mermaid
flowchart LR
A[OW screenshots
SUMMARY · TEAMS
PERSONAL · RANK] -->|fsnotify watcher
or manual Parse| B(Tesseract OCR
+ per-screenshot
parsers)
B --> C[Correlation pass
resolves match_key
by timestamp or E/A/D]
C --> D[(SQLite
5 per-type tables
+ 5 child tables)]
D --> E[Read-time
aggregator
folds by match_key]
E --> F[Vue UI
Wails desktop
or browser]
D -.->|optional| G[Prometheus
collector
:9091/metrics]
G -.-> H[Grafana
dashboard]
classDef opt stroke-dasharray: 4 3
class G,H opt
```
📚 **Full documentation:** [sound-barrier.github.io/recall](https://sound-barrier.github.io/recall/) — installation guides, advanced usage, and the [API reference](https://sound-barrier.github.io/recall/api/). Auto-deployed from `main` on every doc change.
## Table of Contents
**Getting started**
- [Quick start](#quick-start)
- [Installation](#installation)
- [Verifying downloads](#verifying-downloads)
- [Windows](docs/install-windows.md) · [macOS](docs/install-macos.md) · [Linux](docs/install-linux.md)
- [Capturing matches](#capturing-matches)
**Advanced** — most users can skip these
- [🖥️ Use without the desktop app](docs/server.md) — browser access, headless mode, run on startup
- [🐳 Run in Docker](docs/docker.md) — containers, home lab, NAS
- [📊 Charts & Dashboards](docs/grafana.md) — Grafana, SR over time, win-rate charts
**Project**
- [Contributing](#contributing)
- [License](#license)
## Quick start
The desktop app is the simplest way to use Recall. Five steps from zero to your first match record:
1. **Install Recall** — grab `recall-{version}-windows-amd64-installer.exe` from [GitHub Releases](https://github.com/sound-barrier/recall/releases) and run it. Full step-by-step in the [Windows install guide](docs/install-windows.md). For macOS or Linux, see the [Installation](#installation) section below.
2. **Install Tesseract OCR 5.x** — Recall uses it to read your screenshots. Download the **5.x** installer from [UB-Mannheim](https://github.com/UB-Mannheim/tesseract/wiki) and run it with the default options. Older 3.x / 4.x builds are detected and flagged with a warning — parsing may misread. (macOS/Linux instructions are in [docs/install-macos.md](docs/install-macos.md) and [docs/install-linux.md](docs/install-linux.md).)
3. **Launch Recall and pick a screenshots folder** under **Settings → Directories**. Overwatch's default on Windows is `Documents\Overwatch\ScreenShots\Overwatch\`.
4. **Capture screenshots in Overwatch** with **F12** after each match — see [Capturing matches](#capturing-matches) for which post-match tabs to screenshot.
5. **Click *Parse → Run Parse*** to scan the folder, or flip on *Parse → Watch Folder* to auto-parse as new screenshots land. Parsed matches appear under the **Matches** tab.
That's all most users need. The [Advanced](#advanced) sections below cover running Recall headless and streaming matches into a local Grafana dashboard — neither is required for everyday use.
## Installation
Pre-built binaries for every tagged release are on the [GitHub Releases](https://github.com/sound-barrier/recall/releases) page.
| Platform | Desktop app | Server binary |
|---|---|---|
| **Windows** | `recall-{version}-windows-amd64-installer.exe` | `recall-server-{version}-windows-amd64.exe` |
| macOS arm64 | `recall-{version}-darwin-arm64.dmg` | `recall-server-{version}-darwin-arm64.tar.gz` |
| Linux | `recall-{version}-linux-amd64.tar.gz` · `recall-{version}-linux-amd64.deb` | `recall-server-{version}-linux-amd64.tar.gz` · `recall-server-{version}-linux-amd64.deb` |
| Docker | — | `ghcr.io/sound-barrier/recall-server:latest` |
For per-platform setup details (SmartScreen / Gatekeeper bypass, package-manager Tesseract install, data paths), see the platform guides:
- [Installing on Windows](docs/install-windows.md)
- [Installing on macOS](docs/install-macos.md)
- [Installing on Linux](docs/install-linux.md)
### Verifying downloads
Every release binary ships with a `.sha256` checksum file — the
[macOS](docs/install-macos.md#verifying-your-download) and
[Linux](docs/install-linux.md#verifying-your-download) install guides
have the one-line `shasum --check` command. On Windows, PowerShell:
```powershell
(Get-FileHash recall-{version}-windows-amd64-installer.exe).Hash -eq `
(Get-Content recall-{version}-windows-amd64-installer.exe.sha256).Split()[0].ToUpper()
```
`True` / `OK` means the file is intact; any mismatch means re-download.
For stronger supply-chain guarantees, every binary **and its `.sha256`
file** are also signed with [SLSA provenance](https://slsa.dev/) via
GitHub's Sigstore integration. Verify with the
[GitHub CLI](https://cli.github.com/):
```sh
gh attestation verify recall-{version}-windows-amd64-installer.exe --repo sound-barrier/recall
```
Every release also includes `recall-{version}-sbom.spdx.json` — a
software bill of materials listing every dependency.
## Capturing matches
Recall reads four kinds of post-match screenshots from Overwatch. Three are required for a complete match record; the fourth is optional but recommended for competitive play.
| Screenshot | Required? | What it provides |
|---|---|---|
| **SUMMARY** | ✅ Required | Match result (victory/defeat/draw), final score, map, mode, date, game length, and the list of heroes played with playtime percentages. |
| **TEAMS** (scoreboard) | ✅ Required | Eliminations, assists, deaths, damage, healing, mitigation. The in-game scoreboard (Tab key, mid-match) works as a fallback for the post-match tab. |
| **PERSONAL** | ✅ Required (one per hero played) | Per-hero detailed stats: weapon accuracy, ult charges, role-specific cards. If you played multiple heroes in a single match, take one PERSONAL screenshot for each. |
| **RANK** | ⭕ Optional (competitive only) | SR value, rank tier, rank change. Only appears after competitive matches. If it's missing but the SR change is captured, Recall infers the win/loss from the SR delta. |
The in-game screenshot key is **F12** by default (rebindable under *Options → Controls → General → Screenshot*). After a match ends, cycle through the post-match tabs and press F12 on each. Recall stitches the screenshots into a single match record using the filename timestamps Overwatch embeds — taking them within a couple of minutes of each other is enough.
Overwatch saves screenshots to `Documents\Overwatch\ScreenShots\Overwatch\` on Windows by default. Point Recall at that folder under **Settings → Directories**; the watcher (enabled under **Parse → Watch Folder**) auto-parses any new `.png` / `.jpg` that lands in it.
**What if a screenshot type is missing?** Each match row has a *Data Coverage* strip in the detail panel (click any row to open) that flags which of the four screenshot types were captured. Required-but-missing types are highlighted with a warning chip; the optional RANK is shown greyed out when absent. Screenshots Recall couldn't match to a known map collect in the **Unknown** tab for triage.
### What each screenshot type looks like
Real examples from Recall's parser-regression fixture set. The same PNG files live under `testdata/` in this repo and are the inputs `TestParseScreenshot_GoldenFiles` runs against on every change. Click any image for the full-resolution source.
SUMMARY
TEAMS scoreboard
Antarctic Peninsula · comp victory 2-1. The map name + game type + heroes-played list + per-10-min averages all come from this tab.
Same match. Eliminations / assists / deaths / damage / healing / mitigation all come from the highlighted row + the right-hand stat panel.
PERSONAL (one per hero played)
Juno's PERSONAL tab. The 3×3 grid populates hero-specific stats (pulsar torpedoes damage, orbital ray healing, players saved, weapon accuracy).
Mizuki's PERSONAL tab from the same match — the player swapped from Juno (67% played) to Mizuki (33% played). Recall captures one PERSONAL per hero and merges them into the same match record.
> **RANK screen** — no fixture in the test corpus yet (rank screens hadn't been captured at fixture-curation time). The RANK tab shows your current competitive rank tier + per-hero SR values + the recent change — Recall parses it the same way as the others when it's present.
---
# Advanced
If you're just playing Overwatch and want to track your stats, you can stop
reading here — the desktop app is all you need.
| Guide | For when… |
|---|---|
| [🖥️ Use without the desktop app](docs/server.md) | You want browser access, or to run Recall on a headless machine. |
| [🐳 Run in Docker](docs/docker.md) | You run containers on a home lab or NAS. |
| [📊 Charts & Dashboards](docs/grafana.md) | You want SR-over-time graphs and win-rate charts in Grafana. |
| [📘 API reference](https://sound-barrier.github.io/recall/api/) | You want to read or try the HTTP API — Swagger UI rendering of the OpenAPI spec, auto-deployed from `main`. |
## Contributing
Bug reports, feature requests, and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, build instructions, coding conventions, and [git hook requirements](CONTRIBUTING.md#git-hooks-lefthook). The release/tagging process — automated via [release-please](https://github.com/googleapis/release-please), with `make release-beta` / `make release-fire` shortcuts for the manual bits — is documented in [RELEASES.md](RELEASES.md). Commits on `main` follow [Conventional Commits](https://www.conventionalcommits.org/).
By participating in this project — opening an issue, filing a PR, commenting on a discussion — you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). Short version: be kind, and remember that Recall is given away free of charge and maintained in spare time, so no demands and no expectations of timely replies, bug fixes, or feature requests.
## License
Licensed under the [Apache License, Version 2.0](LICENSE).
Third-party dependency attribution is in [NOTICE](NOTICE). A full software bill of materials (SPDX) is attached to each [GitHub Release](https://github.com/sound-barrier/recall/releases).