docs: expand readme

README.md

@@ -1,11 +1,47 @@
 # subsyt
 
+## description
+
+`subsyt` is a wrapper around `yt-dlp`[1] to download youtube channels
+based on a OPML file containing all your subscriptions, sorting the
+channels into `{show}/{season}` folders, and generates `nfo` files,
+extracts thumbnails, downloads posters, banners, and fanart so the media
+should plug into media libraries well-enough, e.g. Jellyfin and Kodi.
+
+A quick rundown on how to use it:
+
+- download `subsyt` or build it into a binary yourself[2]
+- install `yt-dlp`[3]
+- patch it with POT support (POT optional -- yet recommended)[4]
+- generate and download a OPML file[5]
+- setup a config file[6]
+- run `subsyt`[7]
+
+[1]: https://github.com/yt-dlp/yt-dlp
+[2]: [install](#install)
+[3]: [ytdlp](#yt-dlp)
+[4]: [pot](#pot)
+[5]: [opml](#generate opml)
+[6]: [config](#config)
+[7]: [run](#running)
+
 ## install
 
 ```
 go install git.meatbag.se/varl/subsyt@latest
 ```
 
+## yt-dlp
+
+Install `pipx` on your system.
+
+```
+sudo apt install pipx           # debian
+sudo pacman -Syu python-pipx    # archlinux
+
+pipx install yt-dlp
+```
+
 ## running
 
 Configuration can be loaded from a file specified either by the env
@@ -40,7 +76,7 @@ out_dir = "./vids"                      # path to archive vids
 [provider]
 [provider.youtube]
 cmd = "./yt-dlp"                        # path to yt-dlp binary
-quality = "res:1080"                    # set the preferred quality
+quality = "res:1080"                    # set the preferred quality, blank for 1080
 output_path_template = "s%(upload_date>%Y)s/%(channel)s.s%(upload_date>%Y)Se%(upload_date>%m%d)S.%(title)s.%(id)s-1080p.%(ext)s"    # yt-dlp output template
 url = "https://www.youtube.com"         # full yt url
 throttle = 5                            # throttle yt request, 5s works well
@@ -48,14 +84,15 @@ range = "1:5:1"                         # downloads last 5 videos: [START][:STOP
 after_date = "20250326"                 # only download videos after date
 cookies_file = ""                       # pass user cookies to yt, blank to disable
 opml_file = "./opml.xml"                # the opml file to use
-po_token = ""                           # pass a proof-of-origin token
+po_token = ""                           # manually pass a proof-of-origin token, blank to disable
 verbose = true                          # debug info for provider
 ```
 
 ## generate opml
 
-E.g. https://github.com/jeb5/YouTube-Subscriptions-RSS
-`subs-opml.xml`:
+Use this javascript snippet:
+https://github.com/jeb5/YouTube-Subscriptions-RSS to generate a file
+that has the format:
 
 ```xml
 <?xml version="1.0"?>
@@ -81,26 +118,40 @@ E.g. https://github.com/jeb5/YouTube-Subscriptions-RSS
 > Your account **MAY** be banned when using cookies ! Consider using a
 > throw-away account.
 
-E.g. from Chromium:
+Install an extension that can download cookies per site, e.g. for
+firefox: https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/
+
+The steps for the browser is:
+
+1. install cookie export extension, allow in private mode
+1. open a private browsing session (e.g. incognito)
+1. go to youtube.com and login using a (throw-away) account
+1. export the cookies using extension, save to disk
+1. close private browsing session
+1. point `cookies_file` in `config.toml` to the cookies-file
+
+Cookies may need to be refreshed if/when they expire, if so, repeat
+steps 2-5.
+
+You can also `yt-dlp` to do it for you, though that exports all the
+cookies in the browser:
 
 ```
-yt-dlp --cookies-from-browser chromium --cookies cookies.txt
+yt-dlp --cookies-from-browser {browser} --cookies cookies.txt
 ```
 
-Or using an add-on: https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/
-
-## pot token
+## pot
 
 Youtube has started requiring proof-of-origin tokens for some players,
 and it may help not getting hit with the "sign in to confirm you are not
 a bot" together with cookies.
 
 Either add a manually generated POT to the config: `po_token =
-"{TOKEN}"` or, set up bgutils[1] with the youtube extractor to do POT
+"{TOKEN}"` or, set up bgutils[2] with the youtube extractor to do POT
 generation automatically.
 
 ```
-pipx install yt-dlp
+# assumes pipx was used to install yt-dlp
 pipx inject yt-dlp yt-dlp-get-pot
 pipx inject yt-dlp bgutil-ytdlp-pot-provider
 ```
@@ -122,7 +173,7 @@ On the same machine, run the bgutils http server, e.g. with compose:
 If using default ports and it's available on localhost, `yt-dlp` will
 pick up the plugin automatically and can be verified in the logs.
 
-[1]: https://github.com/Brainicism/bgutil-ytdlp-pot-provider
+[2]: https://github.com/Brainicism/bgutil-ytdlp-pot-provider
 
 ## scheduling