From dd87526987ff2966b89c34ea3ed4911e4e513d20 Mon Sep 17 00:00:00 2001 From: Ross Patterson Date: Sun, 17 Aug 2025 00:28:52 -0700 Subject: [PATCH] docs(quick): Add a rote quick start guide This is what I came up with when I tried to write instructions requiring as little understanding as possible. Doing so really did reinforce my impression that this just shouldn't be done, that significant understanding is required for *any* use of ytdl-sub and even offering a quick start may be irresponsible. I'm still on the fence, thoughts? That said, I also think I got some good explanations out of this and a better understanding of what the next bits of the Getting Started should be. This Quick Start is currently redundant with other parts of the Getting Started pages. I suspect that I'll end up repeating and/or reorganizing parts of this Quick Start into the next bits of the Getting Started. To that end I might argue that this change is a WIP and that merging should wait. But I could also argue that this is an incremental improvement and can be merged before that other work. Your call. --- docker/root/defaults/subscriptions.yaml | 72 ++++++++++--------- .../guides/getting_started/quick_start.rst | 70 +++++++++++++++++- tests/unit/config/test_subscription.py | 2 +- 3 files changed, 107 insertions(+), 37 deletions(-) diff --git a/docker/root/defaults/subscriptions.yaml b/docker/root/defaults/subscriptions.yaml index a7e129dc..98535e27 100644 --- a/docker/root/defaults/subscriptions.yaml +++ b/docker/root/defaults/subscriptions.yaml @@ -15,12 +15,12 @@ __preset__: music_video_directory: "/music_videos" # For 'Only Recent' preset, only keep vids within this range and limit - only_recent_date_range: "2months" - only_recent_max_files: 30 + # only_recent_date_range: "2months" + # only_recent_max_files: 30 # Pass any arg directly to yt-dlp's Python API - ytdl_options: - cookiefile: "/config/cookie.txt" + # ytdl_options: + # cookiefile: "/config/cookie.txt" ################################################################### # Subscriptions nested under this will use the @@ -35,52 +35,54 @@ Plex TV Show by Date: # Sets genre tag to "Documentaries" = Documentaries: "NOVA PBS": "https://www.youtube.com/@novapbs" - "National Geographic": "https://www.youtube.com/@NatGeo" - "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U" + # "National Geographic": "https://www.youtube.com/@NatGeo" + # "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U" # Sets genre tag to "Kids", "TV-Y" for content rating - = Kids | = TV-Y: - "Jake Trains": "https://www.youtube.com/@JakeTrains" - "Kids Toys Play": "https://www.youtube.com/@KidsToysPlayChannel" + # = Kids | = TV-Y: + # "Jake Trains": "https://www.youtube.com/@JakeTrains" + # "Kids Toys Play": "https://www.youtube.com/@KidsToysPlayChannel" - = Music: - # TV show subscriptions can support multiple urls and store in the same TV Show - "Rick Beato": - - "https://www.youtube.com/@RickBeato" - - "https://www.youtube.com/@rickbeato240" + # = Music: + # # TV show subscriptions can support multiple urls and store in the same TV Show + # "Rick Beato": + # - "https://www.youtube.com/@RickBeato" + # - "https://www.youtube.com/@rickbeato240" # Set genre tag to "News", use `Only Recent` preset to only store videos uploaded recently - = News | Only Recent: - "BBC News": "https://www.youtube.com/@BBCNews" + # = News | Only Recent: + # "BBC News": "https://www.youtube.com/@BBCNews" ################################################################### # Subscriptions nested under these will use the various prebuilt # music presets -YouTube Releases: - = Jazz: # Sets genre tag to "Jazz" - "Thelonious Monk": "https://www.youtube.com/@theloniousmonk3870/releases" -YouTube Full Albums: - = Lofi: - "Game Chops": "https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i" +# YouTube Releases: +# = Jazz: # Sets genre tag to "Jazz" +# "Thelonious Monk": "https://www.youtube.com/@theloniousmonk3870/releases" -SoundCloud Discography: - = Chill Hop: - "UKNOWY": "https://soundcloud.com/uknowymunich" - = Synthwave: - "Lazerdiscs Records": "https://soundcloud.com/lazerdiscsrecords" - "Earmake": "https://soundcloud.com/earmake" +# YouTube Full Albums: +# = Lofi: +# "Game Chops": "https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i" -Bandcamp: - = Lofi: - "Emily Hopkins": "https://emilyharpist.bandcamp.com/" +# SoundCloud Discography: +# = Chill Hop: +# "UKNOWY": "https://soundcloud.com/uknowymunich" +# = Synthwave: +# "Lazerdiscs Records": "https://soundcloud.com/lazerdiscsrecords" +# "Earmake": "https://soundcloud.com/earmake" + +# Bandcamp: +# = Lofi: +# "Emily Hopkins": "https://emilyharpist.bandcamp.com/" ################################################################### # Can choose between: # - Plex Music Videos: # - Jellyfin Music Videos: # - Kodi Music Videos: -"Plex Music Videos": - = Pop: # Sets genre tag to "Pop" - "Rick Astley": "https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc" - "Michael Jackson": "https://www.youtube.com/playlist?list=OLAK5uy_mnY03zP6abNWH929q2XhGzWD_2uKJ_n8E" \ No newline at end of file + +# "Plex Music Videos": +# = Pop: # Sets genre tag to "Pop" +# "Rick Astley": "https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc" +# "Michael Jackson": "https://www.youtube.com/playlist?list=OLAK5uy_mnY03zP6abNWH929q2XhGzWD_2uKJ_n8E" diff --git a/docs/source/guides/getting_started/quick_start.rst b/docs/source/guides/getting_started/quick_start.rst index d5e93d58..d0c27169 100644 --- a/docs/source/guides/getting_started/quick_start.rst +++ b/docs/source/guides/getting_started/quick_start.rst @@ -1,4 +1,72 @@ Quick Start =========== -TODO +:ref:`Again `, if the following +serves all your needs, then you're probably better off with :ref:`one of the more +user-friendly yt-dlp wrappers available `. If you still want to +get ``ytdl-sub`` up and running quickly and without understanding, then follow these +instructions to the letter. + +#. Install using :ref:`the official Docker GUI image variant `. + +#. Update the paths for your media library: + + Edit :ref:`the subscriptions file `. Near the + top, under ``__preset__:`` and then ``overrides:``, update the values under the + ``*_directory:`` keys with the correct paths for your media library *as they appear + inside the container*. + +#. Select your media library software: + + Change the ``Plex TV Show by Date:`` *key itself* to the preset for your media + library software. See the comment above for the available options. + +#. Select the genre: + + Under the library software preset key from the previous step, change the ``= + Documentaries`` *key itself* to the genre for this subscription prefixed with ``= + ...``. When adding other subscriptions that have the same genre, place them under the + same key. + +#. Update the subscription name and URL: + + Under the genre key from the previous step, update the ``"NOVA PBS":`` key to the + directory name the downloaded files should be placed beneath. This directory will be + created under the ``tv_show_directory:`` from step #2. Then update the + ``"https://www.youtube.com/@novapbs"`` value to the URL of the channel or playlist + for this subscription. + +#. Preview what ``ytdl-sub`` would do for this subscription: + + Run the :ref:`'sub' sub-command ` but with the ``max_downloads`` + setting from ``yt-dlp`` along with the ``--dry-run`` and ``--match`` options from + ``ytdl-sub`` to minimize requests and prevent actual downloads. Be sure to update the + ``--match="..."`` value with the subscription name:: + + $ ytdl-sub --dry-run sub -o '--ytdl_options.max_downloads 3' --match="NOVA PBS" + + Examine the output carefully. + +#. Review the results of real downloads: + + Run it again without the ``--dry-run`` option to actually download media and place + the files in your library:: + + $ ytdl-sub sub -o '--ytdl_options.max_downloads 3' --match="NOVA PBS" + + Examine the output carefully, then examine how the downloads work in your + library. Repeat with a larger value for ``max_downloads`` and examine the output and + downloads again. + +#. Add the rest of your subscriptions: + + Repeat steps #4-7 for each of your subscriptions. Be sure to repeat the preview and + review steps for each subscription. In general, move slowly and carefully review + everything. It's best to catch issues early to avoid repeating downloads and to + minimize requests to avoid being throttled or banned by servers. + +#. Automate downloads: + + :ref:`Set up ytdl-sub to run periodically + `. diff --git a/tests/unit/config/test_subscription.py b/tests/unit/config/test_subscription.py index 8fbfac15..044509bf 100644 --- a/tests/unit/config/test_subscription.py +++ b/tests/unit/config/test_subscription.py @@ -545,4 +545,4 @@ def test_default_docker_config_and_subscriptions(): default_subs = Subscription.from_file_path( config=default_config, subscription_path=Path("docker/root/defaults/subscriptions.yaml") ) - assert len(default_subs) == 15 + assert len(default_subs) == 1