Cricket Live 🏏
Ball-by-ball live cricket scores that stay on screen while you do other things. Free, no ads, no account.
▶ Open Cricket Live · works on Android, iPhone, Windows, Mac and Chromebook · Mac notch app
- Pin the score over any app. Tap Pin score on Android/iPhone or Pop out (P) on desktop. A tiny live score floats on top and updates every ball.
- FOUR, SIX and WICKET moments pop on screen as they happen.
- Follow your teams. Their matches open first, with optional alerts for start, wickets and result.
- Full picture: batters, bowler, last 12 balls, run rates, target and commentary.
- Share the score or a score image to WhatsApp or X.
- Install it from the browser (no app store needed), or get the free Mac app that lives beside the notch.
The Mac app
A tiny native macOS utility that keeps the live score at the top of your screen. It lives in the menu bar and shows a floating widget. On a MacBook with a notch, the widget grows out of the camera housing. It's written in Swift, SwiftUI and AppKit, with no browser or web view.
Collapsed, notched MacBook ● IND 184/4 [ camera ] 32.2 ov
Collapsed, no notch / Below Notch ( ● LIVE IND 184/4 32.2 · AUS 241/8 ⌄ )
Click the widget → score, need X from Y, CRR/RRR, batters, bowler, recent balls, match info
Real ball-by-ball scores come from a public live-score feed: no account, no API key, no server to run. Simulated demo matches are also built in, for trying every state of the widget.
Requirements
- macOS 14 Sonoma or later (built and tested on macOS 26).
- Xcode 16+ or just the Xcode Command Line Tools (
xcode-select --install).
Run it
Option A: Xcode
- Open
CricketScore.xcodeproj.
- Pick the CricketScore scheme and My Mac, then press ⌘R.
- A cricket-ball icon appears in the menu bar and the widget appears at the top of the screen.
If Xcode asks about signing, choose your team under Signing & Capabilities. Otherwise leave it as Sign to Run Locally. You can also open Package.swift in Xcode.
Option B: Command Line Tools only (no Xcode needed)
./Scripts/build-app.sh
open build/CricketScore.app
For quick iteration there's also swift build && .build/debug/CricketScore. That runs unbundled, so Launch at Login is unavailable.
Create the .app
./Scripts/build-app.sh # → build/CricketScore.app (release, ad-hoc signed)
./Scripts/build-app.sh --install # also copies it to /Applications
In Xcode: Product → Archive → Distribute App → Copy App.
The first launch of an ad-hoc-signed app copied to another Mac may be blocked by Gatekeeper. Right-click the app, choose Open, then confirm. To distribute more widely, sign it with a Developer ID and notarize it.
Launch at Login
- Run the app from a real bundle:
/Applications/CricketScore.app is best. It won't work from swift run.
- Go to Menu bar icon → Settings… → General → Launch at login.
- If macOS asks for approval, click Open Login Items… and enable Cricket Score.
This uses SMAppService.mainApp. You can turn it off in the same place or in System Settings → General → Login Items.
Using it
| Action | Result |
|---|
| Click the widget | Expands smoothly with details revealed in stages |
| Click anywhere else, or × | Collapses |
| ⋮ in the expanded widget | Switch match, refresh, pause overlay, open Settings |
| Match chips (expanded) / list (menu bar) | Switch between simultaneous matches |
| Menu bar icon | Selected score, live/upcoming/results lists, Pause/Show Overlay, Settings, Quit |
| Open the app again (Finder/Spotlight) | Opens Settings. Use this to get back if you've hidden both the widget and the menu bar icon. |
Settings
- General: show overlay, launch at login, show menu bar icon, auto-show when a match starts, hide when nothing is live, remember selected match.
- Teams & Alerts:
- Favorite teams. The widget switches to their match and appears when they start playing. "India" also follows India A, India Women and India Under-19s, and there's an option to only show your teams' matches. Favorites are starred in the menu.
- Notch alerts. A 5-second banner in the notch for wickets in your other teams' matches, batter milestones (50, 100…), the last over, match start and result. Alerts can pop up even while the widget is paused or hidden between matches.
- Display: position (Top Center / Top Right / Below Notch), optional drag-to-move with a remembered position, appearance (System/Light/Dark).
- Focus. Hides while a full-screen app is in front or a camera is on (video calls), and keeps the widget out of screen sharing and recordings.
- Data: update frequency (15/30/60 s, default 15), data source (Live scores by default / your own server / Demo / CricketData.org), and a Simulate picker (demo mode only).
With Simulate you can preview every state: live, innings break, rain delay, a match starting soon, match ended, no live matches, nothing scheduled, API error and offline.
The website (any device)
https://cricketscore-server.vercel.app works on Windows, macOS, iPhone and Android, with the same live ball-by-ball data and FOUR / SIX / WICKET animations:
| Feature | How |
|---|
| Follow teams | Tap ☆ next to a team. Their matches are starred, listed first and opened automatically; links to a specific match are always respected. |
| Alerts | Alerts button → browser notifications for your teams' wickets, starts and results, plus 4s, 6s and wickets when the tab is in the background. In-page toasts when the tab is visible. On iPhone, install to the Home Screen first. |
| Pop out | A small always-on-top scoreboard window: Document Picture-in-Picture in Chrome/Edge, with a canvas + video Picture-in-Picture fallback for Safari. |
| Install app | One click in Chrome/Edge (desktop and Android). Device-specific steps elsewhere: Safari → File → Add to Dock; iPhone → Share → Add to Home Screen. A service worker provides installability, an offline shell and Android notifications. Live scores are never cached. |
Code: server/public/ (app.js page logic, features.js favorites/alerts/pop-out/install, lib/ data layer, sw.js).
Live ball-by-ball data — no server, no API key
Scores come from ESPNcricinfo's public, CORS-enabled JSON feed, read directly by each user's device — exactly how ESPN's own website works:
ESPNcricinfo public feed ──▶ each visitor's browser (website: server/public, a static site)
└─▶ each user's Mac app (ESPNScoreProvider.swift)
- Nothing to host except static files, so there's nothing to rate-limit or block (ESPN refuses requests from cloud servers, but allows browsers and apps).
- Website data layer:
server/public/lib/ (espn.js adapter, scorecard.js, data.js) — plain ES modules shared by the browser and Node.
- Mac app:
CricketScore/Services/ESPN/ESPNScoreProvider.swift (default data source). Polls only while a match is live.
- Polite polling: every 6 s per open website tab (60 s when the tab is hidden), and at the app's refresh interval.
- To use a licensed provider later, replace the adapter (
espn.js / ESPNScoreProvider.swift); the UI doesn't change.
server/src/ still contains an optional always-on Node server (SSE push, /api/*) for self-hosting where it's allowed: cd server && npm start.
The feed is unofficial and ESPN's terms don't grant reuse rights: keep the app free and non-commercial, credit ESPNcricinfo, and switch to a licensed feed before charging money or running ads.
Shipping to the public (free)
Website
Hosted on Vercel from this repo (Root Directory server, framework Other). Every git push to main redeploys. It's a static site and installable as an app (PWA): Safari → File → Add to Dock, Chrome → Install, or Add to Home Screen on phones.
Mac app — free, no Apple Developer account
SERVER_URL="https://cricketscore-server.vercel.app" ./Scripts/release.sh 1.0.1 "What's new"
git add server/public/version.json && git commit -m "Release 1.0.1" && git push
This builds a universal (Apple Silicon + Intel) app with only the Command Line Tools, packages CricketScore.dmg (with a "How to open" note), uploads it as a GitHub Release (requires gh auth login), and updates version.json on the website. The permanent download link is https://github.com/trilochan06/CricketScore/releases/latest/download/CricketScore.dmg. The site's Download for Mac button and one-time "Open Anyway" instructions appear automatically, and installed apps show "Update available" within a day.
Because the app isn't notarized, each user approves it once: open it → Done → System Settings → Privacy & Security → Open Anyway.
Optional: signed & notarized (no warning at all)
Requires the Apple Developer Program ($99/year) and Xcode. Create a Developer ID Application certificate, run
xcrun notarytool store-credentials CricketScoreNotary --apple-id … --team-id … --password <app-specific>, then add
SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" to the release command. Credentials stay in your keychain.
Using real data: where the API key goes
The app ships with a provider for CricketData.org (formerly CricAPI). It has a free tier.
- Create a free account at cricketdata.org and copy your API key.
- Go to Settings → Data → Score provider, choose CricketData.org, paste the key and click Save.
The key goes into your macOS login Keychain (service CricketScore.CricketDataAPI). It is never written to source code, UserDefaults or the app bundle.
For development you can instead set the environment variable CRICKET_API_KEY. In Xcode: Product → Scheme → Edit Scheme → Run → Environment Variables. The shared scheme already has a disabled CRICKET_API_KEY entry, so you just fill it in and tick it. The environment variable takes priority over the Keychain.
Free-plan limits: about 100 requests/day. The live provider re-fetches the match list at most every 5 minutes and otherwise fetches only the selected match's scorecard. Polling happens only while a match is live. Even so, choose 60 seconds on the free plan. The free tier has no ball-by-ball feed, so Recent balls and the striker marker are hidden for real data.
Replacing the mock data / adding another API
The data layer is built around one protocol:
CricketScoreProvider (protocol) Services/CricketScoreProvider.swift
├─ MockCricketScoreProvider Services/Mock/ simulated, offline, no key
└─ LiveCricketScoreProvider Services/CricketData/ CricketData.org REST API
LiveMatchService polling, backoff, offline & sleep handling
ScoreViewModel selection, highlights, display state, visibility
SwiftUI views
protocol CricketScoreProvider: Sendable {
var displayName: String { get }
func fetchLiveMatches() async throws -> [CricketMatch]
func fetchScorecard(matchID: String) async throws -> Scorecard
// optional: isMock, requiresNetwork, minimumListRefreshInterval
}
To plug in a different API (e.g. Cricbuzz via RapidAPI, SportMonks, or your own backend):
- Write a type conforming to
CricketScoreProvider that maps the API's JSON into CricketMatch / Scorecard. Use LiveCricketScoreProvider as a template. If there's no data for something (e.g. recent balls), leave it empty and the UI hides that section.
- Add a case to
DataSource and return your provider from ProviderFactory.make(for:). This is the single switch point, in Services/CricketData/LiveCricketScoreProvider.swift.
- Keep secrets in
APIKeyStore (Keychain), not in code.
The default source is set in AppSettings (Key.dataSource: DataSource.demo).
How it works
- Floating widget: a borderless
NSPanel with .nonactivatingPanel, at .statusBar level. It uses canJoinAllSpaces + fullScreenAuxiliary + ignoresCycle, so it shows on every Space and over full-screen apps, and stays out of Cmd+Tab and Mission Control. canBecomeKey is false, so it never takes keyboard focus. The app is an LSUIElement (no Dock icon).
- Doesn't block clicks: the panel resizes to exactly the SwiftUI content size (measured with
onGeometryChange), so there's no invisible area over other apps. Growing happens immediately; shrinking waits for the collapse animation.
- Notch:
NSScreen.safeAreaInsets plus auxiliaryTopLeftArea/auxiliaryTopRightArea locate the camera housing. In Top Center on a notched Mac, the widget is black and flush with the top edge. Its content sits in two equal "wings" either side of the camera, and it expands downward. On Macs without a notch, and in Below Notch / Top Right, it's a blurred floating pill. Changing displays or resolution repositions it live.
- Performance: it polls only while a match is live. Otherwise it checks every ≤5 min, or as the next match starts. Errors trigger exponential backoff, and polling pauses while offline (
NWPathMonitor) or asleep. @Observable state is only assigned when values actually change, so views update only when their data does. There are no continuous animations. Relative timestamps tick every 5 s, and only while the widget is expanded. The measured idle footprint is about 66 MB RSS at 0% CPU.
- Animations: rolling digits on score changes, a FOUR/SIX/WICKET chip and outline glow, a pulse on the new ball, a spring expand/collapse, and staggered reveal. All of these respect Reduce Motion.
Project layout
CricketScore/
├── App/ CricketScoreApp (MenuBarExtra), AppDelegate, SnapshotRenderer (debug only)
├── Models/ Team, CricketMatch, Scorecard, Batter, Bowler, Delivery
├── Services/ CricketScoreProvider, LiveMatchService, Mock/, CricketData/
├── Settings/ AppSettings (UserDefaults), APIKeyStore (Keychain), LaunchAtLogin
├── ViewModels/ ScoreViewModel
├── Views/ ScoreOverlay, Collapsed/Expanded views, PlayersTable, RecentBalls, MatchSelector, Settings, Components/
├── Window/ FloatingPanel, OverlayController, OverlayLayout, ScreenGeometry, SettingsWindowController
├── MenuBar/ MenuBarView
└── Resources/ Info.plist, AppIcon.icns
Scripts/ build-app.sh, make-icon.swift
Development aids (Debug builds only)
swift build
CRICKETSCORE_SNAPSHOT_DIR=/tmp/shots .build/debug/CricketScore # PNG of every state × style × light/dark
CRICKETSCORE_SELFTEST=1 .build/debug/CricketScore # drives the real panel, logs window frames
Note on @ViewState
Views use @ViewState, a four-line wrapper around SwiftUI.State, instead of @State. In the macOS 26 SDK, @State is a compiler macro whose plugin ships with Xcode but not with the standalone Command Line Tools. The wrapper behaves identically and lets the project build either way. With Xcode installed you can switch back to @State if you prefer.
Test checklist
| Check | How it was verified |
|---|
| App launches; one floating window; menu bar icon | Launched CricketScore.app; window list shows exactly one panel |
| Widget at top, centred on the notch (notched MacBook Air, 1470×956) | Panel 391×32 pt at y=0, centred on the notch midpoint |
| Works without a notch / Top Right / Below Notch | Self-test: floating pill 6 pt under the menu bar; Top Right 10 pt from the edge |
| Collapsed ↔ expanded; window shrinks back afterwards | Self-test logs the frames (391×32 → 409×487 → 391×32) |
| Never steals keyboard focus | Self-test: app never active, panel never key |
| Innings break, rain, upcoming, ended, no matches, API error, offline | Rendered snapshots of every state in light and dark |
| Hide when nothing live; Pause/Show overlay | Self-test: panel hides and returns |
| Mock score updates, wickets, innings changes, results | Engine stress test: 90 full simulated matches, no invariant failures, no NaN/nil text |
| CricketData.org parsing | Decoded sample responses (numbers as strings, missing fields, all status types) |
| No warnings; low CPU/memory | Clean build; ~66 MB RSS, 0% CPU idle |
| Please check by hand | Real mouse clicks on the widget (automated clicks need Accessibility permission), dragging, the ⋮ menu, the Settings window, Launch at Login, and a live API key |
License
The code is released under the MIT License.
Cricket scores and commentary shown by the app and website come from ESPNcricinfo and are not covered by this license. This is an unofficial fan project, not affiliated with or endorsed by ESPN.
