Cohost bot for posting randomly selected screencaps and/or audio clips from TV series/movies
Go to file
2024-06-29 15:45:45 -04:00
src v1.6.0: more options around retrying after errors 2023-08-06 19:52:52 -04:00
.gitignore v1.1.0: optional season/part naming, draft mode 2023-07-05 12:29:26 -04:00
Cargo.lock update ffmpreg crate 2024-01-24 19:43:24 -05:00
Cargo.toml v1.6.0: more options around retrying after errors 2023-08-06 19:52:52 -04:00
flake.lock flake update 2024-01-24 19:43:46 -05:00
flake.nix symlinkJoin does specifically want a name though :/ 2024-06-29 15:45:45 -04:00
LICENSE LICENSE and README 2023-07-01 20:55:47 -04:00 v1.6.0: more options around retrying after errors 2023-08-06 19:52:52 -04:00


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


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.


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_CAPTURE_IMAGES: whether to take screenshots (default: true)
  • SCREENCAP_BOT_CAPTURE_AUDIO_DURATION: length of audio clips to capture, in seconds. if unset, or set to 0, audio will not be captured. (default: unset, no audio capture)
  • SCREENCAP_BOT_SUBTITLE_LANGUAGE: ISO-639-2 three-letter code for a subtitle language to embed in screenshots. if this is set to an empty string, or if a video doesn't have any subtitle track tagged with this language, no subtitles will be embedded. (default: eng)
  • SCREENCAP_BOT_AUDIO_LANGUAGE: ISO-639-2 three-letter code for an audio language to prefer when capturing audio clips. if this is unset, set to an empty string, or if a media file doesn't have any audio track tagged with this language, screencap-bot will choose an arbitrary audio track. (default: unset)
  • SCREENCAP_BOT_SHOWS_FILE: path of a YAML file specifying what shows to take captures 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 capture 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_COHOST_CW: whether to CW posts with the episode number (default: true if taking screenshots, false if not)
  • SCREENCAP_BOT_18PLUS: whether posts should be flagged as containing 18+ content (default: false). this can be overridden for individual shows, see below.
  • SCREENCAP_BOT_RETRY_DELAY: if taking a capture or creating a post fails, wait this number of seconds before retrying (default: 30)
  • SCREENCAP_BOT_MAX_RETRIES: maximum number of consecutive times to retry after a failure before exiting with an error. This can be set to 0 to never retry, or set to -1 to retry indefinitely. (default: 5)
  • RUST_LOG: log levels, for the app as a whole and/or for specific submodules/libraries. See env_logger's documentation for details.


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

Char's Counterattack:
  path: /home/user/media/Gundam_CCA.mkv
  weight: 2.5
Gundam 0079:
  path: /home/user/media/Mobile Suit Gundam 0079/
    - MSG 0079
    - "0079"
    - First Gundam
  path: /home/user/media/Gundam Igloo
    1: The Hidden One Year War
    2: Apocalypse 0079
Gundam 0069:
  path: /home/user/media/Gundam 0069
  18+: true
Friends at the Table:
  path: /home/user/media/Friends at the Table
    prefix: "Friends at the Table: "
    regex: '^\d{4}-\d{2}-\d{2} - (?<episode>.*)\.mp3$'

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.
  • custom_episodes: Rather than letting the bot auto-detect episode numbering, you can extract episode numbers from filenames using a regex.
    • regex: should match a filename, and capture the episode number or title in a capture group named episode. Files that don't match the regex will be ignored.
    • prefix: Will be prepended to whatever is captured by the regex. (default: empty string)