ytdl_options defaults for each download strategy

docker/root/defaults/config.yaml

@@ -13,9 +13,6 @@ presets:
     youtube:
       download_strategy: "video"
 
-    ytdl_options:
-      ignoreerrors: True
-
     output_options:
       output_directory: "{music_video_directory}"
       file_name: "{music_video_name}.{ext}"
@@ -45,6 +42,3 @@ presets:
 
     output_options:
       maintain_download_archive: True
-
-    ytdl_options:
-      break_on_existing: True

docs/config.rst

@@ -51,6 +51,8 @@ _______
   :inherited-members:
   :exclude-members: get_date_range
 
+.. autofunction:: ytdl_sub.downloaders.youtube_downloader.YoutubeChannelDownloader.ytdl_option_defaults()
+
 -------------------------------------------------------------------------------
 
 .. _YouTube Playlist:
@@ -62,6 +64,8 @@ ________
   :member-order: bysource
   :inherited-members:
 
+.. autofunction:: ytdl_sub.downloaders.youtube_downloader.YoutubePlaylistDownloader.ytdl_option_defaults()
+
 -------------------------------------------------------------------------------
 
 video
@@ -71,6 +75,8 @@ _____
   :member-order: bysource
   :inherited-members:
 
+.. autofunction:: ytdl_sub.downloaders.youtube_downloader.YoutubeVideoDownloader.ytdl_option_defaults()
+
 -------------------------------------------------------------------------------
 
 soundcloud
@@ -86,6 +92,8 @@ __________________
   :member-order: bysource
   :inherited-members:
 
+.. autofunction:: ytdl_sub.downloaders.soundcloud_downloader.SoundcloudAlbumsAndSinglesDownloader.ytdl_option_defaults()
+
 -------------------------------------------------------------------------------
 
 output_options

examples/kodi_music_videos_config.yaml

@@ -23,11 +23,13 @@ presets:
     youtube:
       download_strategy: "video"
 
-    # For advanced YTDL users only.
+    # For advanced YTDL users only; any YTDL parameter can be set here.
-    # It is wise to leave ignoreerrors=True to avoid errors for things
+    # To download age-restricted videos, you will need to set your cookie
-    # like age-restricted videos in case you have not set your cookie.
+    # file here as a ytdl parameter. For more info, see
-    ytdl_options:
+    # https://ytdl-sub.readthedocs.io/en/latest/faq.html#download-age-restricted-youtube-videos
-      ignoreerrors: True
+    #
+    # ytdl_options:
+    #   cookiefile: "path/to/cookie_file.txt
 
     # For each video downloaded, set the file and thumbnail name here.
     # We set both with {music_video_name}, which is a variable we define in
@@ -70,8 +72,3 @@ presets:
     output_options:
       maintain_download_archive: True
 
-    # Setting break_on_existing=True is also a good thing anytime you are using
-    # a download archive, because it will tell the downloader to stop trying
-    # to download videos that have already been downloaded.
-    ytdl_options:
-      break_on_existing: True

examples/kodi_tv_shows_config.yaml

@@ -22,10 +22,8 @@ configuration:
 presets:
 
   ###############################################################################
-  # LEVEL 1 - FULL ARCHIVE
+  # FULL ARCHIVE
-  #
+  # This preset will download every single video in a YouTube channel.
-  # 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
     # Use the channel avatar and banner images for Kodi
@@ -34,11 +32,13 @@ presets:
       channel_avatar_path: "poster.jpg"
       channel_banner_path: "fanart.jpg"
 
-    # For advanced YTDL users only.
+    # For advanced YTDL users only; any YTDL parameter can be set here.
-    # It is wise to leave ignoreerrors=True to avoid errors for things
+    # To download age-restricted videos, you will need to set your cookie
-    # like age-restricted videos in case you have not set your cookie.
+    # file here as a ytdl parameter. For more info, see
-    ytdl_options:
+    # https://ytdl-sub.readthedocs.io/en/latest/faq.html#download-age-restricted-youtube-videos
-      ignoreerrors: True
+    #
+    # ytdl_options:
+    #   cookiefile: "path/to/cookie_file.txt
 
     # For each video downloaded, set the file and thumbnail name here.
     # We set both with {episode_name}, which is a variable we define in
@@ -85,11 +85,9 @@ presets:
       episode_name: "Season {upload_year}/s{upload_year}.e{upload_month_padded}{upload_day_padded} - {title_sanitized}"
 
   ###############################################################################
-  # LEVEL 2 - RECENT ARCHIVE
+  # RECENT ARCHIVE
-  #
+  # This preset shows how you can download just the last 14 days-worth of videos
-  # It is not always ideal to go full data-hoarder on a channel's videos.
+  # on each download invocation.
-  # 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
@@ -100,30 +98,10 @@ presets:
     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
+  # ROLLING ARCHIVE
-
+  # This example shows how to only keep the last 14-days worth of videos, and
-  # If you put the recent archive example in a cron job, then in a year or so
+  # delete the rest.
-  # 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"

examples/soundcloud_discography_config.yaml

@@ -26,11 +26,11 @@ presets:
       download_strategy: "albums_and_singles"
       skip_premiere_tracks: True
 
