Skip to content

2. Getting Started

Jump to bottom
Jesse Bannon edited this page Aug 3, 2022 · 18 revisions

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

Prerequisites

  • Have a hosted media player/server
  • Understand how media players/servers scrape local files
    • NFO files for Kodi/Jellyfin videos
    • Audio file metadata (id3v2.4, ogg, flac, etc)
  • 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 ytdl(p) works

Installation

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

We highly recommend creating new directories for ytdl-sub media only. It is good practice to isolate things when you can. Most media servers and players support reading from multiple folders, so it should be no problem adding ytdl-sub media as a separate directory.

Docker Compose

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

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

Accessing the command-line

Once your ytdl-sub container is running, access its console using the following command:

docker exec -u abc -it ytdl-sub /bin/bash

abc is the name of the user created in the container with the PUID/GUID permissions. Exclude the -u abc portion of the command if you want to access the console as root.

Improving the console experience

When you first enter the console, you will notice you arrive in the root directory. Also, when you ls, there are no colors! Let's fix both of these issues by creating /config/.bashrc:

# Enter /config directory when logging in
cd

# Add colors to ls
alias ls='ls --color=auto'

Understanding How ytdl-sub Works

Configuration

ytdl-sub uses two types of YAML files: config.yaml and subscriptions.yaml. The config file defines what we call presets which can be thought of as a template for how you want downloaded media and metadata to look like. The subscriptions 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.

Clone this wiki locally