From a297526867d77156adcd130a0317086e98e9c0d9 Mon Sep 17 00:00:00 2001 From: Qualis Svagtlys <45446348+Svagtlys@users.noreply.github.com> Date: Sat, 16 Dec 2023 21:51:08 -0600 Subject: [PATCH] Moving cron setup and intro to ytdl-sub from GH --- docs/source/conf.py | 24 ++-- docs/source/faq/index.rst | 59 ++++++++ .../getting_started/automating_downloads.rst | 131 ++++++++++++++++++ .../guides/getting_started/first_config.rst | 2 + .../guides/getting_started/first_sub.rst | 2 + docs/source/guides/getting_started/index.rst | 10 +- .../guides/getting_started/initial_setup.rst | 5 - docs/source/guides/install/docker.rst | 10 +- docs/source/guides/install/unraid.rst | 4 +- docs/source/index.rst | 18 ++- docs/source/introduction.rst | 38 +++++ 11 files changed, 265 insertions(+), 38 deletions(-) create mode 100644 docs/source/faq/index.rst create mode 100644 docs/source/guides/getting_started/automating_downloads.rst create mode 100644 docs/source/guides/getting_started/first_config.rst create mode 100644 docs/source/guides/getting_started/first_sub.rst delete mode 100644 docs/source/guides/getting_started/initial_setup.rst create mode 100644 docs/source/introduction.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 9c199017..2f8487c9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -6,23 +6,24 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'ytdl-sub' -copyright = '2023, Jesse Bannon' -author = 'Jesse Bannon' -release = '2023.12.15' +project = "ytdl-sub" +copyright = "2023, Jesse Bannon" +author = "Jesse Bannon" +release = "2023.12.15" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ "sphinx.ext.autodoc", - ] + "sphinx_copybutton", + "sphinx_design", +] -templates_path = ['_templates'] +templates_path = ["_templates"] exclude_patterns = [] - # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output @@ -48,12 +49,5 @@ html_theme_options = { ), } -html_sidebars ={ - # "**": [ - # "globaltoc.html", - # "sourcelink.html", - # "searchbox.html" - # ], -} -html_static_path = ['_static'] +html_static_path = ["_static"] diff --git a/docs/source/faq/index.rst b/docs/source/faq/index.rst new file mode 100644 index 00000000..b4ad7273 --- /dev/null +++ b/docs/source/faq/index.rst @@ -0,0 +1,59 @@ +FAQ +=== + +Since ytdl-sub is relatively new to the public, there has not been many question asked yet. We will update this as +more questions get asked. + +.. contents:: Frequently Asked Questions + :depth: 3 + +How do I... +----------- + +...download age-restricted YouTube videos? +'''''''''''''''''''''''''''''''''''''''''' +See +`ytdls recommended way `_ +to download your YouTube cookie, then add it to your +`ytdl options `_ section of your config: + +.. code-block:: yaml + + ytdl_options: + cookiefile: "/path/to/cookies/file.txt" + +...automate my downloads? +''''''''''''''''''''''''' +`This part of the wiki `_ shows how to set up ``ytdl-sub`` to run in a cron job within Docker. + +There is a bug where... +----------------------- + +...date_range is not downloading older videos after I changed the range +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +Your preset most likely has ``break_on_existing`` set to True, which will stop downloading additional metadata/videos if the video exists in your download archive. Set the following in your config to skip downloading videos that exist instead of stopping altogether. + +.. code-block:: yaml + + ytdl_options: + break_on_existing: False + +After your download your new date_range duration, re-enable ``break_on_existing`` to speed up successive downloads. + +...it is downloading non-English title and description metadata +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +Most likely the video has a non-English language set to its 'native' language. You can tell yt-dlp to explicitly download English metadata using + +.. code-block:: yaml + + ytdl_options: + extractor_args: + youtube: + lang: + - "en" + +...Plex is not showing my TV shows correctly +'''''''''''''''''''''''''''''''''''''''''''' +Set the following +`Scanner and Agent `_ +for your library. \ No newline at end of file diff --git a/docs/source/guides/getting_started/automating_downloads.rst b/docs/source/guides/getting_started/automating_downloads.rst new file mode 100644 index 00000000..d20e63cb --- /dev/null +++ b/docs/source/guides/getting_started/automating_downloads.rst @@ -0,0 +1,131 @@ +Automating Downloads +==================== + +:ref:`docker-unraid-setup` + +:ref:`linux-setup` + +:ref:`windows-setup` + +.. _cron tab manpage: https://man7.org/linux/man-pages/man5/crontab.5.html#EXAMPLE_CRON_FILE + +.. _docker-unraid-setup: + +Docker and Unraid +----------------- + +.. tab-set:: + + .. tab-item:: GUI Image + + The script that will execute automatically is located at ``/config/ytdl-sub-configs/run-cron``. + + Access your container at http://localhost:8443/, then in the GUI terminal run these commands: + + .. code-block:: shell + + echo '#!/bin/bash' > /config/ytdl-sub-configs/run_cron + echo "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" >> /config/ytdl-sub-configs/run_cron + echo "echo 'Cron started, running ytdl-sub...'" >> /config/ytdl-sub-configs/run_cron + echo "cd /config/ytdl-sub-configs" >> /config/ytdl-sub-configs/run_cron + echo "ytdl-sub --config=config.yaml sub subscriptions.yaml" >> /config/ytdl-sub-configs/run_cron + chmod +x /config/ytdl-sub-configs/run_cron + chown abc:abc /config/ytdl-sub-configs/run_cron + + You can test the newly created script by running: + + .. code-block:: shell + + /config/ytdl-sub-configs/run_cron + + To create the cron definition, run the following command: + + .. code-block:: shell + + echo "# min hour day month weekday command" > /config/crontabs/abc + echo " 0 */6 * * * /config/ytdl-sub-configs/run_cron" >> /config/crontabs/abc + + This will run the script every 6 hours. To run every hour, change ``*/6`` to ``*/1``, or to run once a day, change the same value to the hour (in 24hr format) that you want it to run at. See the `cron tab manpage`_ for more options. + + .. tab-item:: Headless Image + + .. _LinuxServer's Universal Cron mod: https://github.com/linuxserver/docker-mods/tree/universal-cron + + The first step is to ensure you have `LinuxServer's Universal Cron mod`_ enabled via the environment variable. For the GUI image, this is already included (no need to add it). + + .. code-block:: yaml + + services: + ytdl-sub: + image: ghcr.io/jmbannon/ytdl-sub:latest + container_name: ytdl-sub + environment: + - PUID=1000 + - PGID=1000 + - TZ=America/Los_Angeles + - DOCKER_MODS=linuxserver/mods:universal-cron # <-- Make sure you have this! + volumes: + # ensure directories have user permissions + - :/config + - :/tv_shows + restart: unless-stopped + + This line will tell your container to install and enable cron on start. + + If you had to add this line, you will need to restart your container. + + .. code-block:: shell + + docker compose restart + + The script that will execute automatically is located at ``/config/run-cron``. + + Access your container from the terminal by running: + + .. code-block:: shell + + docker exec -itu abc ytdl-sub /bin/bash + + then in the terminal run these commands: + + .. code-block:: shell + + echo '#!/bin/bash' > /config/ytdl-sub-configs/run_cron + echo "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" >> /config/ytdl-sub-configs/run_cron + echo "echo 'Cron started, running ytdl-sub...'" >> /config/ytdl-sub-configs/run_cron + echo "cd /config/ytdl-sub-configs" >> /config/ytdl-sub-configs/run_cron + echo "ytdl-sub --config=config.yaml sub subscriptions.yaml" >> /config/ytdl-sub-configs/run_cron + chmod +x /config/ytdl-sub-configs/run_cron + chown abc:abc /config/ytdl-sub-configs/run_cron + + You can test the newly created script by running: + + .. code-block:: + + /config/run_cron + + To create the cron definition, run the following command: + + .. code-block:: shell + + echo "# min hour day month weekday command" > /config/crontabs/abc + echo " 0 */6 * * * /config/run_cron" >> /config/crontabs/abc + + This will run the script every 6 hours. To run every hour, change ``*/6`` to ``*/1``, or to run once a day, change the same value to the hour (in 24hr format) that you want it to run at. See the `cron tab manpage`_ for more options. + +.. _linux-setup: + +Linux +----- + + + +.. _windows-setup: + +Windows +------- +To be tested (please contact code owner or join the discord server if you can test this out for us) + +.. code-block:: powershell + + ytdl-sub.exe --config \path\to\config\config.yaml sub \path\to\config\subscriptions.yaml \ No newline at end of file diff --git a/docs/source/guides/getting_started/first_config.rst b/docs/source/guides/getting_started/first_config.rst new file mode 100644 index 00000000..41ca4cfd --- /dev/null +++ b/docs/source/guides/getting_started/first_config.rst @@ -0,0 +1,2 @@ +Initial Configuration +===================== diff --git a/docs/source/guides/getting_started/first_sub.rst b/docs/source/guides/getting_started/first_sub.rst new file mode 100644 index 00000000..a180c6f1 --- /dev/null +++ b/docs/source/guides/getting_started/first_sub.rst @@ -0,0 +1,2 @@ +Initial Subscriptions +===================== \ No newline at end of file diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index 112ee1e4..c9641e63 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -1,7 +1,15 @@ Getting Started =============== +Getting started involves a few steps: + +- Create your configuration file (if the :doc:`prebuilt_presets` don't work for you) +- Create your subscription file +- Automate starting YTDL-Sub + .. toctree:: - initial_setup + first_config + first_sub + automating_downloads prebuilt_presets examples \ No newline at end of file diff --git a/docs/source/guides/getting_started/initial_setup.rst b/docs/source/guides/getting_started/initial_setup.rst deleted file mode 100644 index b0584d52..00000000 --- a/docs/source/guides/getting_started/initial_setup.rst +++ /dev/null @@ -1,5 +0,0 @@ -Initial Setup -============= -If you haven't read it yet, it's highly recommended to go through our -`walk-through guide `_ -to get familiar with how ``ytdl-sub`` works. \ No newline at end of file diff --git a/docs/source/guides/install/docker.rst b/docs/source/guides/install/docker.rst index c85d2603..a0d28445 100644 --- a/docs/source/guides/install/docker.rst +++ b/docs/source/guides/install/docker.rst @@ -1,15 +1,17 @@ Docker ====== + Docker Compose -------------- +.. _LSIO-based images: https://www.linuxserver.io/ + The ytdl-sub Docker images use -`LSIO-based images `_ -and installs ytdl-sub on top. There are a few flavors to choose from. +`LSIO-based images`_ +and install ytdl-sub on top. There are two flavors to choose from. For automating ``subscriptions.yaml`` downloads to pull new media, see -`this guide `_ -on how set up a cron job in any of the docker containers. +:doc:`/guides/getting_started/automating_downloads` on how to set up a cron job in any of the docker containers. GUI ^^^^ diff --git a/docs/source/guides/install/unraid.rst b/docs/source/guides/install/unraid.rst index 5953a526..2dee6ad5 100644 --- a/docs/source/guides/install/unraid.rst +++ b/docs/source/guides/install/unraid.rst @@ -1,5 +1,3 @@ Unraid -------------- -See the -`community app `_ -``ytdl-sub``. Uses Docker under the hood. \ No newline at end of file +See the `community app `_ ``ytdl-sub``. Uses Docker under the hood. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 1f4e35eb..604e0570 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,21 +1,19 @@ -.. ytdl-sub documentation master file, created by - sphinx-quickstart on Fri Dec 15 21:08:10 2023. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to ytdl-sub's documentation! -==================================== +ytdl-sub User Guide +=================== .. toctree:: - :maxdepth: 1 + :maxdepth: 2 + introduction guides/index + faq/index config deprecation_notices presets usage -.. note:: End goal: https://picard-docs.musicbrainz.org/en/functions/list_by_type.html - +.. note:: End goal similar to: https://picard-docs.musicbrainz.org/en/functions/list_by_type.html + Initial plans: + - step-by-step noob install instructions for each platform - pages for each prebuilt preset, showing which variables that can be overridden to do different things (i.e. episode_title) - new wiki walkthrough that uses the README config as a starting point, and gradually adds custom changes diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst new file mode 100644 index 00000000..421162c9 --- /dev/null +++ b/docs/source/introduction.rst @@ -0,0 +1,38 @@ +What is ytdl-sub? +================= + +.. _yt-dlp: https://github.com/yt-dlp/yt-dlp +.. _kodi: https://github.com/xbmc/xbmc +.. _jellyfin: https://github.com/jellyfin/jellyfin +.. _plex: https://github.com/plexinc/pms-docker +.. _emby: https://github.com/plexinc/pms-docker + +``ytdl-sub`` is a command-line tool that downloads media via `yt-dlp`_ and prepares it for your favorite media player (`Kodi`_, `Jellyfin`_, `Plex`_, `Emby`_, modern music players). + +Visual examples +--------------- + +.. figure:: https://user-images.githubusercontent.com/10107080/182677243-b4184e51-9780-4094-bd40-ea4ff58555d0.PNG + + Youtube channels as TV shows in Jellyfin + +.. figure:: https://user-images.githubusercontent.com/10107080/182677256-43aeb029-0c3f-4648-9fd2-352b9666b262.PNG + + Music videos and concerts in Jellyfin + +.. figure:: https://user-images.githubusercontent.com/10107080/182677268-d1bf2ff0-9b9c-4a04-98ec-443a67ada734.png + + Music videos and concerts in Kodi + +.. figure:: https://user-images.githubusercontent.com/10107080/182685415-06adf477-3dd3-475d-bbcd-53b0152b9f0a.PNG + + SoundCloud albums and singles in MusicBee + + +Why ytdl-sub? +------------- +There is a lack of open-source tools to download media and generate metadata to play it in these players. Most solutions involve using multiple tools or bash scripts to achieve this. ``ytdl-sub`` aims to consolidate all of this logic into a single easy-to-use application that can run automatically once configured. + +Why download instead of stream? +------------------------------- +We believe it is important to download what you like because there is no guarantee it will stay online forever. We also believe it is important to download it in such a way that it is easy to consume. Most solutions today force you to watch/listen to your downloaded content via file system or web browser. ``ytdl-sub`` aims to format downloaded content for any media player. \ No newline at end of file