diff --git a/README.md b/README.md index 7eafdf1b..7ed2215b 100644 --- a/README.md +++ b/README.md @@ -65,11 +65,11 @@ server. The `--dry-run` flag can be used to view file output before any download ``` /path/to/youtube_tv_shows/John Smith Vlogs /Season 2021 - s2021.e0317 - St Pattys Day Video.jpg - s2021.e0317 - St Pattys Day Video.mp4 - s2021.e0317 - St Pattys Day Video.nfo + s2021.e0317 - Pattys Day Video-thumb.jpg + s2021.e0317 - Pattys Day Video.mp4 + s2021.e0317 - Pattys Day Video.nfo /Season 2022 - s2022.e1225 - Merry Christmas.jpg + s2022.e1225 - Merry Christmas-thumb.jpg s2022.e1225 - Merry Christmas.mp4 s2022.e1225 - Merry Christmas.nfo poster.jpg diff --git a/docs/config.rst b/docs/config.rst index 855739c9..08db9eb0 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -4,6 +4,8 @@ ytdl-sub is configured using a ``config.yaml`` file. You can view our :doc:`examples ` and read detailed documentation for every configurable field below. +.. _config_yaml: + config.yaml ----------- @@ -190,6 +192,8 @@ nfo_output_directory ------------------------------------------------------------------------------- +.. _subscription_yaml: + subscription.yaml ----------------- The ``subscription.yaml`` file is where we use our `presets`_ in the `config.yaml`_ diff --git a/docs/faq.rst b/docs/faq.rst index 95cdc0f3..e849835a 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -22,3 +22,7 @@ to download your YouTube cookie, then add it to your ytdl_options: cookiefile: "/path/to/cookies/file.txt" + +...automate my downloads? +''''''''''''''''''''''''' +See :ref:`automated_downloads` on how to set up ``ytdl-sub`` to run in a cron job. diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 09d9d48f..a482e24e 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -106,3 +106,74 @@ With a Python 3.10 virtual environment, you can clone and install the repo using cd ytdl-sub pip install -e . + +.. _automated_downloads: + +Setting Up Automated Downloads +------------------------------ +Docker is the recommended way to use ``ytdl-sub`` because it is easy to set up a cron job to +automatically download files via cron job. Setting this up is quite easy since we use the +LinuxServer base image. + +Enabling crontab +________________ +Crontab is a utility for running cron jobs. To enable it in the docker image, add the following +file to ``/config/custom-services.d/cron``: + +.. code-block:: bash + + #!/usr/bin/with-contenv bash + /usr/sbin/crond -f -S -l 0 -c /etc/crontabs + +Creating the crontab file +_________________________ +LinuxServer creates the user ``abc`` in the docker container and assigns it the respective +``PUID`` and ``PGID`` permissions to it. We want the cron job to run as this user to ensure +downloaded files get these permissions instead of root permissions. + +To do this, we need to create the file ``/etc/crontabs/abc``. Since this path is not part +of the already mounted volume, we need to mount another path. In docker-compose, this looks +like: + +.. code-block:: yaml + + services: + ytdl-sub: + image: ghcr.io/jmbannon/ytdl-sub:latest + volumes: + - :/config + - :/etc/crontabs + ... + +Now that ``/path/to/ytdl-sub/crontab_files`` is mounted, we can create the ``abc`` crontab file +there: + +.. code-block:: bash + + # min hour day month weekday command + */20 * * * * /config/run_cron + +Creating the download script +____________________________ + +This will run the ``run_cron`` script every 20 minutes. The last step is to create this bash +script in ``/config/run_cron``. + +.. code-block:: bash + + #!/bin/bash + echo "Cron started, running ytdl-sub..." + ytdl-sub --config=/config/config.yaml sub /config/subscriptions.yaml + +Ensure this file is executable and has permissions for ``abc``: + +.. code-block:: bash + + # run as root + chmod +x /config/run_cron + chown abc:abc /config/run_cron + +This will use the :ref:`config_yaml` and download all subscriptions in :ref:`subscription_yaml`. + +You're done! You are now downloading your subscriptions every 20 minutes. New channel uploads, +videos added to a playlist, or soundcloud artist uploads can now be downloaded automatically. diff --git a/examples/kodi_music_videos_config.yaml b/examples/kodi_music_videos_config.yaml index 36c1306c..0ce8d1d8 100644 --- a/examples/kodi_music_videos_config.yaml +++ b/examples/kodi_music_videos_config.yaml @@ -4,10 +4,10 @@ # formatted as: # # /path/to/Music Videos -# Elton John - Rocketman.jpg +# Elton John - Rocketman-thumb.jpg # Elton John - Rocketman.mp4 # Elton John - Rocketman.nfo -# System of a Down - Chop Suey.jpg +# System of a Down - Chop Suey-thumb.jpg # System of a Down - Chop Suey.mp4 # System of a Down - Chop Suey.nfo # ... diff --git a/examples/kodi_tv_shows_config.yaml b/examples/kodi_tv_shows_config.yaml index 86b3f53a..2d4536cf 100644 --- a/examples/kodi_tv_shows_config.yaml +++ b/examples/kodi_tv_shows_config.yaml @@ -3,11 +3,11 @@ # # /path/to/youtube_tv_shows/My Favorite Youtube Channel # /Season 2021 -# s2021.e0317 - St Pattys Day Video.jpg -# s2021.e0317 - St Pattys Day Video.mp4 -# s2021.e0317 - St Pattys Day Video.nfo +# s2021.e0317 - Pattys Day Video-thumb.jpg +# s2021.e0317 - Pattys Day Video.mp4 +# s2021.e0317 - Pattys Day Video.nfo # /Season 2022 -# s2022.e1225 - Merry Christmas.jpg +# s2022.e1225 - Merry Christmas-thumb.jpg # s2022.e1225 - Merry Christmas.mp4 # s2022.e1225 - Merry Christmas.nfo # poster.jpg