yt - fine-tuning the use of youtube-dl

Download music or video from e.g. YouTube, Soundcloud, Instagram, Facebook. For a full list of supported sites and services, see https://github.com/ytdl-org/youtube-dl/blob/master/docs/supportedsites.md.

Description

yt is a pure-bash command-line tool that optimizes the use of youtube-dl for audio and videophiles with comprehensive and customizable presets, empirically tested on multiple streams. Maintains a download archive, to prevent duplicates when periodically downloading YouTube playlists or Soundcloud sets. Parses title ("%(artist)s - %(title)s") and retrieves a thumbnail, and injects these into file metadata. Adds the url id of the source to the filename, attempts to bypass geographical restrictions, and more.

Features include, but are not limited to:

• Parallel downloads
• Audio mode (default)
• Video mode (MKV -vcodec copy | MP4 AV1 | MP4 AVC)
• HDR video (MKV)
• Playlist mode (currently each playlist is download sequentially)
• Custom audio bitrate, video resolution, destination folder

The audio streams in converted (video) files from yt will generally be of higher quality compared to online alternatives, while maintaining a comparable file size. This is achieved by preferring WAV/OPUS source streams, and by converting using the Fraunhofer FDK AAC codec library at a bitrate of 256kbit/s (sufficient to encode a full 44.1kHz stream using libfdk_aac without losing detail at higher frequencies).

Installation

Dependencies are installations of youtube-dl, atomicparsley, and ffmpeg compiled using at least --with-fdk-aac (fdk-aac is GPL-incompatible, so this will produce an unredistributable distribution).

OSX

To install yt and its dependencies:

brew install ddelange/brewformulae/yt

Or manually (if you wish to avoid Homebrew, and install the dependencies yourself):

• Compile ffmpeg including --with-fdk-aac.
• Install youtube-dl.
• Install atomicparsley.
• Put yt in your path:

  git clone https://github.com/ddelange/yt.git ./yt
  cd ./yt && bash ./install.sh
  yt --help  # check that all is well

Debian/Ubuntu

On Linux, you can use Homebrew as well:

brew install ddelange/brewformulae/yt

Or manually (if you wish to avoid Homebrew, and install the dependencies yourself):

• Compile ffmpeg including --with-fdk-aac. See example instructions, pick your favorite: [1] [2]
• Install youtube-dl.
• Install atomicparsley.
• Put yt in your path:

  git clone https://github.com/ddelange/yt.git ./yt
  cd ./yt && bash ./install.sh
  yt --help  # check that all is well

Windows

Easiest would be using the Windows Subsystem for Linux (WSL), and using instructions above. But since youtube-dl has dedicated Windows distributions available, you could try the following:

[untested, assumes you're running Bash for Windows]

• Compile ffmpeg including the non-free tools (which will contain libfdk-aac).
• Install youtube-dl:
  • [either] Assuming python / python3 and pip / pip3 are installed, run sudo pip3 install youtube-dl or sudo pip3 install youtube-dl respectively.
  • [or] Download youtube-dl.exe and place it in any location on your PATH.
• Make sure youtube-dl is recognized by your shell by typing youtube-dl --version.
• Put yt in your path.

Usage

tl;dr:

• Type yt -h to print the following text and exit.
• Type yt to download audio files for the (space separated) URL(s) fetched from clipboard (see also -c).
• Type yt -vH -P 2160 do download best quality (4K HDR if available) into mkv.

NAME
      yt - fine-tuning the use of youtube-dl.  Download music or video from e.g.  YouTube,
      Soundcloud,  Instagram,  Facebook.  For a full list of supported sites and services,
      see https://github.com/ytdl-org/youtube-dl/blob/master/docs/supportedsites.md

SYNOPSIS
      yt [OPTIONS] [URL] [URL...]

DESCRIPTION
      yt is a bash function that optimizes the use of youtube-dl for audio and videophiles
      with comprehensive and customizable presets, empirically tested on multiple streams.
      Maintains a  download archive,  to prevent duplicates when  periodically downloading
      YouTube playlists or Soundcloud sets.  Parses title  ("%(artist)s - %(title)s")  and
      retrieves a thumbnail, and injects these into file metadata.  Adds the url id of the
      source to the filename, and attempts to bypass geographical restrictions.

      youtube-dl  is a command-line program to download videos from  YouTube.com  and many
      more sites.  It requires the Python interpreter, version 2.6, 2.7, or 3.2+,  and  it
      is not platform specific.  It should work on your Unix box,  on Windows or on macOS.
      It is released to the public domain,  which means you can modify it, redistribute it
      or use it however you like.

REQUIREMENTS
      installations  of  youtube-dl  (e.g. "brew install youtube-dl")  and ffmpeg compiled
      with --enable-libfdk-aac (e.g. "brew install ffmpeg --with-fdk-aac").

OPTIONS
      -h, --help
            Print this help text and exit.

      -U
            Update  youtube-dl  to latest  version  and  exit.  Make  sure  that  you have
            sufficient permissions (run with sudo if needed).

      -s
            Enable silent mode (send stdout to /dev/null).

      -S
            Enable sequential mode.  Default behaviour: parallel mode.  Each playlist will
            be downloaded sequentially as youtube-dl does not support parallel downloading
            of playlists (see #3746). The MAXPROCS (env) var sets parallelism (default 4).

      -v
            Enable video mode. Defaults to audio mode. Only mono and stereo are supported.

      -c
            Fetch space separated  URLs from clipboard,  additional to the manually passed
            URLs. Auto-enables when no URLs are manually passed.

      -D POSIX_PATH
            Set the destination path.  Used for both the (intermediate) output and for the
            download archive. Defaults to  "~/Music/yt"  and  "~/Movies/yt"  for audio and
            video mode respectively.

      -p
            Enable playlist mode. When the input URL contains reference to a playlist, the
            whole playlist will be  downloaded.  Will only download URLs that have not yet
            been recorded in the download archive.

      -k
            Keep original audio additionally.  In most cases, this will keep e.g. OPUS for
            YouTube, or LAME MP3 / WAV for Soundcloud URLs.  Ignored when -v is specified.

      -a KBITS_PER_SECOND
            Set the output audio bitrate. Defaults to 256kbit/s.

      -r HERTZ
            Set the output audio sampling rate. Defaults to 44100Hz.

      -P PIXELS
            Set the maximum height in pixels  of the video output.  Ignored when -v is not
            specified.  Defaults to 1080px.  Constraint is dropped when no formats comply.

      -m
            Use MP4 when merging audio/video streams, keeping video codecs if possible and
            converting audio to 256kbit/s AAC (resolving full 44.1KHz stream). If no merge
            is needed,  the (single) source file is kept  and no conversion is  performed.
            Default behaviour:  copy downloaded audio/video streams into an MKV container,
            using OPUS audio codec and  VP9 video codec for small filesizes.  Ignored when
            -v is not specified. For YouTube this will yield a maximum resolution of 1080.
            Sometimes,  AV1 streams will only be available up to a certain resolution.  In
            this case, specifying -M might yield higher resolution.

      -M
            Prefer the older AVC codec over AV1. Results in bigger file-sizes, but  better
            playback compatibility. Ignored when -v and -m are not specified.

      -H
            Prefer HDR streams. Tested on YouTube videos. Overrides -m.

BSD 3-Clause License

Copyright (c) 2019, ddelange
All rights reserved.