Skip to content

2. Getting Started

Jump to bottom
Jesse Bannon edited this page Jul 29, 2023 · 18 revisions

First and foremost, ytdl-sub is a command-line tool. There are some prerequisites and a learning curve before you can use it to its full potential.

Prerequisites

  • Can navigate directories using the command-line
  • Have a basic understanding of YAML and/or JSON
    • Good explanation of YAML here
  • Not required, but is useful to know how yt-dlp works
  • For Docker + Unraid users...
    • Can use nano or vim to edit config files
      • unless you mount the /config dir somewhere you can open using other text-editing apps)

Installation

See the readthedocs install page on how to download and install ytdl-sub.

If you're savvy enough, installing ytdl-sub via docker is the recommended way because:

  • You can create a cron job to automatically download new videos from any yt-dlp supported link
  • Handles installing all dependencies (Python 3.10+, ffmpeg, etc)
  • Easy to update ytdl-sub to get bug fixes and new features

Understanding How ytdl-sub Works

Configuration

ytdl-sub uses two types of YAML files: config.yaml and subscriptions.yaml.

  • config.yaml file defines presets, which can be thought of as modular widgets to describe how you want downloaded media and metadata to look like.
  • subscriptions.yaml uses the presets defined in the config.yaml to specify things we want to recurrently download, like YouTube channels, playlists, SoundCloud artists, any yt-dlp supported link.

Downloading and Processing

In the config file, a working_directory must be defined. This is where ytdl-sub will initially download metadata and media files via yt-dlp. Once downloaded, it will process each media file using the specified preset, which can do a number of things including:

  • Renaming the media and thumbnail files
  • Add metadata to an audio file
  • Embed chapters into a video file
  • Moving it to a specified output directory
  • Generate an NFO file for each media file

We operate in the working_directory until all processing is complete, and the media files are ready to be moved to the output_directory. This helps prevent file pollution in case an error occurs.

Dry Run

As mentioned above, there is a learning curve to ytdl-sub. A lot of effort has been put in to creating a --dry-run flag which will simulate what your output files and metadata will look like without downloading (almost) anything. It is encouraged to use this flag to test any new changes to your config.yaml.

<<-- Part I: Introduction -- Previous -- | -- Next -- Part III: Creating Your First Config -->>

Clone this wiki locally