diff --git a/docs/config.rst b/docs/config.rst index f311bdd0..99c32953 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -131,6 +131,18 @@ nfo_output_directory :members: :member-order: bysource +------------------------------------------------------------------------------- + +subscription.yaml +----------------- +The ``subscription.yaml`` file is where we use our `presets`_ in the `config.yaml`_ +to define a `subscription`: something we want to recurrently download such as a specific +channel or playlist. + +The subscription file looks nearly identical to the `presets`_ section with a few +exceptions. TODO: work in progress! + + ------------------------------------------------------------------------------- .. _source-variables: diff --git a/examples/kodi_music_videos_config.yaml b/examples/kodi_music_videos_config.yaml index 74713673..6eb7aac8 100644 --- a/examples/kodi_music_videos_config.yaml +++ b/examples/kodi_music_videos_config.yaml @@ -16,7 +16,7 @@ configuration: working_directory: '.ytdl-sub-downloads' presets: - yt_music_video: + yt_music_video_playlist: # Youtube playlists are our source/download strategy. However, this # can be overwritten to download music videos from a 'channel' or a # single 'video' @@ -66,3 +66,11 @@ presets: overrides: music_video_directory: "path/to/Music Videos" music_video_name: "{sanitized_artist} - {sanitized_title}" + + # It is not always ideal to download all of an artist's music videos. + # Maybe you only like one song of theirs. We can reuse our preset above + # to download a single video instead. + yt_music_video: + preset: "yt_music_video_playlist" + youtube: + download_strategy: "video" diff --git a/examples/kodi_music_videos_subscriptions.yaml b/examples/kodi_music_videos_subscriptions.yaml index 3d718cd1..d6765e62 100644 --- a/examples/kodi_music_videos_subscriptions.yaml +++ b/examples/kodi_music_videos_subscriptions.yaml @@ -12,7 +12,7 @@ john_smith: # We must define a preset to use from our config. We named the one in the # config example "yt_music_video", so set that here. - preset: "yt_music_video" + preset: "yt_music_video_playlist" # Since our preset download strategy is set to 'playlist', set the playlist id. youtube: @@ -37,9 +37,8 @@ john_smith: # to download a single video instead. # # The only difference between this example and the one above is -# - youtube.download_strategy -# We defined this as 'playlist' in the config. We must override it -# with 'video' to perform a single video download +# - preset +# Use the music video preset, not the playlist preset # - youtube.video_id # The id of the video to download # @@ -48,18 +47,13 @@ john_smith: # command: # # ytdl-sub dl \ -# --preset "yt_channel_as_tv" \ -# --youtube.download_strategy "video" \ +# --preset "yt_music_video" \ # --youtube.video_id "QhY6r6oAErg" \ # --overrides.artist "John Smith and the Instrument Players" # -# The --preset and --youtube.download_strategy args will always be the -# same. We will try to simplify the dl command to make it shorter. - john_smith_one_hit_wonder: - preset: "yt_channel_as_tv" + preset: "yt_music_video" youtube: - download_strategy: "video" video_id: "QhY6r6oAErg" overrides: artist: "John Smith and the Instrument Players" diff --git a/examples/kodi_tv_shows_config.yaml b/examples/kodi_tv_shows_config.yaml index 5cb90197..64ea4a92 100644 --- a/examples/kodi_tv_shows_config.yaml +++ b/examples/kodi_tv_shows_config.yaml @@ -20,8 +20,14 @@ configuration: working_directory: '.ytdl-sub-downloads' presets: + + ############################################################################### + # LEVEL 1 - FULL ARCHIVE + # + # We will call this preset `yt_channel_as_tv`, and it will download every single video in + # a YouTube channel. yt_channel_as_tv: - # Youtube channels are our source/download strategy + # YouTube channels are our source/download strategy # Use the channel avatar and banner images for Kodi youtube: download_strategy: "channel" @@ -82,3 +88,53 @@ presets: overrides: youtube_tv_shows_directory: "/path/to/youtube_tv_shows" episode_name: "Season {upload_year}/s{upload_year}.e{upload_month_padded}{upload_day_padded} - {sanitized_title}" + + ############################################################################### + # LEVEL 2 - RECENT ARCHIVE + # + # It is not always ideal to go full data-hoarder on a channel's videos. + # This example shows how you can only download the last 14 days-worth + # of videos on each download invocation. + yt_channel_as_tv__recent: + # `preset` can be set to any other preset in the config, and will inherit all its defined fields. + # This helps reduce copy-paste in the config.yaml + preset: "yt_channel_as_tv" + + # We will add the `after` field onto `yt_channel_as_tv`'s YouTube channel download strategy. + # This is saying 'only download videos uploaded in the last 2 weeks' + youtube: + after: "today-2weeks" + + # This is getting into YTDL voodoo. By default, YTDL will try to + # download all channel videos beginning with the most recent one. + # By setting break_on_reject, we will break this full-download on + # the first video that gets rejected. Since we have youtube.after + # defined, all videos after today-14days will be rejected. Therefore, + # the first video that is out of range that it tries to download, it + # will stop there, and save a significant amount of time. + # + # Similar to break_on_reject, but instead, breaks if a video has + # already been downloaded. If you were to perform a download on this + # subscription one-after-the-other, the second invocation would stop + # after looking at the first (most recent) video since it would exist + # in the download archive. + ytdl_options: + break_on_reject: True + break_on_existing: True + + ############################################################################### + # LEVEL 3 - ROLLING ARCHIVE + + # If you put the recent archive example in a cron job, then in a year or so + # you will basically be datahoarding that channel unless you manually delete + # old videos. This example shows how to only keep the last 14-days worth of videos, + # and delete the rest. + yt_channel_as_tv__only_recent: + # Reuse `yt_channel_as_tv__recent` to only download the last 2 weeks' of videos + preset: "yt_channel_as_tv__recent" + + # This is saying "only keep files if they were uploaded in the last 2 weeks". + # All other files that this subscription had previously downloaded will be + # deleted. + output_options: + keep_files_after: "today-2weeks" \ No newline at end of file diff --git a/examples/kodi_tv_shows_subscriptions.yaml b/examples/kodi_tv_shows_subscriptions.yaml index c79de12c..b63023b9 100644 --- a/examples/kodi_tv_shows_subscriptions.yaml +++ b/examples/kodi_tv_shows_subscriptions.yaml @@ -4,13 +4,13 @@ ############################################################################### # LEVEL 1 - FULL ARCHIVE - +# # Subscription names are defined by you. We will call this one # john_smith_archive because it will download every single video in # john_smith's channel. john_smith_archive: - # We must define a preset to use from our config. We named the one in the - # config example "yt_channel_as_tv", so set that here. + # We must define a preset to use from our config. The one that downloads the + # entire YouTube channel is called "yt_channel_as_tv", so set that here. preset: "yt_channel_as_tv" # Our download strategy was Youtube channels. Define the channel id here @@ -28,61 +28,24 @@ john_smith_archive: ############################################################################### # LEVEL 2 - RECENT ARCHIVE - -# It is not always ideal to go full datahoarder on a channel's videos. -# This example shows how you can only download the last 14 days-worth -# of videos on each download invocation. # -# The only difference between this example and the one above is -# - youtube.after -# This is saying 'only download videos in the last 14 days' -# - ytdl_options.break_on_reject -# This is getting into YTDL voodoo. By default, YTDL will try to -# download all channel videos beginning with the most recent one. -# By setting break_on_reject, we will break this full-download on -# the first video that gets rejected. Since we have youtube.after -# defined, all videos after today-14days will be rejected. Therefore, -# the first video that is out of range that it tries to download, it -# will stop there, and save a significant amount of time. -# - ytdl_options.break_on_existing -# Similar to break_on_reject, but instead, breaks if a video has -# already been downloaded. If you were to perform a download on this -# subscription one-after-the-other, the second invocation would stop -# after looking at the first (most recent) video since it would exist -# in the download archive. +# Use the "yt_channel_as_tv__recent" preset to only download the last two +# weeks' worth of YouTube videos. john_smith_recent_archive: - preset: "yt_channel_as_tv" + preset: "yt_channel_as_tv__recent" youtube: channel_id: "UCsvn_Po0SmunchJYtttWpOxMg" - after: today-14days overrides: tv_show_name: "John /\ Smith" - ytdl_options: - break_on_reject: True - break_on_existing: True ############################################################################### # LEVEL 3 - ROLLING ARCHIVE - -# If you put the recent archive example in a cron job, then in a year or so -# you will basically be datahoarding that channel unless you manually delete -# old videos. We automate because we are lazy. This example shows how to -# only keep the last 14-days worth of videos, and delete the rest. # -# The only difference between this example and the one above is -# - output_options.keep_files_after -# This is saying "only keep files if they were uploaded in the last 14 days". -# All other files that this subscription had previously downloaded will be -# deleted. +# Use the "yt_channel_as_tv__recent_only" preset to only download the last two +# weeks' worth of YouTube videos, and delete any existing older videos. john_smith_rolling_archive: - preset: "yt_channel_as_tv" + preset: "yt_channel_as_tv__only_recent" youtube: channel_id: "UCsvn_Po0SmunchJYtttWpOxMg" - after: today-2weeks overrides: - tv_show_name: "John /\ Smith" - ytdl_options: - break_on_reject: True - break_on_existing: True - output_options: - keep_files_after: today-2weeks \ No newline at end of file + tv_show_name: "John /\ Smith" \ No newline at end of file diff --git a/tests/e2e/youtube/test_channel_as_kodi_tv_show.py b/tests/e2e/youtube/test_channel_as_kodi_tv_show.py index ce52e46f..880ff9f2 100644 --- a/tests/e2e/youtube/test_channel_as_kodi_tv_show.py +++ b/tests/e2e/youtube/test_channel_as_kodi_tv_show.py @@ -139,11 +139,8 @@ def recent_channel_subscription_dict(subscription_dict): return mergedeep.merge( subscription_dict, { + "preset": "yt_channel_as_tv__recent", "youtube": {"after": "20150101"}, - "ytdl_options": { - "break_on_reject": True, - "break_on_existing": True, - }, }, ) @@ -194,7 +191,11 @@ def expected_recent_channel_download(): @pytest.fixture def rolling_recent_channel_subscription_dict(recent_channel_subscription_dict): return mergedeep.merge( - recent_channel_subscription_dict, {"output_options": {"keep_files_after": "20181101"}} + recent_channel_subscription_dict, + { + "preset": "yt_channel_as_tv__only_recent", + "output_options": {"keep_files_after": "20181101"}, + }, )