My Config File for Downloading Albums from YouTube Music
The Config File
Here’s the config file:
# yt-dlp.conf # Output format: album/tracks.format -o "%(album,playlist_title)U - [%(playlist_id)s]/%(track_number,playlist_index)s - %(title)U - [%(id)s].%(ext)s" --windows-filenames # --restrict-filenames # Extract audio -f bestaudio --extract-audio # Thumbnail squared --convert-thumbnails png --ppa "ThumbnailsConvertor+ffmpeg_o:-c:v png -vf crop=\"'if(gt(ih,iw),iw,ih)':'if(gt(iw,ih),ih,iw)'\"" --embed-thumbnail # Metadata, with playlist number as track number if the latter is missing --embed-metadata --parse-metadata "playlist_index:%(track_number)s" # Misc --no-overwrites --concurrent-fragments 4
The files are organized into one-directory-per-album, like the following:
... ├── Bach, J.S.： Sonatas & Partitas - [OLAK5uy_nd-ZT5mVVQ4tFm_6FsJWbj-u6GypaFYe8] │ ├── 01 - J.S. Bach： Sonata for Violin Solo No. 1 in G Minor, BWV 1001 - I. Adagio - [ZePaXgWY7-Q].opus │ ├── 02 - J.S. Bach： Sonata for Violin Solo No. 1 in G Minor, BWV 1001 - II. Fuga. Allegro - [93p59vL87cE].opus │ ├── 03 - J.S. Bach： Sonata for Violin Solo No. 1 in G Minor, BWV 1001 - III. Siciliana - [BRssao79MDM].opus │ ├── 04 - J.S. Bach： Sonata for Violin Solo No. 1 in G Minor, BWV 1001 - IV. Presto - [NP_LSvkqLjg].opus │ ├── 05 - J.S. Bach： Partita for Violin Solo No. 1 in B Minor, BWV 1002 - Ia. Allemanda - [4C8pA-8Hy8Q].opus │ ├── 06 - J.S. Bach： Partita for Violin Solo No. 1 in B Minor, BWV 1002 - Ib. Double - [vy43_64aax8].opus │ ├── 07 - J.S. Bach： Partita for Violin Solo No. 1 in B Minor, BWV 1002 - IIa. Corrente - [yiHc8-quDIc].opus ...
The output template:
"%(album,playlist_title)U - [%(playlist_id)s]/%(track_number,playlist_index)s - %(title)U - [%(id)s].%(ext)s"
yt-dlpto use the album’s name, and if that does not exist, use the playlist’s title, the trailing “U” indicating that the string should be normalized.
%(track_number,playlist_index)smeans that the file name begins with the track number, which makes it easier to sort the files, if the file manager or app is not metadata-aware.
%(title)Uis the title normalized.
%(ext)sis the extension.
%(playlist_id)sare the unique ID that YouTube assigns to the file and the playlist respectively, which might be useful if later I need to get more data from YouTube.
--restrict-filenamessanitizes the string of illegal characters. Some file systems support more characters than others, so in theory, it makes sense to err on the side of caution. However, this flag replaces all non-ASCII characters and even special ASCII characters with underscores, which is way too aggressive. While it makes file systems very happy, (an incompatibility is basically impossible), all titles, except the pure English ones, get mangled. “Dvořák” becomes “Dvor_k”, “Ysaÿe” now read “Ysa_e”, and some titles started making funny faces:
--windows-filenamesdoes exactly what it says on the tin: it makes the string Windows-compatible. I’d prefer if it is a little bit more aggressive, for instance, removing
&which some cloud drives don’t support, but it’s a good enough trade-off.
yt-dlp to embed metadata. Some albums don’t have the proper track number set up, which means that when you import the files into a music player, the order of the album gets scrambled up.
--parse-metadata "playlist_index:%(track_number)s" uses the playlist index, which should always be present when downloading a playlist, to fill the track number.
yt-dlpto embed a thumbnail;
--convert-thumbnails pngindicates that the format of the thumbnail should be
webpis possibly the best image format available in
yt-dlp, but its popularity being so recent, I’m wary of its compatibility with music players. Either
jpegshould be fine.
By default, YouTube provides a padded, rectangular image. To cut off the padding, we can use
ffmpeg in post-processing. In this Github Issue, pukkandan(2021) gave a solution:
--ppa "EmbedThumbnail+ffmpeg_o:-c:v mjpeg -vf crop=\"'if(gt(ih,iw),iw,ih)':'if(gt(iw,ih),ih,iw)'\"". But on my machine,
yt-dlp seems to ignore this instruction. Even with
--verbose turned on, I could see no log about cropping the thumbnail, and if I mangle the command deliberately, no error is produced, either. All I get is the same padded rectangular image in the end.
Supported PP are: Merger, ModifyChapters, SplitChapters, ExtractAudio, VideoRemuxer, VideoConvertor, Metadata, EmbedSubtitle, EmbedThumbnail, SubtitlesConvertor, ThumbnailsConvertor, FixupStretched, FixupM4a, FixupM3u8, FixupTimestamp and FixupDuration.
ThumbnailsConvertor must be the two relevant options, so I gave the latter a try:
--ppa "ThumbnailsConvertor+ffmpeg_o:-c:v png -vf crop=\"'if(gt(ih,iw),iw,ih)':'if(gt(iw,ih),ih,iw)'\"". And, hooray, it works!
My guess is that there’s some sort of conflict amongst the sequence of converting the image to the right format, embedding the image, and post-processing the image. In a way, I think it makes sense that thumbnail convertor post processor is the right option here, as it implies that we are processing after the conversion and before the embedding, whereas post-processing
EmbedThumbnail would suggest that we are cropping after the embedding occurs, which would be rather not useful. But this is just a speculation. Without digging into the code, it’s impossible to tell what exactly is happening here.
--no-overwrites: Don’t overwrite files.
--concurrent-fragments 4: Download 4 fragments concurrently to speed up the process.
pukkandan. (2021, June 23). Comment on [Feature Request] Crop to square thumbnail when embedding in MP3s. [Feature Request] Crop to square thumbnail when embedding in MP3s · Issue #429 · yt-dlp/yt-dlp · GitHub
yt-dlp. (2023). Yt-dlp [Python]. yt-dlp. GitHub - yt-dlp/yt-dlp: A youtube-dl fork with additional features and fixes (Original work published 2020)