Simplify the README (#54)
* better readme * code block ytdl-sub * update links
This commit is contained in:
Jesse Bannon
GitHub
parent
8b336e6fb0
commit
a7524e1348
2 changed files with 64 additions and 152 deletions
198
README.md
198
README.md
|
|
@ -10,7 +10,7 @@ Automate downloading and adding metadata with YoutubeDL.
|
||||||
|
|
||||||
This package downloads media via
|
This package downloads media via
|
||||||
[yt-dlp](https://github.com/yt-dlp/yt-dlp)
|
[yt-dlp](https://github.com/yt-dlp/yt-dlp)
|
||||||
and prepares it for consumption in your favorite media player
|
and prepares it for your favorite media player
|
||||||
([Kodi](https://github.com/xbmc/xbmc),
|
([Kodi](https://github.com/xbmc/xbmc),
|
||||||
[Jellyfin](https://github.com/jellyfin/jellyfin),
|
[Jellyfin](https://github.com/jellyfin/jellyfin),
|
||||||
[Plex](https://github.com/plexinc/pms-docker),
|
[Plex](https://github.com/plexinc/pms-docker),
|
||||||
|
|
@ -19,43 +19,51 @@ modern music players).
|
||||||
|
|
||||||
We recognize that everyone stores their
|
We recognize that everyone stores their
|
||||||
media differently. Our approach for file and metadata formatting is to provide
|
media differently. Our approach for file and metadata formatting is to provide
|
||||||
maximum flexibility while maintaining simplicity. Read more about it
|
maximum flexibility while maintaining simplicity.
|
||||||
[here](https://ytdl-sub.readthedocs.io/en/latest/getting_started.html).
|
|
||||||
|
|
||||||
## Supported Features
|
## How it Works
|
||||||
Below lists supported download schemes. You can see our
|
`ytdl-sub` uses YAML configs to define a layout for how you want media to look
|
||||||
[various example configurations](https://github.com/jmbannon/ytdl-sub/tree/master/examples)
|
after it is downloaded. See our
|
||||||
to get an idea on how to use ytdl-sub to your liking.
|
[example configurations](https://github.com/jmbannon/ytdl-sub/tree/master/examples)
|
||||||
|
that we personally use and
|
||||||
|
[readthedocs](https://ytdl-sub.readthedocs.io/en/latest/config.html#)
|
||||||
|
for detailed information on specific sections or fields.
|
||||||
|
|
||||||
- Download any and all audio/video from a channel or playlist
|
Once configured, you can begin downloading using two different methods.
|
||||||
- Format videos to look like
|
|
||||||
- Movies
|
|
||||||
- TV Shows
|
|
||||||
- TV Show Seasons
|
|
||||||
- Music Videos
|
|
||||||
- Format and tag audio files to look like
|
|
||||||
- Albums, Singles
|
|
||||||
- Audiobooks
|
|
||||||
- Download thumbnails, channel avatars, and banners to set as
|
|
||||||
- Posters
|
|
||||||
- Fanart
|
|
||||||
- Banners
|
|
||||||
- Album Artwork
|
|
||||||
- Download a soundcloud artist's albums and singles
|
|
||||||
- Format the music tags and save any artwork for album covers
|
|
||||||
- Manually download a single audio/video file
|
|
||||||
- Reuse configs you have defined to format it as anything you like
|
|
||||||
- Only download recent audio/video, optionally remove old files
|
|
||||||
|
|
||||||
|
### Subscription
|
||||||
## Configuration
|
You can define a `subscriptions.yaml` for things to recurrently
|
||||||
Formatting video and audio files are defined by presets. The `{variables}` used
|
download, like a YouTube channel to pull new videos. It looks something like:
|
||||||
in the strings are derived from the media itself or defined by you in the `overrides`
|
```yaml
|
||||||
section. Below shows what a `config.yaml` and `subscription.yaml` look like to
|
john_smith_channel:
|
||||||
download a Youtube channel as a TV show with artwork. The files are formatted
|
preset: "yt_channel_as_tv"
|
||||||
to look like:
|
youtube:
|
||||||
|
channel_id: "UCsvn_Po0SmunchJYtttWpOxMg"
|
||||||
|
overrides:
|
||||||
|
tv_show_name: "John Smith Vlogs"
|
||||||
```
|
```
|
||||||
/path/to/youtube_tv_shows/Your Favorite YT Channel
|
The download can be performed using:
|
||||||
|
```shell
|
||||||
|
ytdl-sub sub subscription.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
### One-time Download
|
||||||
|
There are things we will only want to download once and never again, like
|
||||||
|
a one-hit wonder music video. Anything you can define in a subscription can be
|
||||||
|
defined using CLI arguments. This example is equivalent to the subscription
|
||||||
|
example above:
|
||||||
|
```shell
|
||||||
|
ytdl-sub dl \
|
||||||
|
--preset "yt_channel_as_tv" \
|
||||||
|
--youtube.channel_id "UCsvn_Po0SmunchJYtttWpOxMg" \
|
||||||
|
--overrides.tv_show_name "John Smith Vlogs"
|
||||||
|
```
|
||||||
|
|
||||||
|
After `ytdl-sub` runs, the end result would download and format the channel
|
||||||
|
files into something ready to be consumed by your favorite media player or
|
||||||
|
server:
|
||||||
|
```
|
||||||
|
/path/to/youtube_tv_shows/John Smith Vlogs
|
||||||
/Season 2021
|
/Season 2021
|
||||||
s2021.e0317 - St Pattys Day Video.jpg
|
s2021.e0317 - St Pattys Day Video.jpg
|
||||||
s2021.e0317 - St Pattys Day Video.mp4
|
s2021.e0317 - St Pattys Day Video.mp4
|
||||||
|
|
@ -69,113 +77,10 @@ to look like:
|
||||||
tvshow.nfo
|
tvshow.nfo
|
||||||
```
|
```
|
||||||
|
|
||||||
### config.yaml
|
|
||||||
The config file defines _how_ to download and format media. You can define any
|
|
||||||
number of presets to represent media how you see fit.
|
|
||||||
```yaml
|
|
||||||
configuration:
|
|
||||||
working_directory: '.ytdl-sub-downloads'
|
|
||||||
|
|
||||||
presets:
|
|
||||||
yt_channel_as_tv:
|
|
||||||
youtube:
|
|
||||||
download_strategy: "channel"
|
|
||||||
channel_avatar_path: "poster.jpg"
|
|
||||||
channel_banner_path: "fanart.jpg"
|
|
||||||
|
|
||||||
# Pass any ytdl parameter to the downloader. It is recommended to leave
|
|
||||||
# ignoreerrors=True for things like age-restricted or hidden videos.
|
|
||||||
ytdl_options:
|
|
||||||
ignoreerrors: True
|
|
||||||
|
|
||||||
output_options:
|
|
||||||
output_directory: "{youtube_tv_shows_directory}/{tv_show_name_sanitized}"
|
|
||||||
file_name: "{episode_name}.{ext}"
|
|
||||||
thumbnail_name: "{episode_name}.jpg"
|
|
||||||
maintain_download_archive: True
|
|
||||||
|
|
||||||
nfo_tags:
|
|
||||||
nfo_name: "{episode_name}.nfo"
|
|
||||||
nfo_root: "episodedetails"
|
|
||||||
tags:
|
|
||||||
title: "{title}"
|
|
||||||
season: "{upload_year}"
|
|
||||||
episode: "{upload_month}{upload_day_padded}"
|
|
||||||
plot: "{description}"
|
|
||||||
year: "{upload_year}"
|
|
||||||
aired: "{upload_date_standardized}"
|
|
||||||
|
|
||||||
output_directory_nfo_tags:
|
|
||||||
nfo_name: "tvshow.nfo"
|
|
||||||
nfo_root: "tvshow"
|
|
||||||
tags:
|
|
||||||
title: "{tv_show_name}"
|
|
||||||
|
|
||||||
overrides:
|
|
||||||
youtube_tv_shows_directory: "/path/to/youtube_tv_shows"
|
|
||||||
episode_name: "Season {upload_year}/s{upload_year}.e{upload_month_padded}{upload_day_padded} - {title_sanitized}"
|
|
||||||
```
|
|
||||||
|
|
||||||
#### subscription.yaml
|
|
||||||
The subscription file defines _what_ to download. Anything in the preset can be
|
|
||||||
overwritten by a subscription.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# Downloads the entire channel
|
|
||||||
john_smith_archive:
|
|
||||||
preset: "yt_channel_as_tv"
|
|
||||||
youtube:
|
|
||||||
channel_id: "UCsvn_Po0SmunchJYtttWpOxMg"
|
|
||||||
# Any user-defined override variables will automatically create a `_sanitized`
|
|
||||||
# variable name, which is safe to use for file names and paths.
|
|
||||||
# In this example, `tv_show_name` will produce `tv_show_name_sanitized`
|
|
||||||
overrides:
|
|
||||||
tv_show_name: "John /\ Smith"
|
|
||||||
|
|
||||||
# Downloads and only keeps videos uploaded in the last 2 weeks
|
|
||||||
john_doe_recent_archive:
|
|
||||||
preset: "yt_channel_as_tv"
|
|
||||||
youtube:
|
|
||||||
channel_id: "UCsvn_Po0SmunchJYtttWpOxMg"
|
|
||||||
after: "today-2weeks"
|
|
||||||
overrides:
|
|
||||||
tv_show_name: "John /\ Smith"
|
|
||||||
# Will stop looking at channel videos if it already exists or the upload date
|
|
||||||
# is out of range
|
|
||||||
ytdl_options:
|
|
||||||
break_on_existing: True
|
|
||||||
break_on_reject: True
|
|
||||||
output_options:
|
|
||||||
keep_files:
|
|
||||||
after: "today-2weeks"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
You can have multiple subscription files for better organizing. We can invoke
|
|
||||||
the subscription download using the command below. For cron jobs, this is the
|
|
||||||
recommended command to use.
|
|
||||||
```shell
|
|
||||||
ytdl-sub sub subscription.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
### One-time Downloads
|
|
||||||
There are things we want to download, but not subscribe to. In this case, you
|
|
||||||
can invoke `ytdl-sub dl` and add any fields like a subscription. This example is
|
|
||||||
equivalent to using the subscription yaml above, but without the yaml.
|
|
||||||
```shell
|
|
||||||
ytdl-sub dl \
|
|
||||||
--preset "yt_channel_as_tv" \
|
|
||||||
--youtube.channel_id "UCsvn_Po0SmunchJYtttWpOxMg" \
|
|
||||||
--overrides.tv_show_name "John /\ Smith"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
Once we are ready for our first release, we will add this package to pypi. Then,
|
|
||||||
we plan to create a docker image that uses the
|
|
||||||
[LinuxServer.io](https://www.linuxserver.io/)
|
|
||||||
base image, and hopefully become a part of their fleet someday.
|
|
||||||
|
|
||||||
Until then, you will have to clone this repo and run it using python 3.10
|
### Virtualenv
|
||||||
|
With a Python 3.10 virtual environment, you can clone and install the repo using
|
||||||
```commandline
|
```commandline
|
||||||
git clone https://github.com/jmbannon/ytdl-sub.git
|
git clone https://github.com/jmbannon/ytdl-sub.git
|
||||||
cd ytdl-sub
|
cd ytdl-sub
|
||||||
|
|
@ -183,14 +88,15 @@ cd ytdl-sub
|
||||||
pip install -e .
|
pip install -e .
|
||||||
```
|
```
|
||||||
|
|
||||||
## Additional Documentation
|
### Local Docker
|
||||||
We are actively working on documenting all ytdl-sub features
|
If you are familiar with
|
||||||
[within our readthedocs page](https://ytdl-sub.readthedocs.io/en/latest/).
|
[LinuxServer.io](https://www.linuxserver.io/),
|
||||||
It is still a work-in-progress, but you can still find some useful things
|
you will be happy to hear that we use their base image for our docker image.
|
||||||
in there.
|
Documentation on how to build the image locally can be found in the
|
||||||
|
[docker readme](https://github.com/jmbannon/ytdl-sub/tree/master/docker#running-ytdl-sub-in-docker).
|
||||||
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
There are many ways to contribute, even without coding. Please take a look in
|
There are many ways to contribute, even without coding. Please take a look in
|
||||||
our [Github Issues](https://github.com/jmbannon/ytdl-sub/issues) to ask
|
our [Github Issues](https://github.com/jmbannon/ytdl-sub/issues) to ask
|
||||||
questions, submit a feature request, or pick up a bug. I try to be responsive
|
questions, submit a feature request, or pick up a bug.
|
||||||
and provide constructive PR feedback to maintain excellent code quality ;)
|
|
||||||
|
|
|
||||||
|
|
@ -41,18 +41,24 @@ If you want to jump the gun to see how ytdl-sub can be configured to do these th
|
||||||
|
|
||||||
Install
|
Install
|
||||||
-------
|
-------
|
||||||
Once we are ready for our first release, we will add this package to pypi. Then,
|
|
||||||
we plan to create a docker image that uses the
|
|
||||||
`LinuxServer.io <https://www.linuxserver.io/>`_
|
|
||||||
base image, and hopefully become a part of their fleet someday.
|
|
||||||
|
|
||||||
Until then, you will have to clone this repo and run it using python 3.10
|
Virtualenv
|
||||||
|
__________
|
||||||
|
With a Python 3.10 virtual environment, you can clone and install the repo using
|
||||||
|
|
||||||
.. code-block:: Bash
|
.. code-block:: shell
|
||||||
|
|
||||||
git clone https://github.com/jmbannon/ytdl-sub.git
|
git clone https://github.com/jmbannon/ytdl-sub.git
|
||||||
cd ytdl-sub
|
cd ytdl-sub
|
||||||
|
|
||||||
pip install -e .
|
pip install -e .
|
||||||
|
|
||||||
|
Local Docker
|
||||||
|
____________
|
||||||
|
If you are familiar with
|
||||||
|
`LinuxServer.io <https://www.linuxserver.io/>`_,
|
||||||
|
you will be happy to hear that we use their base image for our docker image.
|
||||||
|
Documentation on how to build the image locally can be found in the repo's
|
||||||
|
`docker readme <https://github.com/jmbannon/ytdl-sub/tree/master/docker#running-ytdl-sub-in-docker>`_.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue