[DOCS] Clarifications for first time users (#1281)
* docs(docker): Clarify where the configuration is The docs move from installation with Docker straight to modifying the configuration without detailing where those files are. * docs(start): Defining comments is discracting This one is squarely me with my editor's red pen, do what you will. I whole heartedly agree with this statement about comments and the intention (I assume) to encourage new users to comment their configurations early and often. I just think this isn't the right place for it and makes this document less focused and effective. * docs(start): Less technical YAML key description * docs(intro): Update and clarify goals/motivation To help calibrate our collaboration, I went uninhibited with these changes including: - assumptions about history I don't actually know: "this project was one of the early entrants" - description of the yt-dlp/ytdl-sub division of labor I'm not actually certain about - max opinion, both about this project and the domain in general - max cheeky/fun writing tone, with the intention of being personable - max editor's red pen, cut mercilessly IOW, review carefully and reject early and often to help me submit future changes that require less review and revision. To that end, give me more rather than less feedback on this change in particular. I include an endorsement of Pinchflat because [they do the same for ytdl-sub](https://github.com/kieraneglin/pinchflat?tab=readme-ov-file#what-it-does). It would be my next choice if ytdl-sub couldn't meet my needs or vanquished me. More than that link, in other Reddit comments and the like, the Pinchflat author clearly expresses preference for ytdl-sub as their own "next option".
This commit is contained in:
Ross Patterson
GitHub
parent
6b86e5efdf
commit
2465acb451
5 changed files with 69 additions and 27 deletions
|
|
@ -52,7 +52,7 @@ All three types of keys are used for the following:
|
|||
- ``= News`` - an override value for genre
|
||||
- ``Breaking News``, ``BBC News`` - The subscription names
|
||||
|
||||
The bottom-most keys, or leaf keys, should always be the subscription name.
|
||||
The lowest level, most indented keys should always be the subscription name.
|
||||
It is good practice to put subscription names in quotes to differentiate
|
||||
between preset names and subscription names.
|
||||
|
||||
|
|
|
|||
|
|
@ -54,21 +54,6 @@ which are used by the presets below.
|
|||
set at the same indentation level as ``overrides``, not within it.
|
||||
|
||||
|
||||
-------------------------------------
|
||||
|
||||
.. code-block:: yaml
|
||||
:lineno-start: 6
|
||||
|
||||
# Can choose between:
|
||||
# - Plex TV Show by Date:
|
||||
# - Jellyfin TV Show by Date:
|
||||
# - Kodi TV Show by Date:
|
||||
#
|
||||
|
||||
Lines 6-10 are comments that get ignored when parsing YAML since they are prefixed with ``#``.
|
||||
It is good practice to leave informative comments in your config or subscription files to remind
|
||||
yourself of various things.
|
||||
|
||||
-------------------------------------
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -138,4 +123,4 @@ Referring to the
|
|||
:ref:`TV show preset reference <config_reference/prebuilt_presets/tv_show:TV Show>`, the first
|
||||
two indent variables map to the TV show genre and TV show content rating.
|
||||
|
||||
The above info should be enough to understand the rest of the subscription file.
|
||||
The above info should be enough to understand the rest of the subscription file.
|
||||
|
|
|
|||
|
|
@ -151,4 +151,12 @@ If you prefer to only run the container once, you can use the CLI command instea
|
|||
-v <OPTIONAL/path/to/movies>:/movies \
|
||||
-v <OPTIONAL/path/to/music_videos>:/music_videos \
|
||||
-v <OPTIONAL/path/to/music>:/music \
|
||||
ghcr.io/jmbannon/ytdl-sub-gui:latest
|
||||
ghcr.io/jmbannon/ytdl-sub-gui:latest
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
In these examples, the configuration files will be at
|
||||
``<path/to/ytdl-sub/config>/config.yaml`` and
|
||||
``<path/to/ytdl-sub/config>/subscriptions.yaml``. Starting the container the first time
|
||||
will populate those files with default examples.
|
||||
|
|
|
|||
|
|
@ -12,5 +12,3 @@ ytdl-sub User Guide
|
|||
config_reference/index
|
||||
faq/index
|
||||
deprecation_notices
|
||||
|
||||
.. note:: The docs are heavily work-in-progress. Please bear with us while we're under construction!
|
||||
|
|
@ -8,10 +8,19 @@ What is ytdl-sub?
|
|||
.. _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).
|
||||
``ytdl-sub`` is a command-line tool that builds on and orchestrates `yt-dlp`_ to
|
||||
download media from YouTube and/or other online services. It provides a declarative,
|
||||
expressive YAML configuration system that allows you to describe which media to download
|
||||
and how it should appear in your media library servers and applications such as
|
||||
`Jellyfin`_, `Plex`_, `Emby`_, `Kodi`_, modern music players, etc..
|
||||
|
||||
Visual examples
|
||||
===============
|
||||
To these ends, ``ytdl-sub``:
|
||||
|
||||
- wraps and runs `yt-dlp`_, per your configuration to:
|
||||
- download the media, remux and/or optionally transcode it
|
||||
- prepares additional metadata both embedded and in external files
|
||||
- renames the resulting files
|
||||
- places them in your library
|
||||
|
||||
.. figure:: https://user-images.githubusercontent.com/10107080/182677243-b4184e51-9780-4094-bd40-ea4ff58555d0.PNG
|
||||
:alt: The Jellyfin web interface, showing the thumbnails of various YouTube shows.
|
||||
|
|
@ -34,10 +43,52 @@ Visual examples
|
|||
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.
|
||||
Motivation
|
||||
----------
|
||||
|
||||
`yt-dlp`_ has grown into a well maintained, central repository of the intricate,
|
||||
inscrutable, and extensive technical knowledge required to automate downloading media
|
||||
from online services. When those services change their APIs or otherwise change
|
||||
behavior, `yt-dlp`_ is the central, low-level tool to update. It does a best-in-class
|
||||
job at that task, and it does that job more effectively by narrowing focus to just that.
|
||||
As much knowledge as it encapsulates and as well as it does that, it still requires a
|
||||
great deal of additional knowledge to make its output accessible to end-users. Mostly
|
||||
this gap is about extracting and formatting metadata and correctly placing the resulting
|
||||
output files in a media library.
|
||||
|
||||
A number of tools, applications, and other projects have grown up around that central
|
||||
`yt-dlp`_ pillar to fill in those gaps, and this project was one of the early
|
||||
entrants. Many are `full-featured services that provide web UIs`_ including some that
|
||||
`provide media player web UIs`_. Most of those other projects necessarily narrow their
|
||||
scope to provide a more polished and integrated user experience.
|
||||
|
||||
Similarly, ``ytdl-sub`` can run automatically to accomplish the same goals, but aims to
|
||||
serve users that need lower-level control and/or have use cases not covered by the more
|
||||
narrow scope of those other projects. To some degree, this makes this project
|
||||
intrinsically less user friendly and requires more technical experience or learning.
|
||||
|
||||
Want something that "Just Works", try one of the other projects; we recommend
|
||||
`Pinchflat`_ as the next step towards that end. Want to download from more than just
|
||||
YouTube? Don't like the other restrictions inherent in the goals of those other
|
||||
projects? Have unique use cases? Then dig in, learn, and we hope ``ytdl-sub`` gives you
|
||||
enough rope and `a foot-gun`_ to get you there.
|
||||
|
||||
.. _`full-featured services that provide web UIs`:
|
||||
https://github.com/kieraneglin/pinchflat
|
||||
.. _`provide media player web UIs`:
|
||||
https://www.tubearchivist.com/
|
||||
.. _`Pinchflat`: `full-featured services that provide web UIs`_
|
||||
.. _`a foot-gun`: https://en.wiktionary.org/wiki/footgun
|
||||
|
||||
|
||||
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.
|
||||
|
||||
Most of the tools in this `yt-dlp`_ ecosystem serve a similar set of larger, more
|
||||
general use cases, and so does ``ytdl-sub``:
|
||||
|
||||
- Don't rely on profit-driven corporate persons to keep more obscure content available.
|
||||
- Even if they do, don't depend on them to make it possible to use it in different ways.
|
||||
- Even when you pay, don't count on them not inserting ads later.
|
||||
- Regardless, don't depend on them to curate content for yourself and/or your family.
|
||||
- Free yourself and/or your family from what the algorithm would feed them next.
|
||||
|
|
|
|||
Loading…
Reference in a new issue