mlb-rs/mlbt

A terminal user interface for the MLB stats API. Watch a baseball game in your terminal! ⚾

mlbt

A terminal user interface for the MLB Statcast API, written in Rust.

Check scores, standings, and stats. Even watch a live game using Gameday!

This project is under active development! See the v0.1.0 Milestone for more information, planned features, and known bugs.

Table of Contents

• What
• Installation
  • Homebrew
  • Binaries
  • Cargo
• Features
• Usage
  • Scoreboard
  • Gameday
  • Help
• Config
• Shout out
• Copyright Notice
• License

What

The MLB Statcast API is a publicly available (see its license information below) REST API that you can query to get back almost any information about a baseball game, past or present. If you've ever watched a baseball game on TV you've seen the data the API passes around in action. Two prime examples are the pitch/strike zone overlay, and home run stats (like distance and launch angle). This is accomplished by MLB's sophisticated Statcast vision system, which is implemented in every Major League ballpark.

This TUI is an interface for the API, with the intention of providing a light weight way to consume baseball data. See the features listed below for more details.

A TUI and baseball data make a pretty natural combination, at least compared to other sports. The Gameday view allows you to "watch" a live game by polling the API every 10 seconds. This matches the poll rate at which the official Gameday, found here, operates at. The goal with the TUI version is to mimic the official version as closely as possible.

Installation

WIP - more platform support

Homebrew

brew tap mlb-rs/mlbt
brew install mlbt

Binaries

macOS, Linux, and Windows binaries are available on the releases page.

Cargo

After cloning or downloading the source:

cargo install mlbt --path .

TODO - add to crates.io

Features

• scoreboard and box score

  • selectable date

• gameday

• standings

  • team information

• stats

  • player stats
  • team stats
  • stat search (store in sqlite or an embedded db?)

• CLI

• configuration:

  • favorite team
  • time zone
  • colors
  • keymap

Usage

There are four main tabs:

• Scoreboard
• Gameday
• Stats
• Standings

f - full screen (hide tabs)

Scoreboard

Press 1 to activate this tab.

• j: move down
• k: move up
• :: activate date picker

With the date picker active, input a date in the form of YYYY-MM-DD, or use the left/right arrow keys, and press Enter. This will display the schedule for that day. To view games for the current day, input today.

To switch the team displayed in the box score:

• h: home team
• a: away team

Gameday

Press 2 to activate this tab.

By default, the info and pitches panes are shown. However, each pane can be toggled on and off using:

• i: info pane
• p: pitches pane
• b: box score pane

To switch the team displayed in the box score:

• h: home team
• a: away team

Stats

Press 3 to activate this tab.

You can switch between pitching and hitting stats and filter based on team or player using:

• p: pitching
• h: hitting
• t: team
• l: player

Within each stat group (pitching or hitting) you can toggle the display of individual stat columns by selecting the stat with Enter. This selection pane can be turned on/off with o.

• j: move down
• k: move up
• Enter: toggle stat column
• o: toggle stat selection pane

If your terminal is too small to display all columns, they will be turned off starting from the left side.

Standings

Press 4 to activate this tab.

• j: move down
• k: move up
• Enter: display a teams roster TODO

Help

• ?: display help box
• Esc: close help box

If your terminal is too small to display the full help box, the border will be displayed red.

Config

You can configure the TUI with the toml file located at your users' home directory. For a user named Alice this would be:

• Linux: /home/alice/.config/mlbt/mlbt.toml
• Windows: C:\Users\Alice\AppData\Roaming\mlbt\mlbt.toml
• macOS: /Users/Alice/Library/Application Support/mlbt/mlbt.toml

you can see the path for your user in the Help page.

Available settings

• favorite_team: This will make that team always show up first in the schedule if they have a game that day. See here for options (note: use the full name and not the short name).

Example config

# See https://github.com/mlb-rs/mlbt#config for options
favorite_team = "Chicago Cubs"

Shout out

This is built with the wonderful tui-rs.

These TUIs were extremely helpful: spotify-tui, tickrs, bottom.

A reference MLB stats API client by toddrob99 helped make up for the lack of API documentation.

