From cea21ca47f190cbc82cdf51c4fa0ec4cddebbcde Mon Sep 17 00:00:00 2001 From: Jesse Bannon Date: Fri, 2 Feb 2024 22:52:17 -0800 Subject: [PATCH] [DOCS] Add more configuration docs (#916) --- .../prebuilt_presets/common.rst | 15 +++++++ .../prebuilt_presets/helpers_common.rst | 7 ---- .../prebuilt_presets/helpers_players.rst | 7 ---- .../prebuilt_presets/helpers_url.rst | 7 ---- .../prebuilt_presets/index.rst | 8 ++-- .../prebuilt_presets/music.rst | 9 +++++ .../prebuilt_presets/tv_show.rst | 9 +++++ .../advanced_configuration.rst | 35 ++++++++++++++++ .../guides/getting_started/first_config.rst | 8 ++++ .../helpers/download_deletion_options.yaml | 40 ++++++++++++------- .../helpers/media_quality.yaml | 22 +++++++++- 11 files changed, 125 insertions(+), 42 deletions(-) create mode 100644 docs/source/config_reference/prebuilt_presets/common.rst delete mode 100644 docs/source/config_reference/prebuilt_presets/helpers_common.rst delete mode 100644 docs/source/config_reference/prebuilt_presets/helpers_players.rst delete mode 100644 docs/source/config_reference/prebuilt_presets/helpers_url.rst create mode 100644 docs/source/config_reference/prebuilt_presets/music.rst create mode 100644 docs/source/config_reference/prebuilt_presets/tv_show.rst diff --git a/docs/source/config_reference/prebuilt_presets/common.rst b/docs/source/config_reference/prebuilt_presets/common.rst new file mode 100644 index 00000000..0a6c8e8a --- /dev/null +++ b/docs/source/config_reference/prebuilt_presets/common.rst @@ -0,0 +1,15 @@ +======================= +Common +======================= + +.. highlight:: yaml + +Media Quality +------------- + +.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/media_quality.yaml + +Only Recent Videos +------------------ + +.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml \ No newline at end of file diff --git a/docs/source/config_reference/prebuilt_presets/helpers_common.rst b/docs/source/config_reference/prebuilt_presets/helpers_common.rst deleted file mode 100644 index 3dc5e105..00000000 --- a/docs/source/config_reference/prebuilt_presets/helpers_common.rst +++ /dev/null @@ -1,7 +0,0 @@ -======================= -Common Preset Reference -======================= - -.. highlight:: yaml - -.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/common.yaml diff --git a/docs/source/config_reference/prebuilt_presets/helpers_players.rst b/docs/source/config_reference/prebuilt_presets/helpers_players.rst deleted file mode 100644 index 404c38ab..00000000 --- a/docs/source/config_reference/prebuilt_presets/helpers_players.rst +++ /dev/null @@ -1,7 +0,0 @@ -======================== -Players Preset Reference -======================== - -.. highlight:: yaml - -.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/players.yaml diff --git a/docs/source/config_reference/prebuilt_presets/helpers_url.rst b/docs/source/config_reference/prebuilt_presets/helpers_url.rst deleted file mode 100644 index b6928288..00000000 --- a/docs/source/config_reference/prebuilt_presets/helpers_url.rst +++ /dev/null @@ -1,7 +0,0 @@ -==================== -URL Preset Reference -==================== - -.. highlight:: yaml - -.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/url.yaml diff --git a/docs/source/config_reference/prebuilt_presets/index.rst b/docs/source/config_reference/prebuilt_presets/index.rst index 9af49b74..d50cc51d 100644 --- a/docs/source/config_reference/prebuilt_presets/index.rst +++ b/docs/source/config_reference/prebuilt_presets/index.rst @@ -6,7 +6,7 @@ This section contains the code for the prebuilt presets. If you just want to und -.. toctree:: - helpers_common - helpers_players - helpers_url \ No newline at end of file +.. toctree:: + common + tv_show + music \ No newline at end of file diff --git a/docs/source/config_reference/prebuilt_presets/music.rst b/docs/source/config_reference/prebuilt_presets/music.rst new file mode 100644 index 00000000..dde4c28e --- /dev/null +++ b/docs/source/config_reference/prebuilt_presets/music.rst @@ -0,0 +1,9 @@ +===== +Music +===== + +All audio music based presets inherit from ``_music_base``. + +.. highlight:: yaml + +.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/music/singles.yaml \ No newline at end of file diff --git a/docs/source/config_reference/prebuilt_presets/tv_show.rst b/docs/source/config_reference/prebuilt_presets/tv_show.rst new file mode 100644 index 00000000..4cb993a3 --- /dev/null +++ b/docs/source/config_reference/prebuilt_presets/tv_show.rst @@ -0,0 +1,9 @@ +======================== +TV Show +======================== + +All TV show based presets inherit from ``_episode_base``. + +.. highlight:: yaml + +.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/tv_show/episode.yaml diff --git a/docs/source/guides/getting_started/advanced_configuration.rst b/docs/source/guides/getting_started/advanced_configuration.rst index 385ed3b7..e234b77a 100644 --- a/docs/source/guides/getting_started/advanced_configuration.rst +++ b/docs/source/guides/getting_started/advanced_configuration.rst @@ -16,6 +16,41 @@ The layout of the ``config.yaml`` file is relatively straightforward: plugin1: plugin1_option1: value1 +This creates a preset named ``preset_name``, which contains the made-up +:doc:`plugin ` ``plugin1``. Under each plugin are its settings. +A preset can contain multiple plugins. Preset Inheritance ------------------ + +You can modularize your presets via preset inheritance. For example, + +.. code-block:: yaml + + presets: + + TV Show: + presets: + - "Jellyfin TV Show by Date" + + overrides: + tv_show_directory: "/ytdl_sub_tv_shows" + + TV Show Only Recent: + presets: + - "TV Show" + - "Only Recent" + + overrides: + only_recent_date_range: "3weeks" + +This creates two presets: + +* ``TV Show`` + * Inherits the :doc:`prebuilt ` ``Jellyfin TV Show by Date`` preset + * Sets the output tv show directory +* ``TV Show Only Recent`` + * Inherits the ``TV Show`` preset made above it and the ``Only Recent`` prebuilt preset + * Sets only_recent preset to only keep the last 3 weeks worth of videos + +Inheritance makes it easy to extend existing presets to include logic for your specific needs. diff --git a/docs/source/guides/getting_started/first_config.rst b/docs/source/guides/getting_started/first_config.rst index 3deac497..a1bfbef8 100644 --- a/docs/source/guides/getting_started/first_config.rst +++ b/docs/source/guides/getting_started/first_config.rst @@ -9,6 +9,14 @@ Your first configuration will look pretty simple: configuration: working_directory: '.ytdl-sub-downloads' + presets: + TV Show: + preset: + - "Jellyfin TV Show by Date" + - "Only Recent" + + overrides: + tv_show_directory: "/ytdl_sub_tv_shows" The first two lines in this ``config.yaml`` file are the ``configuration``, and define the ``working_directory``, which is described near the bottom of :ref:`this section ` diff --git a/src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml b/src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml index ffb0f596..b62f73cd 100644 --- a/src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml +++ b/src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml @@ -1,18 +1,8 @@ presets: - "Only Recent": - preset: - - "Only Recent Archive" - # Only fetch videos after today minus date_range - - # Only keep files uploaded after date_range - output_options: - keep_files_after: "today-{only_recent_date_range}" - keep_max_files: "{only_recent_max_files}" - - overrides: - only_recent_max_files: 0 - + ############################################################################# + # Only Recent Archive + # Downloads only `date_range` amount of videos (no deletion) "Only Recent Archive": # Only fetch videos after today minus date_range @@ -23,9 +13,29 @@ presets: overrides: date_range: "2months" # keep for legacy-reasons only_recent_date_range: "{date_range}" - - chunk_initial_download: + ############################################################################# + # Only Recent + # Downloads only `date_range` amount of videos and deletes older videos + # that fall out of that range + + "Only Recent": + preset: + - "Only Recent Archive" + + output_options: + keep_files_after: "today-{only_recent_date_range}" + keep_max_files: "{only_recent_max_files}" + + overrides: + only_recent_max_files: 0 + + ############################################################################# + # Download in Chunks + # Will only download 20 videos per invocation of ytdl-sub, starting + # at the very beginning of the channel + + chunk_initial_download: # legacy preset name ytdl_options: max_downloads: 20 playlistreverse: True diff --git a/src/ytdl_sub/prebuilt_presets/helpers/media_quality.yaml b/src/ytdl_sub/prebuilt_presets/helpers/media_quality.yaml index 7bb5e53d..a4c35dc9 100644 --- a/src/ytdl_sub/prebuilt_presets/helpers/media_quality.yaml +++ b/src/ytdl_sub/prebuilt_presets/helpers/media_quality.yaml @@ -1,5 +1,9 @@ presets: + ############################################################################# + # Best Video Quality + # Gets the best available quality + best_video_quality: format: "bestvideo+bestaudio/best" ytdl_options: @@ -9,18 +13,26 @@ presets: preset: - best_video_quality + ############################################################################# + # Max 2160p "Max 2160p": format: "(bv*[height<=2160]+bestaudio/best[height<=2160])" ytdl_options: merge_output_format: "mp4" + ############################################################################# + # Max 1440p + "Max 1440p": format: "(bv*[height<=1440]+bestaudio/best[height<=1440])" ytdl_options: merge_output_format: "mp4" - max_1080p: + ############################################################################# + # Max 1080p + + max_1080p: # legacy name format: "(bv*[height<=1080]+bestaudio/best[height<=1080])" ytdl_options: merge_output_format: "mp4" @@ -28,12 +40,18 @@ presets: "Max 1080p": preset: - max_1080p - + + ############################################################################# + # Max 720p + "Max 720p": format: "(bv*[height<=720]+bestaudio/best[height<=720])" ytdl_options: merge_output_format: "mp4" + ############################################################################# + # Max 480p + "Max 480p": format: "(bv*[height<=480]+bestaudio/best[height<=480])" ytdl_options: