A simple, configurable youtube-dl wrapper to download and manage youtube audio (with added features)
A simple, configurable, cross-platform youtube-dl wrapper for downloading and managing youtube audio (with added features).
$ [sudo] pip3 install --upgrade yt-audio
Description and Features
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: YTAudio.py [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.
NOTE (pip users): 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.
Keeping track of downloaded titles/playlists
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
Changing output format
Downloaded file's output format can be specified with
--output-format argument. Output Template. Default output format is
Passing additional paramaters to youtube-dl
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.
Modifying default youtube-dl/helper commands
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 :)
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.