YouTube CLI Downloader

A simple command-line tool to download YouTube videos and playlists as MP4 in various qualities or MP3. Built on top of yt-dlp and FFmpeg.

Thanks to AmirHaytham/youtube_playlist_downloader, which served as the foundation for this project.

Features

• Download single YouTube videos or entire playlists
• Choose from all available resolutions, up to 4K*
• Auto-select the highest quality available per video
• Download audio-only as MP3 at maximum quality
• Automatically merges video and audio into a single file using FFmpeg
• Embeds metadata (title, artist, etc.) and thumbnails into downloaded files
• Live progress bar with speed and ETA during download

4K availability depends on the source video and your yt-dlp version.

Requirements

Make sure the following are installed before running the script:

• Node.js (v16 or higher)
• yt-dlp
• FFmpeg
• Python (required by yt-dlp)

Installation

1. Verify Prerequisites

Before anything else, confirm that Node.js and Python are installed correctly. Open a terminal and run:

node -v
npm -v
python --version

If any of these commands fail, install the missing tool first:

• Node.js: nodejs.org
• Python: python.org - make sure to check "Add Python to PATH" during installation

2. Clone the Repository

git clone https://github.com/itsmarianmc/youtube-cli-downloader.git
cd youtube-cli-downloader

3. Install yt-dlp

Visit the yt-dlp releases page and download yt-dlp.exe.

Place it in a directory of your choice, for example:

C:\yt-dlp\yt-dlp.exe

4. Install FFmpeg

Visit the FFmpeg download page and download a Windows build. A reliable source is gyan.dev.

Extract the archive and locate the bin folder inside. Place it somewhere accessible, for example:

C:\ffmpeg\bin\

The bin folder should contain ffmpeg.exe, ffprobe.exe, and ffplay.exe.

5. Configure the Script

Open ycd.js and update the paths at the top of the file to match where you placed yt-dlp and FFmpeg:

const ytDlpPath = 'C:\\yt-dlp\\yt-dlp.exe';
const ffmpegPath = 'C:\\ffmpeg\\bin';

Make sure to use double backslashes (\\) in the paths.

Downloaded files are saved to a ./downloads folder next to the script. This folder is created automatically on first run.

Usage

Open a terminal in the project folder and run:

node ycd.js

You will be prompted to enter a YouTube URL. Paste the URL of a single video or a playlist and press Enter.

The script will fetch all available resolutions and display them in a numbered list.

Enter the number for your preferred option and the download will begin.

MP4 downloads the selected video and audio streams separately, then merge them into a single .mp4 file using FFmpeg.

MP3 downloads extract the audio track, convert it to MP3 at maximum quality (VBR 0), and embed metadata and the video thumbnail into the file.

Playlists

Playlist downloads are supported, but there are a few things to keep in mind:

• Only public playlists from regular YouTube channels work reliably
• YouTube Mix playlists (auto-generated radio-style playlists) are not supported
• Private playlists from your own account cannot be downlaoded
• For playlists, selecting the highest quality option is recommended, since a specific resolution (e.g. 1080p) may not be available for every video in the list, which can cause individual downloads to fail or fall back to a lower quality

Legal Notice

This tool is provided for personal and educational use only. By using it, you agree to take full responsibility for how you use it and what you download.

Copyright and Intellectual Property

The vast majority of content on YouTube is protected by copyright law. Downloading, reproducing, distributing, or repurposing copyrighted videos, music, films, podcasts, or any other media without the explicit permission of the rights holder is illegal in most countries and constitutes a violation of those rights.

What You May Download

You may use this tool to download:

• Videos you have uploaded yourself
• Content explicitly released under a Creative Commons or other open license that permits downloading and redistribution
• Content for which you have received direct, written permission from the rights holder
• Content that is clearly in the public domain

When in doubt, please do not download it.

No Liability

The author of this tool, itsmarian, provides this software as-is, without any warranties or guarantees. The author is not responsible for any legal consequences, damages, or account actions that result from the use or misuse of this tool. This tool is a technical interface to yt-dlp and FFmpeg - it does not bypass DRM, does not circumvent platform security, and does not encourage illegal activity.

It is your sole responsibility to ensure that your use of this tool complies with the laws of your country and the terms of any platform you interact with.

License

MIT © 2026 itsmarian