screencap-bot/README.md

# screencap-bot

this is a cohost bot that periodically posts randomly-chosen
screencaps from a configured collection of tv series/movies.

## installation

you can build screencap-bot with cargo by cloning this repo, or
install it as a Nix Flake.  it needs the ffmpeg library, and also
needs the ffmpeg binary in its `PATH` when it's running.  the default
package provided by the flake is a wrapped version that adds ffmpeg to
its `PATH` for you.

## configuration

screencap-bot is configured with the following environment variables,
which can also be put in a `.env` file in the program's working
directory:

- `SCREENCAP_BOT_SHOWS_FILE`: path of a YAML file specifying what shows to take screencaps from (default: `./shows.yaml`)
- `SCREENCAP_BOT_GLOBAL_TAGS`: tags to put on every post the bot makes, as a comma-separated list (eg `bot account,automated post,The Cohost Bot Feed`) (default: none)
- `SCREENCAP_BOT_POST_INTERVAL`: the interval between posts, in
  seconds (default: 0, post a single screencap and then exit)
- `SCREENCAP_BOT_COHOST_EMAIL`: the email address the bot should use to log into cohost
- `SCREENCAP_BOT_COHOST_PASSWORD`: the password the bot should use to log into cohost
- `SCREENCAP_BOT_COHOST_PAGE`: the cohost page the bot should post from
- `SCREENCAP_BOT_COHOST_DRAFT`: whether to create cohost posts as
  drafts, eg for testing (default: `false`)
- `SCREENCAP_BOT_18PLUS`: whether posts should be flagged as
  containing 18+ content (default: `false`). this can be overridden
  for individual shows, see below.
- `RUST_LOG`: log levels, for the app as a whole and/or for specific
  submodules/libraries. See
  [`env_logger`](https://docs.rs/env_logger/latest/env_logger/)'s
  documentation for details.

### shows

the list of shows the bot should take screencaps from is read from a YAML file with the following structure:

```yaml
Char's Counterattack:
  path: /home/user/media/Gundam_CCA.mkv
  weight: 2.5
Gundam 0079:
  path: /home/user/media/Mobile Suit Gundam 0079/
  tags:
    - MSG 0079
    - "0079"
    - First Gundam
MS IGLOO:
  path: /home/user/media/Gundam Igloo
  parts:
    1: The Hidden One Year War
    2: Apocalypse 0079
Gundam 0069:
  path: /home/user/media/Gundam 0069
  18+: true
```

each top-level key is a show title, which will be used in spoiler
warnings on posts and in image alt text.  each show has two keys:

- `path`: the path of a single video file, or the path of a directory
  containing numbered video files for each episode of a series. all of
  the episodes must be directly inside the directory, the bot will not
  traverse subdirectories to find files.
- `tags`: an optional list of tags to put on posts from this show.
- `parts`: an optional map of season numbers to season names.
  by default, if the bot detects episodes from multiple seasons in a directory,
  it will refer to them as "season [number]" in post CWs and image alt-text.
  this is a map rather than a list, since show season numbers may be 1-indexed or 0-indexed.
- `weight`: an optional weight for this show in the random sampling of
  shows. each show without a weight specified has a weight of `1.0`.
- `18+`: an optional setting for whether screencaps from this show
  should be flagged as containing 18+ content. if present, this takes
  precedence over the `SCREENCAP_BOT_18PLUS` environment variable.