https://github.com/mferretti27/scoreboard
Python Script to Display your Favorite Major League Sports Teams in Scoreboard Style
https://github.com/mferretti27/scoreboard
baseball basketball football hockey python sports
Last synced: about 2 months ago
JSON representation
Python Script to Display your Favorite Major League Sports Teams in Scoreboard Style
- Host: GitHub
- URL: https://github.com/mferretti27/scoreboard
- Owner: MFerretti27
- License: other
- Created: 2024-11-02T20:32:59.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-08T22:09:14.000Z (5 months ago)
- Last Synced: 2026-02-09T03:58:07.416Z (5 months ago)
- Topics: baseball, basketball, football, hockey, python, sports
- Language: Python
- Homepage:
- Size: 11.6 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# General Information
- Python Script to Display your Favorite Major League Sports Teams in Scoreboard Style
- Using FreeSimpleGUI for GUI interface (Free version of PySimpleGUI)
- [FreeSimpleGUI Documentation](https://docs.pysimplegui.com/en/latest/)
- List of API's used:
- ESPN API
- [MLB-StatsAPI](https://github.com/toddrob99/MLB-StatsAPI)
- [nba_api](https://github.com/swar/nba_api)
- [nhl-api-py](https://github.com/coreyjs/nhl-api-py)
# Screen Shots
Main menu Screen, used for add team, set display order, and change functionality of scoreboard, and updating code:
Screens when no teams are currently playing but have games scheduled:
Screens when teams are currently playing:
Screen when games are over:
If game is in a playoffs/champianship game, or in the Bonus/PowerPlay/RedZone it will show something like this:
## Controls
Pressing keys on the keyboard while script is running will trigger different actions.
Escape - Return to main menu.
Caps Lock - Stay on the current displayed team (only if multiple teams are playing).
Shift - Resume rotating between multiple teams.
Right Arrow - Turn on live data delay, this will put a delay on live data shown. The amount of delay is set in settings.
Left Arrow - Turn off live data delay, this will show live game info as soon as its available.
Up Arrow - Enter "No Spoiler Mode," hiding scores, records, and game details.
Down Arrow - Exit "No Spoiler Mode," showing scores, records, and game details.
## How to Run
Using Python run the main.py file e.g. ```python main.py```
- This file will create a virtual environment and install the all library dependencies needed for the scoreboard script to work (Other generic libraries should already be on your machine)
- When starting the main menu will be displayed, this is where you can add teams you want to follow, check for updates of code, change display order of teams, and change overall settings. The settings allow you to change what elements on the scoreboard are displayed, how long to display each team for, adding a delay in displaying live data to not be too fast.
- Press the Start button on main menu to start displaying teams selected.
- Press Escape on the keyboard to return to main menu or press escape while at main menu to quit.
## How Data is Collected
- Primary source: ESPN API.
- Secondary Source: MLBStats-API (baseball), nba_api (basketball), nhlapi (hockey).
- If only primary source fails:
- Tries backup APIs based on the sport, all data but Spread/OverUnder will still be displayed.
- A small message will appear in bottom right telling ESPN API failed (Only will be displayed for team that it failed for).
- If only secondary sources fail:
- Displays basic info from ESPN.
- Some details (last pitch thrown, bonus status, shots on goal, play by play, etc) might be missing but most data will still be displayed.
- A small message will appear in bottom right telling MLB/NBA/NFL/NHL API failed (Only will be displayed for team that it failed for).
- If all data fetching fails:
- Shows a clock until connection/data is restored.
- Logos are gotten when first running for the first time.
- If you need to re-download logos or resize images such as if a team has updated their logo, you can re-download logos and resize by selecting "Download/Resize Images when Starting" in settings.
- Any Game information that is more than a month away will not display.
## Main Screen
- The main screen allows you to:
- Update scoreboard.
- Pressing Update bottom will check Github if there is an update, if there is click it again to update.
- Restore to previous version.
- If update went wrong or critical issues arise in newest version you can restore to a previous software version you were on before.
- Every time you update scoreboard through update button it will save a local copy of older version in the same directory.
- Add teams from MLB, NBA, NHL, and NFL to be follow and display.
- Set the order of teams to be displayed.
- Change what is displayed (See Scoreboard screen section below to see what information can be displayed or not displayed on the scoreboard screen).
- Change functionality of scoreboard in settings section.
- You can set a delay for live data so that if watching on TV the scoreboard doesn’t update before TV has.
- How often each team is displayed on screen for.
- This can be done individually for when currently playing and when no team is playing.
- How often the scoreboard should update new information.
- This is only when no team is playing. If a team is playing it will update every few seconds to ensure the most information is captured and displayed. (Set delay if this is too fast and ahead of TV).
- How long team information should be displayed once game is over.
## Scoreboard Screen
- Home team will always display on the right.
- Scoreboard will prioritize games playing meaning if a game is finished/scheduled for later it won't display until no games are currently playing (Can be changed in settings).
- Scoreboard will always display team logos, score, game time/game status and teams names.
- Other generic elements below can be displayed or not displayed based of settings:
- Team season record.
- Betting Odds MoneyLine/OverUnder/Spread before the game has started.
- Venue of where game is being played before the game has started (stadium name).
- Date of when game finished.
- Series information for sports play a series of games (MLB, NBA, NHL).
- The broadcast network game is on, only if its national broadcast not local one.
- Sports specific elements can be displayed or not displayed based off settings:
- MLB
- Last pitch thrown.
- Batter Count.
- Image of bases showing what base is occupied.
- Hits and errors of each team.
- What inning the game is in.
- How many outs there are.
- Description of last play.
- NBA
- How many Timeouts each team has.
- If a team is in the bonus (If a team is in the bonus their score will go orange).
- Game Clock and quarter the game is in.
- Shooting stats of each team (3pt/FG made and attempted).
- Play by Play of the game.
- NHL
- The number of shots on goal each team has.
- If a team is on a power play (If a team is on a power play their score will go blue).
- Game Clock and period the game is in.
- Play by Play of the game.
- NFL
- How many Timeouts each team has.
- If a team is in the RedZone (If a team is in the RedZone their score will go red).
- What team has possession of the ball (What ever team has possession their score will be underlined).
- What down and yardage a team is at on the field.
- Game Clock and quarter the game is in.
## Clock Screen
- Displays a clock:
- If data fetching fails.
- If internet connection is lost.
- If none of selected teams have data to display.
- Automatically returns displaying team info:
- Once data fetching is successful.
- Internet connection is restored.
- One of selected teams has data to display.
- A message on clock screen will appear telling why clock is displaying.
## Requirements
- Python needs to be installed and in your PATH (install [HERE](https://www.python.org/downloads/))
- pip (usually installed with python) needs to be installed
- All other requirements are in requirements.txt file and will be installed when you run the main.py file in virtual environment.
Unique Libraries Script needs to be installed to work (these will be installed in virtual environment when running main.py):
- adafruit-circuitpython-ticks -- Used to keep track of when to fetch data and switch displaying teams
- FreeSimpleGUI -- Used to install Python GUI library
- pillow -- Used to resize logo images without losing quality
- requests -- Used for being able to grab data from ESPN API
- ruff -- Used for code quality rules for repo
- MLB-StatsAPI -- Used to get more MLB data and used as a backup if ESPN fetching fails for MLB
- nba_api -- Used to get more MLB data and used as a backup if ESPN fetching fails for MLB
- nhl-api-py -- Used to get more MLB data and used as a backup if ESPN fetching fails for MLB
- rapidfuzz -- Used to find best matches within lists
- orjson -- Used to send data between subprocess as JSON
## Hardware Recommended
- Raspberry PI (3b+ and up, the better the CPU the less lag displaying images)
- [Link](https://www.amazon.com/Raspberry-Pi-Quad-core-Cortex-A76-Processor/dp/B0CTQ3BQLS/ref=sxin_16_pa_sp_search_thematic_sspa?content-id=amzn1.sym.76d54fcc-2362-404d-ab9b-b0653e2b2239%3Aamzn1.sym.76d54fcc-2362-404d-ab9b-b0653e2b2239&crid=2W4WOFMA7GQFC&cv_ct_cx=raspberry%2Bpi%2B5&dib=eyJ2IjoiMSJ9.9Y9spcqJNnOBeHLQWNTS41xuiL-91jGxokGdWfYaXkN26OVp-gUsmv2kqlxliXXA.-RF009atOtVOBvjkGi-tAig15vDCYjL13yHoA8iGsX0&dib_tag=se&keywords=raspberry%2Bpi%2B5&pd_rd_i=B0CTQ3BQLS&pd_rd_r=a22d1f2f-599f-4cb8-8e5d-9832619347b6&pd_rd_w=go2DS&pd_rd_wg=aZn7Y&pf_rd_p=76d54fcc-2362-404d-ab9b-b0653e2b2239&pf_rd_r=FEB2SVV839B11Z6QKJBH&qid=1731383117&s=electronics&sbo=RZvfv%2F%2FHxDF%2BO5021pAnSA%3D%3D&sprefix=ras%2Celectronics%2C190&sr=1-1-6024b2a3-78e4-4fed-8fed-e1613be3bcce-spons&sp_csd=d2lkZ2V0TmFtZT1zcF9zZWFyY2hfdGhlbWF0aWM&th=1)
- Monitor (22, 24, inch have been tested, use these for 100% known working without making any changes to code)
- 22 inch flat monitor [Link](https://www.amazon.com/dp/B0D17P8N28?ref=ppx_yo2ov_dt_b_fed_asin_title)
- 24 inch Asus monitor [Link](https://www.amazon.com/ASUS-VA24DQ-Adaptive-Sync-DisplayPort-Frameless/dp/B08C5MGFXQ/ref=sr_1_3?crid=3S3T4WEGS9F80&dib=eyJ2IjoiMSJ9.rmF77kGZWbFRIylLifYcthss5lyAUm4EJ3MCJ40pqPqk6E_p4qgSiCnLo3AtyHk0jlxasr3d1r7SRelS4QjWUlJ8WoVcpdJ8JIkxzzURDpKruZxWRjl2bgEddP3chNo-kYixRihIxsh7RNkkfIIuqltU9GVN0nA6SqcF4MWjIJIWxBeebZn1awc6QkvL0lgoY7ORZlWmoiBAFy58rvyO2zj6JnsciaG1HeKXFcKam3c.L37ENfD17MKaFgnxtCRUxVbtX79lT4SiDcT7y2hxc2w&dib_tag=se&keywords=asus+monitor&qid=1748050481&sprefix=asus+monitor%2Caps%2C202&sr=8-3&ufe=app_do%3Aamzn1.fos.9fe8cbfa-bf43-43d1-a707-3f4e65a4b666)
- 15 inch monitor [Link](https://www.amazon.com/Portable-Ultra-Slim-External-Kickstand-Extender/dp/B0D8JXY8V3/ref=sr_1_1_sspa?crid=IXV836AAVTQY&dib=eyJ2IjoiMSJ9.JFwG8BAM9jkKSm3OAh4xtDYnh0VGDF3iuVvD2ln-HAvVOuW69xYNAH5kzbNq8sVzDK1D9IY5ceWZ-C0EX6IEkSRt8KxpAunjMeQ1XkfiD_zJF_Op2FScahvVyb7t43xlh5HS9T_ujfUZL-NmmMDqGHYFOEsPuZlkTO3SXRK3W1-kjzRWKU3O9FPoVypirbHmYjc_UcHbGqa0_bxOFUF_a1SV5TlbSs0jRIMzGs7JeL0.jqQ152DrfcMx0DyA7sv6mx2l9on_qiKtzkIPrQmWwRQ&dib_tag=se&keywords=ailrinni%2Bportable%2Bmonitor%2B-%2B15.6%2Binch%2Bfull%2Bhd%2B1080p%2Bips&qid=1748048739&sprefix=%2Caps%2C188&sr=8-1-spons&sp_csd=d2lkZ2V0TmFtZT1zcF9hdGY&th=1)
- Remote (Helpful when setting everything up on pi, navigating main menu, and controlling scoreboard - see controls section)
- [Link](https://www.amazon.com/dp/B06XHF7DNQ?ref=ppx_yo2ov_dt_b_fed_asin_title)
This code has been tested in the following operating systems, Debian (Raspberry Pi), Darwin (Mac) and Windows.
Text and images should auto size based on the monitor size you are using.
## Future Plans
- [ ] Support for college sports
- [ ] Improve main screen layout switching (Less flicker when navigating)
- [ ] Clean up code