-    # For advanced YTDL users only.
+    # For advanced YTDL users only; any YTDL parameter can be set here.
-    # This sets the download format to grab the best mp3 available.
+    # You can set the type of format you prefer YTDL to download here.
-    # Other formats should work but have not been tested.
+    # By default, soundcloud will download the best mp3.
-    ytdl_options:
+    # ytdl_options:
-      format: 'bestaudio[ext=mp3]'
+    #   format: 'bestaudio[ext=mp3]'
 
     # For each song downloaded, set the file and thumbnail name here.
     # The output directory stores all artists in a shared {music_directory}.

src/ytdl_sub/downloaders/downloader.py

@@ -48,8 +48,13 @@ class Downloader(Generic[DownloaderOptionsT, DownloaderEntryT], ABC):
 
     @classmethod
     def ytdl_option_defaults(cls) -> Dict:
-        """Downloader defaults that can be overwritten from user input"""
+        """
-        return {}
+        .. code-block:: yaml
+
+           ytdl_options:
+             ignoreerrors: True  # ignore errors like hidden videos, age restriction, etc
+        """
+        return {"ignoreerrors": True}
 
     @classmethod
     def _configure_ytdl_options(

src/ytdl_sub/downloaders/soundcloud_downloader.py

@@ -53,13 +53,6 @@ class SoundcloudDownloader(
 
     downloader_entry_type = SoundcloudTrack
 
-    @classmethod
-    def ytdl_option_defaults(cls) -> Dict:
-        """Returns default format to be best mp3"""
-        return {
-            "format": "bestaudio[ext=mp3]",
-        }
-
     @classmethod
     def artist_albums_url(cls, artist_url: str) -> str:
         """
@@ -124,6 +117,24 @@ class SoundcloudAlbumsAndSinglesDownloader(
 ):
     downloader_options_type = SoundcloudAlbumsAndSinglesDownloadOptions
 
+    @classmethod
+    def ytdl_option_defaults(cls) -> Dict:
+        """
+        Default `ytdl_options`_ for ``albums_and_singles``
+
+        .. code-block:: yaml
+
+           ytdl_options:
+             ignoreerrors: True  # ignore errors like hidden videos, age restriction, etc
+             format: "bestaudio[ext=mp3]"  # download format the best possible mp3
+        """
+        return dict(
+            super().ytdl_option_defaults(),
+            **{
+                "format": "bestaudio[ext=mp3]",
+            },
+        )
+
     def _get_albums(self, entry_dicts: List[Dict]) -> List[SoundcloudAlbum]:
         """
         Parameters

src/ytdl_sub/downloaders/youtube_downloader.py

@@ -95,6 +95,21 @@ class YoutubeVideoDownloader(YoutubeDownloader[YoutubeVideoDownloaderOptions, Yo
     downloader_options_type = YoutubeVideoDownloaderOptions
     downloader_entry_type = YoutubeVideo
 
+    @classmethod
+    def ytdl_option_defaults(cls) -> Dict:
+        """
+        Default `ytdl_options`_ for ``video``
+
+        .. code-block:: yaml
+
+           ytdl_options:
+             ignoreerrors: True  # ignore errors like hidden videos, age restriction, etc
+        """
+        return dict(
+            super().ytdl_option_defaults(),
+            **{"break_on_existing": True},
+        )
+
     def download(self) -> List[YoutubeVideo]:
         """Download a single Youtube video"""
         entry_dict = self.extract_info(url=self.download_options.video_url)
@@ -144,6 +159,25 @@ class YoutubePlaylistDownloader(
     downloader_options_type = YoutubePlaylistDownloaderOptions
     downloader_entry_type = YoutubePlaylistVideo
 
+    # pylint: disable=line-too-long
+    @classmethod
+    def ytdl_option_defaults(cls) -> Dict:
+        """
+        Default `ytdl_options`_ for ``playlist``
+
+        .. code-block:: yaml
+
+           ytdl_options:
+             ignoreerrors: True  # ignore errors like hidden videos, age restriction, etc
+             break_on_existing: True  # stop downloads (newest to oldest) if a video is already downloaded
+        """
+        return dict(
+            super().ytdl_option_defaults(),
+            **{"break_on_existing": True},
+        )
+
+    # pylint: enable=line-too-long
+
     def download(self) -> List[YoutubePlaylistVideo]:
         """
         Downloads all videos in a Youtube playlist
@@ -231,6 +265,29 @@ class YoutubeChannelDownloader(YoutubeDownloader[YoutubeChannelDownloaderOptions
     downloader_options_type = YoutubeChannelDownloaderOptions
     downloader_entry_type = YoutubeVideo
 
+    # pylint: disable=line-too-long
+    @classmethod
+    def ytdl_option_defaults(cls) -> Dict:
+        """
+        Default `ytdl_options`_ for ``channel``
+
+        .. code-block:: yaml
+
+           ytdl_options:
+             ignoreerrors: True  # ignore errors like hidden videos, age restriction, etc
+             break_on_existing: True  # stop downloads (newest to oldest) if a video is already downloaded
+             break_on_reject: True  # stops downloads if the video's upload date is out of the specified 'before'/'after' range
+        """
+        return dict(
+            super().ytdl_option_defaults(),
+            **{
+                "break_on_existing": True,
+                "break_on_reject": True,
+            },
+        )
+
+    # pylint: enable=line-too-long
+
     def __init__(
         self,
         working_directory: str,