mlblive-mastodon-scripts/README.md

# mlblive-mastodon-scripts
This repo contains some scripts to help automate posting live MLB game updates
to Mastodon.

## Structure
* `mlbgames.sh`, `mlbstartpost.sh`, and `mlbfinalpost.sh` are used to make a
  post at the start and end of games. `mlbgames.sh` populates the `games` table
of a SQLite database, which the play and highlight scripts read when running,
so you'll need to run `mlbgames.sh` if you want to use the other scripts.
* `mlbplaysave.sh` and `mlbplaypost.sh` are used in tandem to post scoring
  updates. The former saves new plays to a SQLite database, and the latter
reads the database and posts any scoring plays that have not been posted yet.
* `mlbhighlightsave.sh` and `mlbhighlightpost.sh` work similarly to the
  previous pair, but post video highlights instead.
* `posthighlights.sql`, `postplays.sql`, `poststart.sql`, and `postfinal.sql`
  are used by the posting scripts to select unposted data and then mark that
data as posted.
* `schema.sql` defines the table that new data gets saved to.

Note that there are invisible characters (like `0x1f`) in some of the files.
These are used as delimiters when processing the data.

## How to use
### Dependencies
To run these scripts, you'll need a few other programs:
* [mlblive](https://scm.dairydemon.net/filifa/mlblive), another program I wrote
  for retrieving data from MLB's Stats API
* `toot`, a CLI program for Mastodon
* `jq`, a program for processing JSON data
* `sqlite3` for saving and loading data
* some standard Unix programs (`sed`, `awk`, `curl`, etc.)

You may want to review the scripts yourself to see what you might be missing.

### Setup guidelines
Here's some high-level instructions to mirror the setup I use for these
scripts:
1. Put all the shell scripts somewhere convenient (I put them in
   `~/.local/bin`).
2. Pick a directory to keep the SQLite database in (I picked
   `~/.local/share/mlblive`).
3. Create the database with `sqlite3 <filename> < schema.sql`
    * I recommend making one database for plays and one for highlights
      (assuming you wish to process both) for each team you want to follow.
Separate databases for plays and highlights will reduce delays due to locking.
4. Put the other SQL scripts in the same directory as the database.
5. Review the shell scripts to see what arguments they require.
6. Write some systemd services and timers to execute the shell scripts
   automatically on some interval. Set the working directory to the directory
with the database.
    * I have `mlbsaveplays.sh` running as a simple service, and all the other
      scripts (games, highlights, `mlbpostplays.sh`) running as oneshot
services that execute on timers.