Skip to content

2. Getting Started

Jump to bottom
Jesse Bannon edited this page Mar 2, 2023 · 18 revisions

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

Prerequisites

  • Comfortable using the command-line, can use nano or vim to edit config files
  • Can run a Docker image and access its container's console
  • Not required, but is useful to know how yt-dlp works

For having videos or music display in your media player/server...

  • Understand how your media player/server scrapes local files
  • Understand audio file metadata for music (id3v2.4, ogg, flac, etc)

Installation

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

Installing ytdl-sub via docker is the recommended way because:

  • You can easily create a cron job to automatically download new videos from YouTube channels, playlists, SoundCloud artists, etc
  • Handles installing all dependencies (Python 3.10+, ffmpeg, etc)
  • Can easily 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. The config file defines presets, which can be thought of as a template for how you want downloaded media and metadata to look like. The subscription file defines things we want to recurrently download, like YouTube channels, playlists, or SoundCloud artists.

Subscription files aren't necessarily required. You can perform a download on the command-line using the dl arg. This is ideal for downloading a single video or one-time things, like a playlist from a deceased artist.

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