From 938bd236fb850be739890b41959345091dbff56f Mon Sep 17 00:00:00 2001 From: Viktor Varland Date: Sat, 12 Apr 2025 13:13:18 +0200 Subject: [PATCH] docs: expand readme --- README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 63 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 481374b..16408fb 100644 --- a/README.md +++ b/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 @@ -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