[DOCS] Update readthedocs to only contain config documentation (#206)
This commit is contained in:
Jesse Bannon
GitHub
parent
6d84e52467
commit
968fa47b0f
5 changed files with 14 additions and 270 deletions
|
|
@ -1,8 +1,6 @@
|
|||
Config
|
||||
======
|
||||
ytdl-sub is configured using a ``config.yaml`` file. You can view our
|
||||
:doc:`examples <examples>` and read detailed documentation for every configurable
|
||||
field below.
|
||||
ytdl-sub is configured using a ``config.yaml`` file.
|
||||
|
||||
.. _config_yaml:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,48 +0,0 @@
|
|||
Examples
|
||||
========
|
||||
|
||||
This page shows how you can use ytdl-sub for various use cases. These
|
||||
are the configs I personally use and have incorporated as part of the e2e tests.
|
||||
|
||||
Each example has a ``config.yaml`` and ``subscription.yaml``. The config defines
|
||||
`how` you format your media, whereas the subscription defines `what` you
|
||||
download plus some additional configuring if needed.
|
||||
|
||||
Also note that ``kodi`` examples are applicable for ``jellyfin``, ``emby``, and
|
||||
``plex`` with the
|
||||
`XBMC Movies <https://github.com/gboudreau/XBMCnfoMoviesImporter.bundle>`_
|
||||
or
|
||||
`XBMC TV Show <https://github.com/gboudreau/XBMCnfoTVImporter.bundle>`_
|
||||
Plex importer. We would like to improve Plex support, please chime in
|
||||
`here <https://github.com/jmbannon/ytdl-sub/issues/6>`_
|
||||
if you have experience with importing custom videos with metadata.
|
||||
|
||||
Kodi/Jellyfin TV Shows
|
||||
----------------------
|
||||
|
||||
config.yaml
|
||||
^^^^^^^^^^^
|
||||
|
||||
.. include:: ../examples/kodi_tv_shows_config.yaml
|
||||
:literal:
|
||||
|
||||
subscriptions.yaml
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: ../examples/kodi_tv_shows_subscriptions.yaml
|
||||
:literal:
|
||||
|
||||
Kodi/Jellyfin Music Videos
|
||||
--------------------------
|
||||
|
||||
config.yaml
|
||||
^^^^^^^^^^^
|
||||
|
||||
.. include:: ../examples/kodi_music_videos_config.yaml
|
||||
:literal:
|
||||
|
||||
subscriptions.yaml
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: ../examples/kodi_music_videos_subscriptions.yaml
|
||||
:literal:
|
||||
28
docs/faq.rst
28
docs/faq.rst
|
|
@ -1,28 +0,0 @@
|
|||
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 <https://github.com/ytdl-org/youtube-dl#how-do-i-pass-cookies-to-youtube-dl>`_
|
||||
to download your YouTube cookie, then add it to your
|
||||
:ref:`ytdl options <ytdl_options>` section of your config:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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.
|
||||
|
|
@ -1,179 +0,0 @@
|
|||
Getting Started
|
||||
===============
|
||||
|
||||
The goal of this app is automate the downloading and metadata creation of audio and video files, then place the files
|
||||
in a directory that gets read by your media player/server. Everyone stores and watches their media differently, so
|
||||
we strive for comprehensive and simplistic customization to fit all self-hosting needs.
|
||||
|
||||
Audio metadata is just a matter of adding tags to the audio file. The backend plugin we use supports practically every
|
||||
common audio file type, so there should (hopefully) be no issues getting audio recognized by your media player.
|
||||
|
||||
Video metadata on the other hand, is currently geared toward generating Kodi/Jellyfin/Emby NFO files. Plex uses metadata
|
||||
written within MP4 containers - we do not support that currently, but could be added as a plugin in the future.
|
||||
|
||||
Usage Ideas
|
||||
-----------
|
||||
Below is a list ways you can use ytdl-sub to download and consume different kinds of media in the representation you
|
||||
prefer.
|
||||
|
||||
* Download a Youtube channel
|
||||
* Store the channel as its own TV Show
|
||||
* Use the channel's avatar as the TV Show poster, banner as the fanart
|
||||
* Format the season and episodes as ``Season YYYY/sYYYY.eMMDD - Video Title.mp4`` to easily navigate videos by upload date
|
||||
* Store the channel as a single season under a TV Show shared with other channels
|
||||
* Only download audio, store it as a Podcast
|
||||
* Only keep video/audio uploaded in the last `N` days
|
||||
* Great for news or podcast based channels
|
||||
|
||||
* Download a Youtube playlist
|
||||
* Download an artist's music videos playlist, store each video as a Kodi/Jellyfin/Emby Music Video
|
||||
* Only download the audio, store the playlist as an album
|
||||
|
||||
* Manually download a single Youtube video
|
||||
* Store it as a Movie
|
||||
* Download a one-hit wonder and store it as a Kodi/Jellyfin/Emby Music Video
|
||||
|
||||
* Download a soundcloud artist's discography
|
||||
* Add tags and album cover images so it shows up nicely in your music player
|
||||
|
||||
If you want to jump the gun to see how ytdl-sub can be configured to do these things, head over to the
|
||||
:doc:`examples <examples>`.
|
||||
|
||||
Install
|
||||
-------
|
||||
|
||||
The ytdl-sub docker image uses
|
||||
`LinuxServer's <https://www.linuxserver.io/>`_
|
||||
`base alpine image <https://github.com/linuxserver/docker-baseimage-alpine>`_.
|
||||
It looks, feels, and operates like other LinuxServer images. This is the
|
||||
recommended way to use ytdl-sub.
|
||||
|
||||
Docker Compose
|
||||
______________
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
version: "2.1"
|
||||
services:
|
||||
ytdl-sub:
|
||||
image: ghcr.io/jmbannon/ytdl-sub:latest
|
||||
container_name: ytdl-sub
|
||||
environment:
|
||||
- PUID=1000
|
||||
- PGID=1000
|
||||
- TZ=America/Los_Angeles
|
||||
volumes:
|
||||
- <path/to/ytdl-sub/config>:/config
|
||||
- <path/to/tv_shows>:/tv_shows # optional
|
||||
- <path/to/movies>:/movies # optional
|
||||
- <path/to/music_videos>:/music_videos # optional
|
||||
- <path/to/music>:/music # optional
|
||||
restart: unless-stopped
|
||||
|
||||
Docker CLI
|
||||
__________
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run -d \
|
||||
--name=ytdl-sub \
|
||||
-e PUID=1000 \
|
||||
-e PGID=1000 \
|
||||
-e TZ=America/Los_Angeles \
|
||||
-v <path/to/ytdl-sub/config>:/config \
|
||||
-v <OPTIONAL/path/to/tv_shows>:/tv_shows \
|
||||
-v <OPTIONAL/path/to/movies>:/movies \
|
||||
-v <OPTIONAL/path/to/music_videos>:/music_videos \
|
||||
-v <OPTIONAL/path/to/music>:/music \
|
||||
--restart unless-stopped \
|
||||
ghcr.io/jmbannon/ytdl-sub:latest
|
||||
|
||||
|
||||
Building Docker Image Locally
|
||||
_____________________________
|
||||
|
||||
Run `make docker` in the root directory of this repo to build the image. This
|
||||
will build the python wheel and install it in the Dockerfile.
|
||||
|
||||
Virtualenv
|
||||
__________
|
||||
|
||||
With a Python 3.10 virtual environment, you can clone and install the repo using
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://github.com/jmbannon/ytdl-sub.git
|
||||
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:
|
||||
- </path/to/ytdl-sub/config>:/config
|
||||
- </path/to/ytdl-sub/crontab_files>:/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.
|
||||
|
|
@ -1,15 +1,19 @@
|
|||
ytdl-sub: to enjoy media in your favorite player
|
||||
================================================
|
||||
ytdl-sub readthedocs
|
||||
====================
|
||||
|
||||
ytdl-sub automates downloading media and preparing it for
|
||||
consumption in your favorite media player. It is
|
||||
`open-source <https://github.com/jmbannon/ytdl-sub>`_
|
||||
and written entirely in Python.
|
||||
Our readthedocs page is dedicated towards ytdl-sub config documentation.
|
||||
|
||||
If you are new to ytdl-sub, head over to the
|
||||
:doc:`Getting Started <getting_started>`
|
||||
page to see how you can use ytdl-sub, install, configure it
|
||||
to your liking, and start downloading.
|
||||
`GitHub Wiki <https://github.com/jmbannon/ytdl-sub/wiki>`_
|
||||
to see our
|
||||
`walkthrough <https://github.com/jmbannon/ytdl-sub/wiki/1.-Introduction>`_ and
|
||||
`FAQ <https://github.com/jmbannon/ytdl-sub/wiki/FAQ>`_. For full examples of
|
||||
ytdl-sub configs, check out the
|
||||
`examples directory <https://github.com/jmbannon/ytdl-sub/tree/master/examples>`_.
|
||||
|
||||
|
||||
For navigating config docs, use the left-side bar on the
|
||||
:ref:`config_yaml` page to find every available ytdl-sub field.
|
||||
|
||||
Contents
|
||||
========
|
||||
|
|
@ -17,7 +21,4 @@ Contents
|
|||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
getting_started
|
||||
config
|
||||
examples
|
||||
faq
|
||||
|
|
|
|||
Loading…
Reference in a new issue