ytmdl

Download a song by name (with interactive selection)

$ ytmdl [song_name]

$ ytmdl [[-q|--quiet]] [song_name]

$ ytmdl [[-o|--output-dir]] [path/to/directory] [song_name]

$ ytmdl --url https://www.youtube.com/watch?v=[oHg5SJYRHA0]

$ ytmdl --format [mp3|m4a|opus] [song_name]

$ ytmdl --artist [artist_name] --album [album_name] [song_name]

$ ytmdl --list [path/to/list.txt]

$ ytmdl [[-h|--help]]

ytmdl [OPTIONS] <SEARCH_QUERY_OR_URL ...>

-u, --url <URL>
    Download music from a specific YouTube URL.

-p, --playlist <URL>
    Download all songs from a given YouTube playlist URL.

--artist <ARTIST_NAME>
    Specify the artist name for better search results and metadata accuracy.

--album <ALBUM_NAME>
    Specify the album name for better search results and metadata accuracy.

--title <TITLE_NAME>
    Specify the song title for better search results and metadata accuracy.

--format <FORMAT>
    Specify the output audio format (e.g., mp3, flac, m4a, opus).

-o, --output <DIRECTORY>
    Specify the directory where the downloaded music files will be saved.

-m, --disable-metadata
    Disable embedding of metadata (tags and album art) into the downloaded audio file.

--disable-album-art
    Prevent embedding album art into the downloaded file, even if metadata is enabled.

--lyrics
    Embed lyrics into the downloaded audio file if available from metadata sources.

--choice
    Present a list of search results and allow the user to choose the desired song interactively.

--add-args <ARGS>
    Pass additional arguments directly to the underlying yt-dlp command.

--download-archive <FILE>
    Use a file to record downloaded video IDs, preventing re-downloading of already processed videos.

-v, --version
    Display the ytmdl version and exit.

-h, --help
    Show the help message and exit.

ytmdl is a powerful command-line utility for Linux, designed to download music from YouTube with comprehensive metadata and high-quality album art. It serves as a frontend to the robust yt-dlp (or youtube-dl) project, leveraging its ability to extract audio from YouTube videos. Beyond simple downloading, ytmdl intelligently fetches and embeds crucial metadata such as song title, artist, album, and genre from various online sources like Last.fm, Spotify, and MusicBrainz. It also automatically searches for and embeds album artwork, providing a complete and organized music file.

Users can specify search queries, YouTube URLs, or even entire playlists. It offers extensive customization options, including output format, bitrate, proxy support, and the ability to embed lyrics. The tool aims to provide a seamless experience for curating a local music library directly from YouTube, ensuring downloaded tracks are well-tagged and ready for any music player.

ytmdl relies heavily on external dependencies like yt-dlp (or youtube-dl), ffmpeg, and ffprobe. Breakages can occur if YouTube's website changes or if these dependencies are not installed or are outdated. Users should be aware of YouTube's terms of service regarding content downloading. Metadata fetching relies on third-party services, and occasional inconsistencies or rate limits may occur. It also requires a Python environment to run.

ytmdl requires several external tools to function correctly:

• Python: For the script itself.
• yt-dlp (or youtube-dl): For video extraction and downloading.
• ffmpeg/ffprobe: For audio conversion, trimming, and metadata embedding.

For persistent settings, ytmdl supports a configuration file, typically located at ~/.config/ytmdl/config.json or ~/.ytmdl/config.json. This file allows users to define default values for options like output directory, preferred format, bitrate, and metadata preferences, avoiding the need to specify them with every command.

ytmdl originated as a Python-based command-line tool, initially designed to simplify downloading YouTube music with embedded metadata. It gained traction for its user-friendly interface and robust metadata capabilities. Over time, it transitioned its primary backend from youtube-dl to yt-dlp to benefit from yt-dlp's more active development and better handling of YouTube changes. The project continues to be maintained, with ongoing improvements in metadata accuracy, download reliability, and feature additions like playlist support and interactive selection.

yt-dlp(1), ffmpeg(1)