Copyright Notice

The data used in this application is supplied by the MLB's Stats API. Use of this data is subject to the license posted here: http://gdx.mlb.com/components/copyright.txt.

This application and its author are not affiliated with the MLB.

License

This project is under the MIT License.

mlbt's Issues

More build targets and packages

Builds:

• armv7
• musl

Packages:

• arch
• scoop

Boxscore mega thread

Issue for tracking all things needed for the box score. The first three are taken from issue #9

• add pitching information to box score
• display batter substitutions

For the player names I'm using the last string after splitting by white space. This leads to some wrong results, e.g. Fernando Tatis Jr. becomes Jr..

• Fix player name display

• Fix flickering when terminal is too small (issue #10)

• Make players selectable -> display player information on Enter

Gameday mega thread

Mega thread for everything that needs to happen for the Gameday view

• redo layout
• display information about plays that already happened that innning
• display pitches in the correct location
• show the team box score on the left
• show who's on deck, in the hole
• show pitcher/batter sides (LHP/RHP) (R/L)

I think I want to create a Gameday struct, with all of the individual components (matchup, heat map, pitches, ect.) as fields. This should clean up the layout generation and display quite a bit.

Make date selectable for schedule

Currently you can only view the current days schedule in the Scoreboard tab. It would be nice to be able to select the date so past scores can be checked.

Dynamically sized heatmap

The current sizing of the heat map doesn't display well on smaller sized terminals.

I think I need to calculate the size of the current terminal window and then change the size of the heat map accordingly. Additionally, there are 3 columns and 3 rows in the heat map, so the overall size of the heat map should be equally divisible by 3 (or just find closest number divisible by 3 for row and col size?).

Add Windows support

• switch to crossterm for the backend
• add Windows build to GH Action
• test on a Windows machine

rename GameDay to Gameday

Should rename all GameDay occurrences to Gameday. It seems this is the official name - see references in this blog post

Add standings layout

The standings tab needs to be completed still. This will require hitting the https://statsapi.mlb.com/api/v1/standings endpoint and then parsing the data. Should be relatively straight forward.

The layout will be based on a Table widget.

Switch to async in API

Table widths in small blocks

When tables, such as the line score and box score, are in a block that is smaller than the width of the table the columns that get displayed changes each redraw.

Solutions:

• Need to figure out the width of the block and then drop columns accordingly, or in the worst case, not display at all.
• On the line score, use the three letter team abbreviation instead of the team name.

Add configuration

I would like the TUI to be configurable for things such as:

• key map
• color scheme
• favorite team

This seems common in other TUI's so I will just base it off of those.

The favorite team selection should highlight the team in various modes, e.g. move the team to the top of the schedule and highlight the table row in the standings.

Cleveland Indians name change

Indians changed their name to the Guardians, and is causing a crash due to an unwrap() in the schedule parsing.

Get stuck in help menu

Pressing ? if you're already in the help menu makes it impossible to get out again, so you have to quit the app.

Gameday UI improvements

After PR #8 most of the major UI components are done. There are a few outstanding things I would like to dial though.

help

When the terminal height is small the help messages get cut off.

• Fix help popup. Maybe display as multiple columns.

strike zone

The strike zone gets distorted when the info or box score panes aren't shown.

• Constrain width for strike zone and pitch display

bad:

good:

box score

See images

• Add pitching information to boxscore

• Display batter substitutions

Add stats layout

The stats layout is a little complicated. I'm not sure exactly what stats to display yet, but will likely just mirror what can be found on MLB's website. I believe the endpoint is https://statsapi.mlb.com/api/v1/stats. The problem is you need query parameters to get back data. These come from the meta endpoints:

• https://statsapi.mlb.com/api/v1/statTypes
• https://statsapi.mlb.com/api/v1/statGroups

I've managed to build this query: https://statsapi.mlb.com/api/v1/stats?group=hitting&stats=sabermetrics,byDayOfWeek but more exploration is needed around the query parameters.

The UI will be based on a Table widget. I would like to add the ability to perform searches, e.g. batting vs pitching. These searches will likely correspond with what I discover with the API.