Initial commit, first working version

README.md

@@ -0,0 +1,93 @@
+# autosnatch
+Script to download either the latest episode, or a specific episode, of certain Beacon shows.
+
+- Currently only supports Critical Role and Critical Cooldown.
+- Intended for use on a remote server, but can absolutely be used locally.
+
+## What it does
+1. Downloads an episode of a supported Beacon.tv show using [`beacon-snatch`](https://github.com/RetroZelda/beacon-snatch).
+2. Grabs the thumnbail for the episode.
+3. Downloads + merges the subtitles and video into one file.
+
+### Why not just use `beacon-snatch`?
+1. While it _is_ the framework that holds up this bodge-job of a script, `beacon-snatch` works best when downloading a _specific_ episode. **autosnatch can grab the latest episode**, which allows it to be used easier in scenarios where you'd want to automate `beacon-snatch` to line up with Beacon.tv show release schedules.
+2. **`beacon-snatch` does not download the thumbnail.** If you plan on archiving episodes on a local media server (i.e. Jellyfin/Plex et al), this nay be important to you.
+3. Most importantly, `beacon-snatch` _does_ grab the URL for the subtitles stream, but **it does _not_ document a way to download it as part of a normal `beacon-snatch` operation.** As someone who is functionally hard of hearing, having autosnatch download the subs stream automatically is very important.
+    - They don't _need_ to be merged, but it makes the episode more portable + easier to manage for me.
+
+
+## Vague setup steps
+I'm not gonna document this properly. This is a personal project. I might document it later though.
+```bash
+# 1. Install xvfb (for headless operation)
+#    See https://github.com/ponty/PyVirtualDisplay for more info
+sudo apt-get install xvfb 
+
+# 2. Download autosnatch
+git clone https://git.gaycat.cloud/jess/autosnatch.git 
+cd autosnatch
+
+# 3. Set up Python virtualenv (ugh)
+python -m virtualenv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# 4. Create a new config file
+cp config.EXAMPLE.toml config.toml
+nano config.toml # Linux
+notepad config.toml # Windows
+
+# 5. Run autosnatch (see examples below)
+python -m scripts.dl $series $episodenumber
+```
+
+## Usage examples
+### Download the latest episode of Critical Role: Campaign 4
+```bash
+python -m scripts.dl campaign-4 latest
+```
+
+### Download episode no. 12 of Critical Cooldown
+```bash
+python -m scripts.dl critical-cooldown 12
+```
+
+### Example job to put in your crontab
+```shell
+1 14 * * 5 /home/exampleuser/autosnatch/scripts/remote-dl.sh
+```
+
+## Configuration
+In `config.toml`:
+```toml
+# The minimum error level to show in the terminal:
+# DEBUG, INFO, WARNING, ERROR, CRITICAL
+LOG_LEVEL = "INFO"
+
+# Soon to be deprecated lmao
+SHOW_NAME = false
+
+# Where to store the cache of episode lists
+CACHE_DIR = "cache"
+
+# The oldest the cache files can be before autosnatch generates a new one
+# during the next run
+CACHE_MAX_AGE = 48 # in hours
+
+# The folder where the video, subs, and thumbnail will be downloaded
+DL_ROOT = "downloads"
+
+# autosnatch merges the MP4 video and the subtitles into a new MKV video file.
+#Set to 'false' to prevent them from being deleted during the merge.
+DELETE_MP4_SRT_AFTER_DOWNLOAD = true
+
+# Your Beacon.tv account credentials. Must be a paid account.
+BEACON_EMAIL = "beacontrialemail@gmail.com"
+BEACON_PASSWORD = "Micaeah444?"
+```
+
+## A word on headless server operation
+This project uses [pyvirtualdisplay](https://github.com/ponty/PyVirtualDisplay), which allows us to open an invisible browser window on an invisible display buffer, for machines that do not _have_ a real display. Ensure you skim over its GitHub above for additional set-up steps or issues documented.
+
+## A word on Windows compatibility
+It's probably not. lmao. Test it and lmk, I guess.