ComboTracker

A small local web UI + Python backend that listens to your keyboard/mouse and tracks whether you performed a defined “combo” correctly, including wait and hold timing steps.

Features

• Practice combos: see live status + a step timeline.
• Wait + hold steps:
  • wait = minimum delay gate (pressing later is OK).
  • hold = finger commitment (must hold long enough).
• Combo enders: define which “wrong” inputs should drop the combo.
• Stats: success/fail, best time, hardest steps, fail reasons.
• Difficulty scoring (simple + tunable):
  • Practical APM (uses your expected execution time)
  • Theoretical max APM (uses fastest-possible time)
  • Difficulty out of 10 (keys + timing + simple timing-variation rule)

---

Getting started

Requirements

• Python 3.10+ recommended

Install dependencies:

cd ComboTracker
python -m pip install -r requirements.txt

Run

cd ComboTracker
python ui_server.py

Then open the UI:

• http://localhost:8080

Notes:

• The backend also runs a WebSocket server at ws://localhost:8765.
• The app listens to global keyboard/mouse via pynput (you may need accessibility permissions on some OSes).

Building a standalone .exe (Windows)

You can package ComboTracker as a single executable so others can run it without installing Python.

1. Install PyInstaller (once):

   pip install pyinstaller

2. From the project root, build:

   pyinstaller ComboTracker.spec

3. The executable is created at dist/ComboTracker.exe. Run it; it will start the HTTP and WebSocket servers. Open http://localhost:8080 in your browser.
4. combos.json (saved combos and settings) is stored in the same folder as the .exe. You can move the .exe anywhere; keep combos.json next to it if you want to keep your data, or it will create a new one on first run.

---

OBS overlay

You can show the Combo Steps timeline in OBS as a separate overlay (e.g. for streaming or recording).

1. In the main UI, open the Combo Steps section and click Copy Overlay URL.
2. In OBS, add a Browser Source, paste the URL (e.g. http://localhost:8080/?view=timeline), and set the width/height you want. The overlay stays in sync with the app via WebSocket.
3. Open in new window is also available if you prefer OBS Window Capture instead of Browser Source.

Browser Source vs your browser: The OBS Browser Source is a separate embedded browser. Toggles (Auto scroll, Images, Show fail count) are per-instance: use Interact on the Browser Source in OBS (right‑click the source → Interact) to open a window where you can click those controls for the overlay. Timeline content and progress sync for all clients; only the toggle state is local to each instance.

Wide layout: In timeline-only view (?view=timeline), the section stretches to fill the width of the Browser Source, so you can set a wide source in OBS and use the space.

For a walkthrough of common OBS Browser Source gotchas (separate instance, interact window, scrolling, sizing), see: OBS Browser Source demo (video, ~2:25).

you can set custom CSS to zoom in body {zoom : 150%;}

---

Documentation

Detailed docs live in documentation.md:

• Combo format: documentation.md#combo-format
• Combo enders: documentation.md#combo-enders
• Difficulty + APM: documentation.md#difficulty--apm
• Troubleshooting: documentation.md#troubleshooting
• Architecture / module map: documentation.md#architecture

Data

Combos and stats are stored locally in combos.json.

Tests

python -m pytest tests\ -v