Referees miss things. Scorekeepers lose count. iRefFoos solves both problems with a fully automated image processing pipeline that watches the ball, identifies which zone it's in, enforces shot-clock rules, and streams live statistics directly into OBS — in real time, on every possession.
Step 1 — Image processing
Every frame the camera produces is captured at a working resolution and normalized into a 320 × 320 pixel space before any analysis begins. Normalizing to a fixed coordinate system means that every downstream algorithm — zone boundaries, pixel cluster thresholds, centroid math — operates on consistent values regardless of the physical camera resolution or the table size in the frame. This predictability is what makes real-time detection practical on a mobile device.
Before zone detection can happen, the raw camera image must be geometrically corrected. Overhead cameras mounted above a foosball table are almost never perfectly perpendicular — they tilt, they shift, they produce a trapezoidal view of what should be a rectangle. iRefFoos corrects this using homography, a projective transformation that maps the four detected corner points of the table surface to a canonical top-down rectangle. This perspective correction warps every incoming frame so that the playing field always fills the normalized viewport in a consistent orientation, eliminating the distortion that would otherwise make zone boundaries unreliable.
With a geometrically corrected frame in hand, the pipeline moves to ball-pixel classification. The image is converted from RGB into HSV color space (hue, saturation, value), which separates color information from brightness and makes the classifier far more robust to changing lighting conditions. Each pixel is then tested against a per-table color profile: pixels that fall within the configured hue, saturation, and value ranges are marked as ball candidates. The resulting binary mask of candidate pixels is passed to centroid calculation — a weighted average of the X and Y positions of all matching pixels — to produce a single best estimate of the ball's location in the normalized frame.
A raw centroid is not enough on its own. Reflections off rods, glare from overhead lighting, and partial occlusions can all generate spurious pixel clusters that look like the ball. The pipeline therefore applies a pixel cluster radius check: the detected cluster must span a minimum number of pixels and remain within a plausible size range for a foosball. Clusters that are too small (reflections) or too large (merged lighting artifacts) are rejected. Only a cluster that passes this validation is accepted as a confirmed ball position for that frame.
Step 2 — Calibration
Before a session begins, iRefFoos runs a short calibration phase — typically around eight frames captured from a table with no ball and no players in motion. During this phase, the system builds a static background mask: a pixel-level map of every part of the image that can be permanently excluded from ball-detection consideration. The green felt surface, the rod housings, the goal openings, and the walls all get encoded into this mask so that the detection algorithm only needs to examine the small fraction of pixels where the ball could plausibly appear.
Background subtraction using a static mask cleanly eliminates a whole class of false positives that would otherwise be triggered by the table structure itself. It also handles the inherently predictable nature of a foosball table well: the background is genuinely static between possessions, unlike outdoor scenes where wind moves leaves or clouds shift light. Because the mask is built once at calibration time rather than recomputed every frame, the per-frame detection workload stays minimal even on a mobile CPU.
One practical challenge with a static mask is rod shadows. The metal rods cast shadows that shift slightly as rods rotate, and those shifting shadows can generate pixel-level changes that look like ball motion in a naively constructed mask. iRefFoos addresses this with mask dilation: the rod regions in the mask are expanded outward by a small number of pixels so that the shadow penumbra is also excluded. This handles the occlusion problem where rod rotation momentarily obscures the ball and prevents the tracker from briefly losing confidence because of a shadow artifact rather than genuine ball movement.
Step 3 — Zone detection
Once the ball position is confirmed in the normalized 320 × 320 frame, iRefFoos determines which of the six zones the ball currently occupies. Zone boundaries are defined as Y-coordinate ranges in normalized space: Goalie, 5-Bar, and 3-Bar each correspond to a horizontal band across the table. Because the homography step has already mapped the frame to a consistent top-down perspective, the Y-coordinate boundaries are the same values for every supported table model — only the per-table color profiles differ.
Raw per-frame zone assignments are noisy on their own. The ball can briefly leave one rod's zone and immediately return, and touch-and-go contacts that don't constitute a genuine possession change should not reset the shot clock. iRefFoos applies temporal filtering through a configurable confirmation delay: the ball must remain in a new zone for a minimum number of consecutive frames before the system records a possession change. This debouncing approach eliminates flicker while keeping latency low enough that the shot clock responds quickly to real play.
The possession timeline produced by this system records every confirmed zone entry, its timestamp, and the outgoing zone so that downstream components can reconstruct the full sequence of a game. The shot clock — a 10, or 15-second countdown begins the moment a possession change is confirmed and resets with each new possession.
Step 4 — Analytics backend
Every confirmed possession event is written to a
PostgreSQL
table called
possessions, which records the zone, the duration, whether the possession ended
in a successful pass or shot, the sub-zone within a 5-bar (wall or
lane), and whether a confirmed goal was scored. This row-per-event
event sourcing
approach means that every derived statistic — success rates, average
possession durations, zone heat maps — can be recomputed from the raw
log at any time. Nothing is discarded and nothing is pre-aggregated in
a way that prevents later reanalysis.
Match state is tracked through two companion tables:
matches
stores the overall match context — scores, serve indicator, teams, and
match phase — while
games
tracks the individual games within a match. The
REST API
server computes live success rates and pass-completion percentages on
demand using SQL aggregates over the possession events for the current
game, so the OBS overlays and public share pages always show numbers
that reflect everything that has happened since the first whistle.
Public sharing is handled via auto-generated match IDs derived from the device's unique identifier. Anyone with the QR code or share URL can view live match analytics in a browser — no app install required. The server performs real-time aggregation on every request, joining across the possession events, game records, and match records to produce a fully populated stats page in a single round trip. The relational database schema is designed so that a match with fifty games and thousands of possession events remains fast to query because every access pattern is indexed and bounded by the match ID.
Step 5 — Broadcast
iRefFoos ships many dedicated browser sources designed to drop straight into OBS Studio without any plugins or configuration files. Each overlay connects to the iRefFoos server via WebSocket and updates in real-time sync with every possession change, goal, timeout, or reset warning — turning a standard OBS setup into a sportscaster-quality foosball broadcast rig.
Web Auto-Timer
The Web Auto-Timer brings every component described on this page — perspective correction, HSV segmentation, centroid tracking, zone classification, and possession timeline recording — into a single browser-based application that requires no app install and no dedicated device. It runs entirely in-browser using the same TypeScript detection code as the iOS and Android apps, compiled to a self-contained JavaScript bundle via esbuild.
Frame processing runs inside Web Workers so the detection pipeline never blocks the browser's UI thread. The camera feed, the zone detection output, and the OBS overlay WebSocket connections all operate concurrently on a single machine, which means a streamer can run the complete auto-timer, OBS-Stats, OBS-Clock, OBS-Ref, and OBS-Dock from one machine — the same machine running OBS itself. No dedicated phone mount. No second screen. No latency from a cross-device connection.
The Web Auto-Timer supports the same five official ITSF table models as the mobile app and produces an identical possession timeline output, making it a fully interchangeable broadcast solution for tournament organizers who want the simplest possible setup path.
Launch Web Auto-Timer →Download iRefFoos free for iOS or Android and try automatic possession tracking at your next session, or launch the Web Auto-Timer right now in any browser — no install required.