A TypeScript CLI for downloading YouTube videos as MP3 files. Supports batch downloads from a file, single video downloads by URL, and entire playlists.
- List Mode: Batch download multiple songs from
songs.txt(search by title or direct URL) - Direct Mode: Download a single video by URL
- Playlist Mode: Download all videos from a YouTube playlist
- Parallel downloads with configurable concurrency
- Node.js v18 or later
git clone https://github.com/TsuKpa/download-yt-mp3.git
cd download-yt-mp3
npm installnpm startChoose from a menu:
Select download mode:
1. Download from songs.txt
2. Direct by YouTube URL
3. Download entire playlist
Enter choice (1-3):
Download from songs.txt:
npm startWith a custom file and concurrency:
npm start -- --file my-songs.txt --concurrency 5Format of songs.txt:
Song Title 1
Song Title 2
https://www.youtube.com/watch?v=...
Song Title 3
# Comments are ignored
Download a single video:
npm start -- https://www.youtube.com/watch?v=dQw4w9WgXcQOr with a flag:
npm start -- --url https://www.youtube.com/watch?v=dQw4w9WgXcQDownload an entire playlist:
npm start -- --playlist https://www.youtube.com/playlist?list=PLxxxYou'll be prompted for:
- Folder name (for organization)
- Numeric prefix preference (e.g.,
1. Song.mp3,2. Song.mp3) - Starting number (if prefix is enabled)
| Option | Short | Description |
|---|---|---|
--file <path> |
-f |
Path to songs list (default: songs.txt) |
--concurrency <n> |
-c |
Max parallel downloads (default: 3) |
--url <url> |
Direct video URL | |
--playlist <url> |
Playlist URL | |
--help |
-h |
Show help message |
# Help
npm start -- --help
# List with 10 concurrent downloads
npm start -- -f songs.txt -c 10
# Direct download
npm start -- --url "https://www.youtube.com/watch?v=..."
# Set concurrency via environment
DOWNLOAD_CONCURRENCY=10 npm start- MP3 files:
downloads/ - Success log:
downloaded.log(tracks all successfully downloaded files with timestamps) - Error log:
errors.log
Each download shows real-time progress:
▓▓▓▓▓▓░░░░ 60% | Song Title Here
▓▓▓▓▓▓▓▓▓▓ 100% | Another Song
█░░░░░░░░░ 5% | Third Song
Summary at the end:
Download summary
┌───────┬────────────┬───────────┬─────────┬──────┐
│ ID │ Query │ Status │ Reason │ File │
├───────┼────────────┼───────────┼─────────┼──────┤
│ 1 │ Song 1 │ completed │ │ ... │
│ 2 │ Song 2 │ skipped │ Already │ ... │
│ 3 │ Song 3 │ failed │ Error │ │
└───────┴────────────┴───────────┴─────────┴──────┘
Totals => processed: 3, completed: 1, skipped: 1, failed: 1
License: MIT © TsuKpa