A simple, configurable, cross-platform youtube-dl wrapper for downloading and managing youtube audio (with added features).
- Requires Python3 (>=3.5), youtube-dl and ffmpeg/avconv as dependencies.
yt-audio can be installed via pip. Arch Linux users can use AUR as well.
$ [sudo] pip3 install --upgrade yt-audio
yt-audio is a command-line program that is used download and manage audio from youtube.com. It is a youtube-dl wrapper program, which means it uses youtube-dl as backend for downloading audio. yt-audio tries to make audio/playlist management easy for users. It is cross-platform (Windows/Linux/MacOS).
- Configure/Setup your own command-line arguments for managing titles/playlists (See usage below)
- Ability to save each audio/playlist to a different directory (directory specified in argument).
- Option to keep track of already-downloaded playlist titles with or without archive file.
- Manage single/playlist audio(s).
usage: yt-audio [OPTIONS] REQUIRED_ARGS
A simple, configurable youtube-dl wrapper for downloading and managing youtube audio.
Required Arguments (Any/all):
URL[::DIR] Video/Playlist URL with (optional) save directory [URL::dir]
-e, --example1 Example playlist [Custom]
--all All [Custom] Arguments
Optional Arguments:
-h, --help show this help message and exit
-v, --version show version and exit
--use-archive use archive file to track downloaded titles
--use-metadata use metadata to track downloaded titles
--output-format [OUTPUT_FORMAT]
File output format
--ytdl-args [YTDL_ADDITIONAL_ARGS]
youtube-dl additional arguments
yt-audio requires either URL or custom argument(s) (or both) as mandatory input(s).
yt-audio gives user the ability to setup their own custom arguments for managing/synchronizing audio/playlists. Custom arguments can be configured in yt-audio's (config.ini) configuration file.
IMPORTANT NOTE: The user, if required, will have to copy the configuration file as it is not copied during installation.
Unix/Linux Users: The default config location is $XDG_CONFIG_HOME/yt-audio/ directory. In case $XDG_CONFIG_HOME is not set, the file can be placed in $HOME/.config/yt-audio/ directory.
Windows Users: The default config location is C:\Users\<user>\.config\yt-audio
Setting up custom arguments
The config file config.ini has URL_LIST[] option where users can specify arguments with corresponding URL and (optional) save directory. It's format is as follows:
URL_LIST = [
# "['-short_arg1','--long_arg1','Help Text/Description']::URL::PATH"
# PATH (optional) specifies output directory for that particular playlist
# PATH should be absoulte directory path
# URL: Complete youtube title/playlist URL
# These arguments are visible in --help
# "['-e','--example1','Example playlist']::URL::PATH",
]
URL_LIST takes comma-separated string values. Each string value is formed from 3 components:
- CLI Argument - Argument to register. It is written in form: ['-short_arg','--long_arg','Help Text/Description']
- URL: Youtube playlist/title URL.
- PATH (optional): Path where this particular playlist/title will be saved. Provide absolute PATH here.
All custom arguments are visible in --help [$ yt-audio --help]
The default save PATH is $HOME/Music. PATH can be configured by user in config file (OUTPUT_DIRECTORY = <dir>). For playlists, one more directory of <PlaylistName> is created where all playlist records are saved.
yt-audio has an added feature of keeping track of audio files using file's metadata. This removes the requirement of additional archive file to store title(s) info (option provided by youtube-dl).
User can specify any of the two ways to keep track of downloaded titles. (By default, downloaded titles are not tracked)
Using File Metadata
To use file's metadata, pass --use-metadata argument to yt-audio. To use metadata everytime, you can set USE_METADATA = 1 in config file. Metadata method requires following to work:
--add-metadataargument to youtube-dl (--add-metadataargument is added by yt-audio by default. If you don't want this, you can re-configure youtube-dl command in config).
Known limitations of using metadata method
- I have tried this method with both MP3 and M4A format. MP3 works fine. M4a does not work.
Using Archive File
To use archive file method, pass --use-archive argument to yt-audio. To use archive file everytime with yt-audio, you can set USE_ARCHIVE = 1 in config file. This will create 'records.txt' file in title's download location.
--use-archive flag simply passes youtube-dl's --download-archive FILE argument to youtube-dl. You can pass your own filename to youtube-dl as well with --ytdl-args \"--download-archive FILE\". More info about '--ytdl-args' argument.
# Enable metadata
$ yt-audio --use-metadata [URL/custom_args]
# Enable archive file - creates records.txt file
$ yt-audio --use-archive [URL/custom_args]
# Enable archive file - creates archive.txt file
$ yt-audio --ytdl-args \"--download-archive FILE\" [URL/custom_args]
If both metadata and archive file are enabled, archive file method is used
User can also specify any arbitrary path for a particular playlist/title. This PATH can be specified as URL::PATH. If PATH is not provided, PATH from config file is used. If no path is present in config, $HOME/Music path is used
Downloaded file's output format can be specified with --output-format argument. Output Template. Default output format is "%(title)s.%(ext)s"
yt-audio gives user the flexibility to pass additional parameters to youtube-dl directly from command-line. Additional arguments can be provided with --ytdl-arguments yt-audio argument. Arguments passed to ytdl-arguments are passed as-it-is to youtube-dl.
$ yt-audio `--ytdl-args \"--download-archive FILE --user-agent UA\"`
NOTE: Make sure to escape double-quotes " when passing arguments to --ytdl-args. Else the arguments passed to --ytdl-args will be read as input arguments to yt-audio.
The commands used by yt-audio can be modified from config file. Unusual parameters might break the program. If the parameter is legit and should have (ideally) worked but it didn't, please raise an issue.
# Synchronizes/downloads --custom1 and --custom2 custom argument URLs and download specified URL as well.
$ yt-audio --custom1 --custom2 https://youtube.com/playlist?list=abcxyz
# Saves playlist to /my/path/p1/<PlaylistName>/ and single audio to /some/another/path
$ yt-audio https://youtube.com/playlist?list=abcxyz::/my/path/p1 https://www.youtube.com/watch?v=abcxyz::/some/another/path
# Adding additional youtube-dl arguments
# This will append additional arguments to youtube-dl download command
$ yt-audio --ytdl-args \"arg1 arg2\" https:youtube.com/abc https://youtube.com/xyz::DIR
# Different output format
$ yt-audio --output-format "%(display_id)s.%(ext)s" https://youtube.com/...
The following commands are used by yt-audio to download and manage audio. The commands are configurable using config file.
youtube-dl audio download
# (-x --print-json -o "$OUTPUT$" $URL$) are mandatory
$ youtube-dl -x --print-json --audio-format mp3 --audio-quality 0 --add-metadata --embed-thumbnail -o "$OUTPUT$" $URL$
get playlist/URL info
$ youtube-dl --flat-playlist -J $PLAYLIST_URL$
get file's metadata (used when downloaded titles are tracked using metadata)
$ ffprobe -v quiet -print_format json -show_format -hide_banner "$PATH$"
- Keeping track of downloaded tracks works with youtube.com only (for now).
Please create issue for the same. I'm open to suggestions as well :)
Feel free get in touch with me via Email.