A program to download playlists from YouTube and organise them automatically
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
This repo is archived. You can view files and clone it, but cannot push or open issues/pull-requests.
Mia Raindrops 34956c2d0f Add new file 12 months ago
.idea Commit 1 year ago
node_modules Commit 1 year ago
.DS_Store Commit 1 year ago
.gitignore Commit 1 year ago
.gitlab-ci.yml Add new file 12 months ago
README.md Commit 1 year ago
index.js Commit 1 year ago
lyrics.js Commit 1 year ago
package-lock.json Major update 1 year ago
package.json Even more fixes 1 year ago
youtoo Commit 1 year ago



YouToo takes a YouTube playlist ID, and:

  • downloads;
  • sorts;
  • syncs; and
  • adds metadata

to songs.


  • NodeJS 14 or later
  • ffmpeg
  • yt-dlp
  • ImageMagick


First, go to the folder where you downloaded the source code (the folder where the "index.js" file is located). Also make sure node, ffmpeg, yt-dlp and magick are in your PATH

Running npm install shouldn't be required, but if you encounter issues you may need to run it.

On Windows (PowerShell):

node .\index.js <your YouTube playlist ID> [album name]

On POSIX systems (Linux, macOS, *BSD, ...):

./youtoo <your YouTube playlist ID> [album name]

Argument [album name] is optional. If used, YouToo will make it so that all the songs belong to the same album rather than the auto-detected albums. Useful to keep playlists organized. To preserve compatibility with Plex (and some other media players), enabling this option will disable album art.

After running this command (and after waiting while it runs), you get the final audio files in ./_youtoo/Result, it is suggested that you keep these here for syncing to work (e.g. use a symbolic link).

How does it work?


Downloads are processed using regular yt-dlp commands. Audio is downloaded as an MPEG-4 audio file, and then transcoded into MPEG-3 when metadata is later added.


YouToo downloads songs in the order they are in your playlist. Although the final files are sorted alphabetically with their video ID, all the download process is done in your playlist's order.


When you give YouToo your playlist ID, it will check which songs have already been downloaded. If a song is already downloaded, it will ignore it. Additionally, if a song is downloaded locally but not in the playlist anymore, it will be deleted.


The trickiest part of YouToo. It will use a bunch of different regular expressions that have been tested against Minteck's playlists to grab the following information from the videos:

  • title;
  • artist(s);
  • album;
  • release date

It will first attempt to get this data from what YouTube gives, and eventually fall back to parsing the video title using regular expressions.

If the regular expressions doesn't correctly catch the title/artist(s)/album, please report an issue to this project to help improve accuracy. Make sure you embed the ./_youtoo/Metadata/<your video ID>.json file so we can have a look at what's wrong.

It will also fetch Genius to get lyrics, if possible. You need to use a media player that supports lyrics, such as Retro Music Player, VLC or Apple Music.


If you have issues running YouToo, follow these steps:

  1. update yt-dlp. YouTube's API change frequently, and yt-dlp is frequently updated. Make sure you always run the latest version to avoid issues.
  2. update NodeJS. We recommend using the latest stable release, or the latest long term support release. YouToo has been tested on NodeJS 17.3.0.
  3. free up disk space. Required disk space depends on the size of your playlist. To be safe, make sure you have 16MB per song.
  4. delete the ./_youtoo folder. This will completely reset YouToo, so in case a cache file is corrupted, it will all be reset. You may backup the ./_youtoo/Result folder if you don't want to have to download all the songs again.
  5. run npm install. This will update all dependencies and perhaps solve the issue.

If these steps didn't help you, open an issue to this project. We will be more than happy to help!